From 7cdf1d4e7b93a3b1017fe914b8c0faa4574d3215 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Fri, 23 Oct 2026 11:28:40 -0700
Subject: [PATCH 01/20] chore(node): start the posthog-node 6 capture v1
 release branch

---
 .changeset/posthog-node-capture-v1.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/posthog-node-capture-v1.md

diff --git a/.changeset/posthog-node-capture-v1.md b/.changeset/posthog-node-capture-v1.md
new file mode 100644
index 0000000000..c74d172a8a
--- /dev/null
+++ b/.changeset/posthog-node-capture-v1.md
@@ -0,0 +1,5 @@
+---
+'posthog-node': major
+---
+
+Send events only through capture v1, with AI events on their own lane. See the 6.0 migration guide.

From c716deb6ce8ed5e16229309f27f56e5bc6830efd Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Mon, 26 Oct 2026 20:43:36 -0700
Subject: [PATCH 02/20] test(node): read capture events from either wire format
 (#5414)

* test(node): read capture events from either wire format

Add shared helpers that find analytics capture requests on the legacy
/batch/ endpoint or the capture v1 analytics endpoint, and return their
events in the legacy shape. A v1 event's options, session and window
ids and SDK info header map back to the properties they replace, so one
assertion holds for both formats.

Port the tests that read events off the wire to these helpers, and
answer capture requests with a body that both senders accept. The same
tests pass on the legacy default and with POSTHOG_CAPTURE_MODE=v1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(ai): accept capture v1 requests in the cassette collector

The collector accepted only the legacy /batch/ request. It now also
accepts the capture v1 analytics and AI endpoints with a bearer token,
and returns their events in the legacy shape, so the replay tests hold
for both wire formats.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(convex): read example events from either capture endpoint

The example tests read events only from /batch/ calls and checked the
api_key in the body. Read them from the legacy or the capture v1
analytics endpoint, and accept the project key from the body or the
bearer token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(convex): give the sequenced fetch mock the headers field its type requires

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../example-convex/convex/example.test.ts     |  61 ++++-----
 packages/ai/harness/collector.test.ts         | 121 +++++++++++++-----
 packages/ai/harness/collector.ts              |  72 +++++++++--
 .../node/src/__tests__/bot-detection.spec.ts  |  76 ++++++-----
 .../capture-v1/route-isolation.spec.ts        |   3 +-
 .../src/__tests__/capture-v1/wiring.spec.ts   |   3 +-
 packages/node/src/__tests__/context.spec.ts   |  34 +----
 .../node/src/__tests__/edge-exports.spec.ts   |  13 +-
 .../src/__tests__/extensions/express.spec.ts  |  16 +--
 .../src/__tests__/extensions/nestjs.spec.ts   |  25 +---
 .../extensions/sentry-integration.spec.ts     |  23 +---
 .../node/src/__tests__/posthog-node.spec.ts   |  96 +++++---------
 .../__tests__/server-wire-snapshots.spec.ts   |   3 +-
 packages/node/src/__tests__/utils/index.ts    | 108 +++++++++++++---
 .../node/src/__tests__/utils/v1-wiring.ts     |  14 +-
 .../src/__tests__/waituntil-flush.spec.ts     |  48 ++-----
 16 files changed, 388 insertions(+), 328 deletions(-)

diff --git a/examples/example-convex/convex/example.test.ts b/examples/example-convex/convex/example.test.ts
index 64e8629dde..31f9043e3b 100644
--- a/examples/example-convex/convex/example.test.ts
+++ b/examples/example-convex/convex/example.test.ts
@@ -6,21 +6,24 @@ import { api, components } from './_generated/api.js'
 // Keep a guard above Jest's 5s default; scheduled functions are driven deterministically below.
 vi.setConfig({ testTimeout: 15000 })
 
+// posthog-node sends events to the legacy `/batch/` endpoint or the capture v1 analytics endpoint.
+const CAPTURE_PATHS = ['/batch/', '/i/v1/analytics/events']
+
 // Collect all fetch calls for assertion
-let fetchCalls: Array<{ url: string; body: unknown }> = []
+let fetchCalls: Array<{ url: string; headers: Record<string, string>; body: unknown }> = []
 const originalFetch = global.fetch
 
 function mockFetch(responseByUrl?: Record<string, unknown>, statusByUrl?: Record<string, number>) {
     fetchCalls = []
     return vi.fn(async (url: string | URL, init?: RequestInit) => {
         const urlStr = url.toString()
+        const headers = (init?.headers ?? {}) as Record<string, string>
         const status = Object.entries(statusByUrl ?? {}).find(([pattern]) => urlStr.includes(pattern))?.[1] ?? 200
         let body: unknown
         if (init?.body) {
             let rawText: string
             if (init.body instanceof Blob) {
-                const headers = init.headers as Record<string, string> | undefined
-                if (headers?.['Content-Encoding'] === 'gzip') {
+                if (headers['Content-Encoding'] === 'gzip') {
                     const ds = new DecompressionStream('gzip')
                     rawText = await new Response(init.body.stream().pipeThrough(ds)).text()
                 } else {
@@ -35,7 +38,7 @@ function mockFetch(responseByUrl?: Record<string, unknown>, statusByUrl?: Record
                 body = rawText
             }
         }
-        fetchCalls.push({ url: urlStr, body })
+        fetchCalls.push({ url: urlStr, headers, body })
 
         if (responseByUrl) {
             for (const [pattern, response] of Object.entries(responseByUrl)) {
@@ -56,7 +59,17 @@ function mockFetch(responseByUrl?: Record<string, unknown>, statusByUrl?: Record
 }
 
 function batchCalls() {
-    return fetchCalls.filter((c) => c.url.includes('/batch'))
+    return fetchCalls.filter((c) => CAPTURE_PATHS.some((path) => new URL(c.url).pathname === path))
+}
+
+// The project key travels as `api_key` in a legacy body and as a bearer token in capture v1.
+function apiKeyOf(call: (typeof fetchCalls)[number]): string | undefined {
+    return (call.body as { api_key?: string }).api_key ?? call.headers.Authorization?.replace(/^Bearer /, '')
+}
+
+// Fails every capture request with `status`, whichever endpoint the client uses.
+function captureStatus(status: number): Record<string, number> {
+    return Object.fromEntries(CAPTURE_PATHS.map((path) => [path, status]))
 }
 
 function flagsCalls() {
@@ -71,9 +84,7 @@ function firstBatchEvent(): Record<string, unknown> {
 }
 
 function allBatchEvents(): Record<string, unknown>[] {
-    return batchCalls().flatMap(
-        (call) => (call.body as { batch: Record<string, unknown>[] }).batch
-    )
+    return batchCalls().flatMap((call) => (call.body as { batch: Record<string, unknown>[] }).batch)
 }
 
 async function finishScheduledFunctions(t: ReturnType<typeof initConvexTest>) {
@@ -110,8 +121,7 @@ describe('capture', () => {
         await finishScheduledFunctions(t)
 
         expect(batchCalls().length).toBeGreaterThanOrEqual(1)
-        const batch = batchCalls()[0].body as { api_key: string }
-        expect(batch.api_key).toBe('phc_test_key')
+        expect(apiKeyOf(batchCalls()[0])).toBe('phc_test_key')
 
         const event = firstBatchEvent()
         expect(event.distinct_id).toBe('user-123')
@@ -483,7 +493,9 @@ describe('getFeatureFlag (local eval)', () => {
                     filters: {
                         groups: [
                             {
-                                properties: [{ key: 'email', value: ['user@acme.com'], operator: 'exact', type: 'person' }],
+                                properties: [
+                                    { key: 'email', value: ['user@acme.com'], operator: 'exact', type: 'person' },
+                                ],
                                 rollout_percentage: 100,
                             },
                         ],
@@ -786,9 +798,7 @@ describe('getAllFlags (local eval)', () => {
     })
 
     test('respects flagKeys filter', async () => {
-        global.fetch = mockFetch(
-            definitionsResponse([flagDef('flag-a'), flagDef('flag-b'), flagDef('flag-c')])
-        )
+        global.fetch = mockFetch(definitionsResponse([flagDef('flag-a'), flagDef('flag-b'), flagDef('flag-c')]))
         const t = initConvexTest()
         await loadDefinitions(t)
 
@@ -872,15 +882,13 @@ describe('refreshFlagDefinitions cron action', () => {
     const noArgs = {}
 
     /** Builds a fetch mock whose responses are picked per call from the supplied sequence. */
-    function sequencedFetch(
-        responses: Array<{ status: number; body?: unknown; headers?: Record<string, string> }>
-    ) {
+    function sequencedFetch(responses: Array<{ status: number; body?: unknown; headers?: Record<string, string> }>) {
         fetchCalls = []
         let i = 0
         // Statuses where the spec forbids a body (Response constructor throws on non-null body).
         const NULL_BODY_STATUSES = new Set([101, 103, 204, 205, 304])
         return vi.fn(async (url: string | URL) => {
-            fetchCalls.push({ url: url.toString(), body: undefined })
+            fetchCalls.push({ url: url.toString(), headers: {}, body: undefined })
             const r = responses[Math.min(i, responses.length - 1)]
             i++
             const payload =
@@ -964,9 +972,7 @@ describe('refreshFlagDefinitions cron action', () => {
         await t.action(components.posthog.lib.refreshFlagDefinitions, noArgs)
 
         // Now PostHog flaps cold-cache 503s. Cache is < 5min old so we keep what we have.
-        global.fetch = sequencedFetch([
-            { status: 503, body: 'Required data not found in cache.' },
-        ])
+        global.fetch = sequencedFetch([{ status: 503, body: 'Required data not found in cache.' }])
         const result = (await t.action(components.posthog.lib.refreshFlagDefinitions, noArgs)) as {
             status: string
         }
@@ -988,9 +994,7 @@ describe('refreshFlagDefinitions cron action', () => {
             // Jump 6 minutes forward; the cached defs now count as stale.
             vi.setSystemTime(new Date(Date.now() + 6 * 60 * 1000))
 
-            global.fetch = sequencedFetch([
-                { status: 503, body: 'Required data not found in cache.' },
-            ])
+            global.fetch = sequencedFetch([{ status: 503, body: 'Required data not found in cache.' }])
             const result = (await t.action(components.posthog.lib.refreshFlagDefinitions, noArgs)) as {
                 status: string
             }
@@ -1101,7 +1105,7 @@ describe('evaluateFlag (remote)', () => {
     })
 
     test('returns the flag value when telemetry fails', async () => {
-        global.fetch = mockFetch(flagsResponse({ 'test-flag': 'variant-a' }), { '/batch': 400 })
+        global.fetch = mockFetch(flagsResponse({ 'test-flag': 'variant-a' }), captureStatus(400))
         const t = initConvexTest()
 
         const value = await t.action(components.posthog.lib.evaluateFlag, {
@@ -1198,10 +1202,7 @@ describe('evaluateAllFlags (remote)', () => {
 
     test('returns all flags and payloads', async () => {
         global.fetch = mockFetch(
-            flagsResponse(
-                { 'flag-a': true, 'flag-b': 'variant', 'flag-c': false },
-                { 'flag-a': { config: 'value' } }
-            )
+            flagsResponse({ 'flag-a': true, 'flag-b': 'variant', 'flag-c': false }, { 'flag-a': { config: 'value' } })
         )
         const t = initConvexTest()
 
@@ -1220,7 +1221,7 @@ describe('evaluateAllFlags (remote)', () => {
     })
 
     test('returns all flags when telemetry fails', async () => {
-        global.fetch = mockFetch(flagsResponse({ 'flag-a': true }), { '/batch': 400 })
+        global.fetch = mockFetch(flagsResponse({ 'flag-a': true }), captureStatus(400))
         const t = initConvexTest()
 
         const result = await t.action(components.posthog.lib.evaluateAllFlags, {
diff --git a/packages/ai/harness/collector.test.ts b/packages/ai/harness/collector.test.ts
index b550b43855..17f3855cd7 100644
--- a/packages/ai/harness/collector.test.ts
+++ b/packages/ai/harness/collector.test.ts
@@ -2,43 +2,102 @@ import { gzipSync } from 'node:zlib'
 import { expect, it } from 'vitest'
 import { startCollector } from './collector'
 
-it.each(['$ai_generation', '$ai_embedding'])(
-  'accepts compressed %s analytics and retains decode failures',
-  async (eventName) => {
-    const collector = await startCollector()
-    try {
-      const event = { event: eventName, distinct_id: 'test', properties: {} }
-      const response = await fetch(`${collector.url}/batch/`, {
-        method: 'POST',
-        headers: { 'content-encoding': 'gzip' },
-        body: gzipSync(JSON.stringify({ api_key: 'phc_cassette_test', batch: [event] })),
-      })
-      expect(response.status).toBe(200)
-      expect(collector.events).toEqual([event])
-      collector.verify()
-      const invalid = await fetch(`${collector.url}/batch/`, {
-        method: 'POST',
-        headers: { 'content-encoding': 'gzip' },
-        body: 'not gzip',
-      })
-      expect(invalid.status).toBe(500)
-      expect(() => collector.verify()).toThrow('Analytics collector failed')
-    } finally {
-      await collector.close()
-    }
+const AUTH = { authorization: 'Bearer phc_cassette_test' }
+
+function legacyBody(batch: unknown[]): string {
+  return JSON.stringify({ api_key: 'phc_cassette_test', batch })
+}
+
+function v1Body(batch: unknown[]): string {
+  return JSON.stringify({ created_at: '2026-01-01T00:00:00.000Z', batch })
+}
+
+function v1Event(event: string, options: Record<string, unknown> = {}) {
+  return {
+    event,
+    uuid: '01890000-0000-7000-8000-000000000000',
+    distinct_id: 'test',
+    timestamp: '2026-01-01T00:00:00.000Z',
+    session_id: 'session-1',
+    options,
+    properties: {},
+  }
+}
+
+it.each([
+  ['$ai_generation', '/batch/'],
+  ['$ai_embedding', '/batch/'],
+  ['$ai_generation', '/i/v1/ai/events'],
+  ['$ai_embedding', '/i/v1/ai/events/'],
+  ['$ai_generation', '/i/v1/analytics/events'],
+])('accepts compressed %s analytics on %s and retains decode failures', async (eventName, path) => {
+  const collector = await startCollector()
+  try {
+    const legacy = path === '/batch/'
+    const body = legacy
+      ? legacyBody([{ event: eventName, distinct_id: 'test', properties: {} }])
+      : v1Body([v1Event(eventName)])
+    const response = await fetch(`${collector.url}${path}`, {
+      method: 'POST',
+      headers: { ...AUTH, 'content-encoding': 'gzip' },
+      body: gzipSync(body),
+    })
+    expect(response.status).toBe(200)
+    expect(collector.events).toEqual([
+      legacy
+        ? { event: eventName, distinct_id: 'test', properties: {} }
+        : {
+            event: eventName,
+            uuid: '01890000-0000-7000-8000-000000000000',
+            distinct_id: 'test',
+            timestamp: '2026-01-01T00:00:00.000Z',
+            properties: { $session_id: 'session-1' },
+          },
+    ])
+    collector.verify()
+    const invalid = await fetch(`${collector.url}${path}`, {
+      method: 'POST',
+      headers: { ...AUTH, 'content-encoding': 'gzip' },
+      body: 'not gzip',
+    })
+    expect(invalid.status).toBe(500)
+    expect(() => collector.verify()).toThrow('Analytics collector failed')
+  } finally {
+    await collector.close()
   }
-)
+})
 
-it('rejects non-AI events', async () => {
+it('reads capture v1 options as the legacy properties they replace', async () => {
   const collector = await startCollector()
   try {
-    const response = await fetch(`${collector.url}/batch/`, {
+    const response = await fetch(`${collector.url}/i/v1/analytics/events`, {
       method: 'POST',
-      body: JSON.stringify({
-        api_key: 'phc_cassette_test',
-        batch: [{ event: '$pageview', distinct_id: 'test', properties: {} }],
-      }),
+      headers: AUTH,
+      body: v1Body([v1Event('$ai_generation', { process_person_profile: false })]),
     })
+    expect(response.status).toBe(200)
+    expect(collector.events[0].properties).toEqual({ $session_id: 'session-1', $process_person_profile: false })
+    collector.verify()
+  } finally {
+    await collector.close()
+  }
+})
+
+it.each([
+  ['non-AI events', '/batch/', {}, legacyBody([{ event: '$pageview', distinct_id: 'test', properties: {} }])],
+  ['non-AI v1 events', '/i/v1/ai/events', AUTH, v1Body([v1Event('$pageview')])],
+  ['a missing bearer token', '/i/v1/ai/events', {}, v1Body([v1Event('$ai_generation')])],
+  ['a legacy body on a v1 endpoint', '/i/v1/ai/events', AUTH, legacyBody([])],
+  [
+    'v1 events without v1 fields',
+    '/i/v1/ai/events',
+    AUTH,
+    v1Body([{ event: '$ai_generation', distinct_id: 'test', properties: {} }]),
+  ],
+])('rejects %s', async (_name, path, headers, body) => {
+  const collector = await startCollector()
+  try {
+    const response = await fetch(`${collector.url}${path}`, { method: 'POST', headers, body })
     expect(response.status).toBe(500)
     expect(collector.events).toHaveLength(0)
     expect(() => collector.verify()).toThrow('Analytics collector failed')
diff --git a/packages/ai/harness/collector.ts b/packages/ai/harness/collector.ts
index 0d69765c8d..a8e6d17bda 100644
--- a/packages/ai/harness/collector.ts
+++ b/packages/ai/harness/collector.ts
@@ -1,8 +1,57 @@
-import { createServer } from 'node:http'
+import { createServer, type IncomingHttpHeaders } from 'node:http'
 import { gunzipSync } from 'node:zlib'
 
+const API_KEY = 'phc_cassette_test'
+const LEGACY_CAPTURE_PATH = '/batch/'
+const V1_CAPTURE_PATHS = new Set(['/i/v1/analytics/events', '/i/v1/ai/events'])
+
+// Capture v1 per-event `options`, keyed by the legacy property each one replaces.
+const V1_OPTION_PROPERTIES: Record<string, string> = {
+  cookieless_mode: '$cookieless_mode',
+  disable_skew_correction: '$ignore_sent_at',
+  process_person_profile: '$process_person_profile',
+  product_tour_id: '$product_tour_id',
+}
+
+type CollectedEvent = { event: string; distinct_id: string; properties: Record<string, unknown> }
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** One capture v1 event in the legacy `/batch/` shape, so assertions hold for both wire formats. */
+function toLegacyEvent(item: unknown): unknown {
+  if (
+    !isObject(item) ||
+    typeof item.uuid !== 'string' ||
+    typeof item.timestamp !== 'string' ||
+    !isObject(item.options) ||
+    !isObject(item.properties)
+  )
+    throw new Error('Unexpected analytics event')
+  const { options, session_id, window_id, properties, ...event } = item
+  const legacyProperties: Record<string, unknown> = { ...properties }
+  for (const [option, value] of Object.entries(options))
+    legacyProperties[V1_OPTION_PROPERTIES[option] ?? option] = value
+  if (session_id !== undefined) legacyProperties.$session_id = session_id
+  if (window_id !== undefined) legacyProperties.$window_id = window_id
+  return { ...event, properties: legacyProperties }
+}
+
+/** The events of one capture request, from either the legacy `/batch/` or the capture v1 wire format. */
+function readEvents(isLegacy: boolean, headers: IncomingHttpHeaders, payload: Record<string, unknown>): unknown[] {
+  if (isLegacy) {
+    if (payload.api_key !== API_KEY || !Array.isArray(payload.batch)) throw new Error('Invalid analytics payload')
+    return payload.batch
+  }
+  if (headers.authorization !== `Bearer ${API_KEY}`) throw new Error('Invalid analytics credentials')
+  if (typeof payload.created_at !== 'string' || !Array.isArray(payload.batch))
+    throw new Error('Invalid analytics payload')
+  return payload.batch.map(toLegacyEvent)
+}
+
 export async function startCollector() {
-  const events: Array<{ event: string; distinct_id: string; properties: Record<string, unknown> }> = []
+  const events: CollectedEvent[] = []
   const errors: Error[] = []
   const server = createServer(async (request, response) => {
     try {
@@ -10,7 +59,9 @@ export async function startCollector() {
         response.end(JSON.stringify({ count: events.length }))
         return
       }
-      if (request.method !== 'POST' || request.url !== '/batch/') throw new Error('Unexpected collector request')
+      const isLegacy = request.url === LEGACY_CAPTURE_PATH
+      const isV1 = V1_CAPTURE_PATHS.has(request.url?.replace(/\/$/, '') ?? '')
+      if (request.method !== 'POST' || (!isLegacy && !isV1)) throw new Error('Unexpected collector request')
       const chunks: Buffer[] = []
       let size = 0
       for await (const chunk of request) {
@@ -23,18 +74,19 @@ export async function startCollector() {
       if (encoding && encoding !== 'gzip') throw new Error('Unsupported collector encoding')
       const bytes = encoding === 'gzip' ? gunzipSync(compressed, { maxOutputLength: 1024 * 1024 }) : compressed
       const payload = JSON.parse(bytes.toString('utf8'))
-      if (payload.api_key !== 'phc_cassette_test' || !Array.isArray(payload.batch))
-        throw new Error('Invalid analytics payload')
-      for (const item of payload.batch) {
+      if (!isObject(payload)) throw new Error('Invalid analytics payload')
+      for (const item of readEvents(isLegacy, request.headers, payload)) {
         if (
-          !['$ai_generation', '$ai_embedding'].includes(item.event) ||
+          !isObject(item) ||
+          !['$ai_generation', '$ai_embedding'].includes(item.event as string) ||
           typeof item.distinct_id !== 'string' ||
-          !item.properties
+          !isObject(item.properties)
         )
           throw new Error('Unexpected analytics event')
-        events.push(item)
+        events.push(item as CollectedEvent)
       }
-      response.end('{}')
+      response.setHeader('content-type', 'application/json')
+      response.end('{"results":{}}')
     } catch (error) {
       errors.push(error instanceof Error ? error : new Error(String(error)))
       response.statusCode = 500
diff --git a/packages/node/src/__tests__/bot-detection.spec.ts b/packages/node/src/__tests__/bot-detection.spec.ts
index 5e5997c4b4..2cc354ae86 100644
--- a/packages/node/src/__tests__/bot-detection.spec.ts
+++ b/packages/node/src/__tests__/bot-detection.spec.ts
@@ -1,5 +1,5 @@
 import { PostHog } from '@/entrypoints/index.node'
-import { waitForPromises } from './utils'
+import { captureRequests, sentEventsOf, v1Response, waitForPromises } from './utils'
 
 const mockedFetch = vi.spyOn(globalThis, 'fetch').mockImplementation()
 
@@ -18,11 +18,7 @@ describe('bot detection and pageview collection (Node SDK)', () => {
   let client: PostHog
 
   beforeEach(() => {
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () => Promise.resolve({ status: 1 }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
   })
 
   afterEach(async () => {
@@ -53,10 +49,10 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$pageview')
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$pageview')
     })
 
     it('should allow events without user agent', async () => {
@@ -77,10 +73,10 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$pageview')
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$pageview')
     })
   })
 
@@ -106,12 +102,12 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$bot_pageview')
-      expect(body.batch[0].properties.$browser_type).toBe('bot')
-      expect(body.batch[0].properties.$raw_user_agent).toBe(
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$bot_pageview')
+      expect(event.properties.$browser_type).toBe('bot')
+      expect(event.properties.$raw_user_agent).toBe(
         'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)'
       )
     })
@@ -137,11 +133,11 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$pageview')
-      expect(body.batch[0].properties.$raw_user_agent).toBe(
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$pageview')
+      expect(event.properties.$raw_user_agent).toBe(
         'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36'
       )
     })
@@ -167,10 +163,10 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('custom_event')
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('custom_event')
     })
 
     it('should work with various bot user agents', async () => {
@@ -205,11 +201,11 @@ describe('bot detection and pageview collection (Node SDK)', () => {
         await waitForFlushTimer()
 
         expect(mockedFetch).toHaveBeenCalled()
-        const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+        const [call] = captureRequests(mockedFetch)
         expect(call).toBeDefined()
-        const body = JSON.parse((call![1] as any).body)
-        expect(body.batch[0].event).toBe('$bot_pageview')
-        expect(body.batch[0].properties.$raw_user_agent).toBe(ua)
+        const [event] = sentEventsOf(call)
+        expect(event.event).toBe('$bot_pageview')
+        expect(event.properties.$raw_user_agent).toBe(ua)
 
         await client.shutdown()
       }
@@ -234,10 +230,10 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$pageview')
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$pageview')
     })
 
     it('should support custom_blocked_useragents', async () => {
@@ -262,11 +258,11 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$bot_pageview')
-      expect(body.batch[0].properties.$raw_user_agent).toBe('MyCustomBot/1.0')
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$bot_pageview')
+      expect(event.properties.$raw_user_agent).toBe('MyCustomBot/1.0')
     })
 
     it('should preserve other event properties when renaming', async () => {
@@ -292,12 +288,12 @@ describe('bot detection and pageview collection (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(mockedFetch).toHaveBeenCalled()
-      const call = mockedFetch.mock.calls.find((x) => (x[0] as string).includes('/batch/'))
+      const [call] = captureRequests(mockedFetch)
       expect(call).toBeDefined()
-      const body = JSON.parse((call![1] as any).body)
-      expect(body.batch[0].event).toBe('$bot_pageview')
-      expect(body.batch[0].properties.custom_prop).toBe('test_value')
-      expect(body.batch[0].properties.$current_url).toBe('https://example.com')
+      const [event] = sentEventsOf(call)
+      expect(event.event).toBe('$bot_pageview')
+      expect(event.properties.custom_prop).toBe('test_value')
+      expect(event.properties.$current_url).toBe('https://example.com')
     })
   })
 })
diff --git a/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts b/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
index 6da40f5e16..fbeed6e55c 100644
--- a/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
@@ -2,7 +2,8 @@ import { PostHogPersistedProperty } from '@posthog/core'
 
 import { PostHog } from '@/entrypoints/index.node'
 
-import { V1WiringHarness, v1Response, waitForFlushTimer } from '../utils/v1-wiring'
+import { v1Response } from '../utils'
+import { V1WiringHarness, waitForFlushTimer } from '../utils/v1-wiring'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
 
diff --git a/packages/node/src/__tests__/capture-v1/wiring.spec.ts b/packages/node/src/__tests__/capture-v1/wiring.spec.ts
index 25eafd47a1..ad2f35cac4 100644
--- a/packages/node/src/__tests__/capture-v1/wiring.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/wiring.spec.ts
@@ -2,7 +2,8 @@ import { gunzipSync } from 'node:zlib'
 
 import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
 import { CaptureV1Error } from '@/capture-v1/errors'
-import { V1_URL, V1WiringHarness, v0Response, v1Response, waitForFlushTimer } from '../utils/v1-wiring'
+import { v1Response } from '../utils'
+import { V1_URL, V1WiringHarness, v0Response, waitForFlushTimer } from '../utils/v1-wiring'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
 
diff --git a/packages/node/src/__tests__/context.spec.ts b/packages/node/src/__tests__/context.spec.ts
index 015d1bb874..909d3e2581 100644
--- a/packages/node/src/__tests__/context.spec.ts
+++ b/packages/node/src/__tests__/context.spec.ts
@@ -1,6 +1,5 @@
 import { PostHog } from '@/entrypoints/index.node'
-import { apiImplementation } from './utils'
-import { waitForPromises } from './utils'
+import { apiImplementation, lastSentBatch, sentEvents, v1Response, waitForPromises } from './utils'
 
 vi.mock('../version', () => ({ version: '1.2.3' }))
 
@@ -12,14 +11,7 @@ const waitForFlush = async (): Promise<void> => {
   await waitForPromises()
 }
 
-const getLastBatchEvents = (): any[] | undefined => {
-  const call = mockedFetch.mock.calls
-    .slice()
-    .reverse()
-    .find((x) => (x[0] as string).includes('/batch/'))
-  if (!call) return undefined
-  return JSON.parse((call[1] as any).body as any).batch
-}
+const getLastBatchEvents = (): any[] | undefined => lastSentBatch(mockedFetch)
 
 describe('PostHog Context', () => {
   let posthog: PostHog
@@ -35,11 +27,7 @@ describe('PostHog Context', () => {
       disableCompression: true,
     })
 
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () => Promise.resolve({ status: 'ok' }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
   })
 
   afterEach(async () => {
@@ -200,13 +188,7 @@ describe('PostHog Context', () => {
 
     await waitForFlush()
 
-    const allEvents: any[] = []
-    mockedFetch.mock.calls.forEach((call) => {
-      if ((call[0] as string).includes('/batch/')) {
-        const batch = JSON.parse((call[1] as any).body as any).batch
-        allEvents.push(...batch)
-      }
-    })
+    const allEvents = sentEvents(mockedFetch)
 
     expect(allEvents).toHaveLength(50)
 
@@ -254,13 +236,7 @@ describe('PostHog Context', () => {
 
     await waitForFlush()
 
-    const allEvents: any[] = []
-    mockedFetch.mock.calls.forEach((call) => {
-      if ((call[0] as string).includes('/batch/')) {
-        const batch = JSON.parse((call[1] as any).body as any).batch
-        allEvents.push(...batch)
-      }
-    })
+    const allEvents = sentEvents(mockedFetch)
 
     expect(allEvents).toHaveLength(4)
 
diff --git a/packages/node/src/__tests__/edge-exports.spec.ts b/packages/node/src/__tests__/edge-exports.spec.ts
index dd04c2d556..8db27fd6d6 100644
--- a/packages/node/src/__tests__/edge-exports.spec.ts
+++ b/packages/node/src/__tests__/edge-exports.spec.ts
@@ -3,6 +3,8 @@
 import { execFileSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 
+import { sentEventsOf } from './utils'
+
 const packageRoot = fileURLToPath(new URL('../../', import.meta.url))
 
 describe('built edge entrypoints', () => {
@@ -21,30 +23,29 @@ describe('built edge entrypoints', () => {
         `
           import { createRequire } from 'node:module'
           const { PostHog } = ${loader === 'import' ? `await import('${specifier}')` : `createRequire(import.meta.url)('${specifier}')`}
-          const batches = []
+          const requests = []
           const client = new PostHog('test-key', {
             host: 'https://example.test',
             disableCompression: true,
             fetchRetryCount: 0,
-            fetch: async (_url, options) => {
-              batches.push(...JSON.parse(options.body).batch)
+            fetch: async (url, options) => {
+              requests.push([url, { headers: options.headers, body: options.body }])
               return { status: 200, text: async () => '{}', json: async () => ({}) }
             },
           })
           client.capture({ distinctId: 'edge-user', event: 'edge-event' })
           await client.shutdown()
-          console.log(JSON.stringify(batches))
+          console.log(JSON.stringify(requests))
         `,
       ],
       {
         cwd: packageRoot,
         encoding: 'utf8',
         timeout: 10_000,
-        env: { ...process.env, POSTHOG_CAPTURE_MODE: 'v0' },
       }
     )
 
-    expect(JSON.parse(output)).toEqual([
+    expect(JSON.parse(output).flatMap(sentEventsOf)).toEqual([
       expect.objectContaining({
         distinct_id: 'edge-user',
         event: 'edge-event',
diff --git a/packages/node/src/__tests__/extensions/express.spec.ts b/packages/node/src/__tests__/extensions/express.spec.ts
index e0eed1b1ca..83e78e40cd 100644
--- a/packages/node/src/__tests__/extensions/express.spec.ts
+++ b/packages/node/src/__tests__/extensions/express.spec.ts
@@ -1,6 +1,7 @@
 import { EventEmitter } from 'node:events'
 import type { IncomingHttpHeaders } from 'node:http'
 import { PostHog } from '@/entrypoints/index.node'
+import { anyCaptureUrl, lastSentBatch, v1Response } from '../utils'
 import { setupExpressErrorHandler, setupExpressRequestContext } from '@/extensions/express'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
@@ -12,13 +13,8 @@ const waitForFlushTimer = async (posthog: PostHog): Promise<void> => {
 }
 
 const getLastBatchEvents = (): any[] | undefined => {
-  expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.objectContaining({ method: 'POST' }))
-
-  const call = [...mockedFetch.mock.calls].reverse().find((x) => (x[0] as string).includes('/batch/'))
-  if (!call) {
-    return undefined
-  }
-  return JSON.parse((call[1] as any).body as any).batch
+  expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.objectContaining({ method: 'POST' }))
+  return lastSentBatch(mockedFetch)
 }
 
 const createMockRequest = (overrides?: {
@@ -80,11 +76,7 @@ describe('Express extension', () => {
   beforeEach(() => {
     posthog = createPostHog()
 
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () => Promise.resolve({ status: 'ok' }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
   })
 
   afterEach(async () => {
diff --git a/packages/node/src/__tests__/extensions/nestjs.spec.ts b/packages/node/src/__tests__/extensions/nestjs.spec.ts
index ae836a6dfe..472d330a00 100644
--- a/packages/node/src/__tests__/extensions/nestjs.spec.ts
+++ b/packages/node/src/__tests__/extensions/nestjs.spec.ts
@@ -2,6 +2,7 @@ import type { IncomingHttpHeaders } from 'node:http'
 import { defer, of, throwError, lastValueFrom } from 'rxjs'
 
 import { PostHog } from '@/entrypoints/index.node'
+import { anyCaptureUrl, captureRequests, lastSentBatch, v1Response } from '../utils'
 import { PostHogInterceptor } from '@/extensions/nestjs'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
@@ -17,16 +18,8 @@ const waitForFlushTimer = async (posthog: PostHog): Promise<void> => {
 }
 
 const getLastBatchEvents = (): any[] | undefined => {
-  expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.objectContaining({ method: 'POST' }))
-
-  const call = mockedFetch.mock.calls
-    .slice()
-    .reverse()
-    .find((x) => (x[0] as string).includes('/batch/'))
-  if (!call) {
-    return undefined
-  }
-  return JSON.parse((call[1] as any).body as any).batch
+  expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.objectContaining({ method: 'POST' }))
+  return lastSentBatch(mockedFetch)
 }
 
 const createMockContext = (overrides?: {
@@ -75,11 +68,7 @@ describe('PostHogInterceptor', () => {
   beforeEach(() => {
     posthog = createPostHog()
 
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () => Promise.resolve({ status: 'ok' }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
   })
 
   afterEach(async () => {
@@ -345,7 +334,7 @@ describe('PostHogInterceptor', () => {
       await expect(lastValueFrom(interceptor.intercept(context, createMockCallHandler(error)))).rejects.toThrow(error)
       await waitForFlushTimer(posthog)
 
-      const batchCalls = mockedFetch.mock.calls.filter((c) => (c[0] as string).includes('/batch/'))
+      const batchCalls = captureRequests(mockedFetch)
       expect(batchCalls.length).toBe(0)
     })
 
@@ -418,7 +407,7 @@ describe('PostHogInterceptor', () => {
       await expect(lastValueFrom(interceptor.intercept(context, createMockCallHandler(error)))).rejects.toThrow(error)
       await waitForFlushTimer(posthog)
 
-      const batchCalls = mockedFetch.mock.calls.filter((c) => (c[0] as string).includes('/batch/'))
+      const batchCalls = captureRequests(mockedFetch)
       expect(batchCalls.length).toBe(0)
     })
 
@@ -482,7 +471,7 @@ describe('PostHogInterceptor', () => {
       await expect(lastValueFrom(interceptor.intercept(context, createMockCallHandler(error)))).rejects.toThrow(error)
       await waitForFlushTimer(posthog)
 
-      const batchCalls = mockedFetch.mock.calls.filter((c) => (c[0] as string).includes('/batch/'))
+      const batchCalls = captureRequests(mockedFetch)
       expect(batchCalls.length).toBe(0)
     })
 
diff --git a/packages/node/src/__tests__/extensions/sentry-integration.spec.ts b/packages/node/src/__tests__/extensions/sentry-integration.spec.ts
index 76de5da82a..0ca79aba77 100644
--- a/packages/node/src/__tests__/extensions/sentry-integration.spec.ts
+++ b/packages/node/src/__tests__/extensions/sentry-integration.spec.ts
@@ -1,4 +1,5 @@
 import { PostHog } from '@/entrypoints/index.node'
+import { anyCaptureUrl, lastSentBatch, v1Response } from '../utils'
 import {
   PostHogSentryIntegration,
   sentryIntegration,
@@ -10,17 +11,8 @@ vi.mock('../../version', () => ({ version: '1.2.3' }))
 const mockedFetch = vi.spyOn(globalThis, 'fetch').mockImplementation()
 
 const getLastBatchEvents = (): any[] | undefined => {
-  expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.objectContaining({ method: 'POST' }))
-
-  // reverse mock calls array to get the last call
-  const call = mockedFetch.mock.calls
-    .slice()
-    .reverse()
-    .find((x) => (x[0] as string).includes('/batch/'))
-  if (!call) {
-    return undefined
-  }
-  return JSON.parse((call[1] as any).body as any).batch
+  expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.objectContaining({ method: 'POST' }))
+  return lastSentBatch(mockedFetch)
 }
 
 const createMockSentryException = (): any => ({
@@ -79,14 +71,7 @@ describe('PostHogSentryIntegration', () => {
 
     posthogSentry = new PostHogSentryIntegration(posthog)
 
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () =>
-        Promise.resolve({
-          status: 'ok',
-        }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
   })
 
   afterEach(async () => {
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index bdbb9c03c9..40b6263942 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -1,7 +1,17 @@
 import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
 import ErrorTracking from '@/extensions/error-tracking'
 import type { IPostHog } from '@/types'
-import { anyFlagsCall, anyLocalEvalCall, apiImplementation, wait, waitForPromises } from './utils'
+import {
+  anyCaptureUrl,
+  anyFlagsCall,
+  anyLocalEvalCall,
+  apiImplementation,
+  lastSentBatch,
+  sentEvents,
+  v1Response,
+  wait,
+  waitForPromises,
+} from './utils'
 import { randomUUID } from 'crypto'
 import { setTimeout as waitWithRealTimers } from 'node:timers/promises'
 import { UUID_REGEX } from '@posthog/core'
@@ -31,17 +41,8 @@ const waitForFlushTimer = async (): Promise<void> => {
 }
 
 const getLastBatchEvents = (): any[] | undefined => {
-  expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.objectContaining({ method: 'POST' }))
-
-  // reverse mock calls array to get the last call
-  const call = mockedFetch.mock.calls
-    .slice()
-    .reverse()
-    .find((x) => (x[0] as string).includes('/batch/'))
-  if (!call) {
-    return undefined
-  }
-  return JSON.parse((call[1] as any).body as any).batch
+  expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.objectContaining({ method: 'POST' }))
+  return lastSentBatch(mockedFetch)
 }
 
 describe('PostHog Node.js', () => {
@@ -66,25 +67,11 @@ describe('PostHog Node.js', () => {
       disableCompression: true,
     })
 
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () =>
-        Promise.resolve({
-          status: 'ok',
-        }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
   })
 
   afterEach(async () => {
-    mockedFetch.mockResolvedValue({
-      status: 200,
-      text: () => Promise.resolve('ok'),
-      json: () =>
-        Promise.resolve({
-          status: 'ok',
-        }),
-    } as any)
+    mockedFetch.mockResolvedValue(v1Response())
 
     // ensure clean shutdown & no test interdependencies
     await posthog.shutdown()
@@ -728,7 +715,7 @@ describe('PostHog Node.js', () => {
       await waitForFlushTimer()
 
       expect(beforeSendFn).toHaveBeenCalledTimes(1)
-      expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.anything())
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
     })
 
     it('should support array of before_send functions', async () => {
@@ -775,7 +762,7 @@ describe('PostHog Node.js', () => {
       expect(beforeSend1).toHaveBeenCalledTimes(1)
       expect(beforeSend2).toHaveBeenCalledTimes(1)
       expect(beforeSend3).not.toHaveBeenCalled()
-      expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.anything())
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
     })
 
     it('should fail closed when a before_send function throws', async () => {
@@ -800,7 +787,7 @@ describe('PostHog Node.js', () => {
 
       expect(sentinel).not.toHaveBeenCalled()
       expect(loggerSpy).toHaveBeenCalledWith("Error in before_send function for event 'test-event':", error)
-      expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.anything())
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
       loggerSpy.mockRestore()
     })
 
@@ -964,7 +951,7 @@ describe('PostHog Node.js', () => {
         await send(ph)
 
         expect(beforeSendFn).toHaveBeenCalledTimes(1)
-        expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.anything())
+        expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
       }
     )
 
@@ -1078,14 +1065,7 @@ describe('PostHog Node.js', () => {
         // simulate network delay
         await wait(500)
 
-        return Promise.resolve({
-          status: 200,
-          text: () => Promise.resolve('ok'),
-          json: () =>
-            Promise.resolve({
-              status: 'ok',
-            }),
-        } as any)
+        return Promise.resolve(v1Response())
       })
 
       vi.useRealTimers()
@@ -1144,10 +1124,7 @@ describe('PostHog Node.js', () => {
       }
       expect(flushSettled).toBe(true)
       expect(shutdownSettled).toBe(true)
-      const flushedEvents = mockedFetch.mock.calls
-        .filter(([url]) => String(url).endsWith('/batch/'))
-        .flatMap(([, options]) => JSON.parse(options!.body as string).batch)
-      expect(flushedEvents).toMatchObject([
+      expect(sentEvents(mockedFetch)).toMatchObject([
         { event: 'test-event-1' },
         { event: 'test-event-2' },
         { event: 'test-event-3' },
@@ -2192,15 +2169,9 @@ describe('PostHog Node.js', () => {
         expect(mockedFetch).toHaveBeenCalledWith(...anyLocalEvalCall)
 
         // Should make immediate batch call
-        expect(mockedFetch).toHaveBeenCalledWith(
-          'http://example.com/batch/',
-          expect.objectContaining({ method: 'POST' })
-        )
+        expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.objectContaining({ method: 'POST' }))
 
-        const lastCall = mockedFetch.mock.calls.find((call) => (call[0] as string).includes('/batch/'))
-        const body = JSON.parse(lastCall?.[1]?.body as string)
-
-        expect(body.batch[0]).toEqual(
+        expect(sentEvents(mockedFetch)[0]).toEqual(
           expect.objectContaining({
             distinct_id: 'user123',
             event: 'test event',
@@ -2397,10 +2368,7 @@ describe('PostHog Node.js', () => {
           await hashStarted
           await vi.advanceTimersByTimeAsync(0)
           expect(flushFinished).toBe(false)
-          expect(mockedFetch).not.toHaveBeenCalledWith(
-            'http://example.com/batch/',
-            expect.objectContaining({ method: 'POST' })
-          )
+          expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.objectContaining({ method: 'POST' }))
 
           releaseHash()
           await flushing
@@ -2887,7 +2855,7 @@ describe('PostHog Node.js', () => {
       await waitForPromises()
       await posthog.flush()
 
-      expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
+      expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.any(Object))
 
       expect(getLastBatchEvents()?.[0]).toEqual(
         expect.objectContaining({
@@ -2916,7 +2884,7 @@ describe('PostHog Node.js', () => {
       await waitForPromises()
       await posthog.flush()
 
-      expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.any(Object))
 
       // # called for different user, should call capture again
       expect(
@@ -2929,7 +2897,7 @@ describe('PostHog Node.js', () => {
       vi.runOnlyPendingTimers()
       await waitForPromises()
       await posthog.flush()
-      expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
+      expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.any(Object))
 
       expect(getLastBatchEvents()?.[0]).toEqual(
         expect.objectContaining({
@@ -2958,7 +2926,7 @@ describe('PostHog Node.js', () => {
       vi.runOnlyPendingTimers()
       await waitForPromises()
       await posthog.flush()
-      expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.any(Object))
 
       // # called for different flag, falls back to flags, should call capture again
       expect(
@@ -2972,7 +2940,7 @@ describe('PostHog Node.js', () => {
       await posthog.flush()
       // one to flags, one to batch
       expect(mockedFetch).toHaveBeenCalledWith(...anyFlagsCall)
-      expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
+      expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.any(Object))
 
       expect(getLastBatchEvents()?.[0]).toEqual(
         expect.objectContaining({
@@ -3002,7 +2970,7 @@ describe('PostHog Node.js', () => {
       await posthog.flush()
       // call flags, but not batch
       expect(mockedFetch).toHaveBeenCalledWith(...anyFlagsCall)
-      expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.any(Object))
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.any(Object))
     })
 
     describe('`sendFeatureFlagEvent` client option', () => {
@@ -3057,7 +3025,7 @@ describe('PostHog Node.js', () => {
           await posthog.flush()
 
           // Should NOT send $feature_flag_called event because global setting is false
-          expect(mockedFetch).not.toHaveBeenCalledWith('http://example.com/batch/', expect.anything())
+          expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
         })
 
         it('overrides client sendFeatureFlagEvent option when method-level option is provided', async () => {
@@ -3078,7 +3046,7 @@ describe('PostHog Node.js', () => {
           await posthog.flush()
 
           // The client option should have been overridden, allowing the event to be sent
-          expect(mockedFetch).toHaveBeenCalledWith('http://example.com/batch/', expect.anything())
+          expect(mockedFetch).toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
         })
       })
     })
diff --git a/packages/node/src/__tests__/server-wire-snapshots.spec.ts b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
index 4886826498..9a14e30fdc 100644
--- a/packages/node/src/__tests__/server-wire-snapshots.spec.ts
+++ b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
@@ -4,7 +4,8 @@ import type { PostHogFetchOptions } from '@posthog/core'
 
 import { V1CaptureSender } from '@/capture-v1/sender'
 import { PostHog } from '@/entrypoints/index.node'
-import { v0Response, v1Response } from './utils/v1-wiring'
+import { v1Response } from './utils'
+import { v0Response } from './utils/v1-wiring'
 
 type FetchCall = [string, PostHogFetchOptions]
 
diff --git a/packages/node/src/__tests__/utils/index.ts b/packages/node/src/__tests__/utils/index.ts
index 779801d124..225d2cee3d 100644
--- a/packages/node/src/__tests__/utils/index.ts
+++ b/packages/node/src/__tests__/utils/index.ts
@@ -1,6 +1,92 @@
 import { PostHogV2FlagsResponse } from '@posthog/core'
 import util from 'util'
 
+const LEGACY_CAPTURE_PATH = '/batch/'
+const V1_ANALYTICS_CAPTURE_PATH = '/i/v1/analytics/events'
+const ANALYTICS_CAPTURE_PATHS = [LEGACY_CAPTURE_PATH, V1_ANALYTICS_CAPTURE_PATH]
+
+const isAnalyticsCaptureUrl = (url: unknown): boolean => {
+  const { pathname } = new URL(String(url))
+  return ANALYTICS_CAPTURE_PATHS.includes(pathname)
+}
+
+/** Matches the analytics capture URL of either wire format: legacy `/batch/` or Capture V1. */
+export const anyCaptureUrl = expect.stringMatching(/^https?:\/\/[^/]+(\/batch\/|\/i\/v1\/analytics\/events)$/)
+
+/** A capture 2xx response. The legacy sender ignores the body; the Capture V1 sender reads `results`. */
+export function v1Response(results: Record<string, unknown> = {}): any {
+  const body = JSON.stringify({ results })
+  return {
+    status: 200,
+    text: () => Promise.resolve(body),
+    json: () => Promise.resolve({ results }),
+    headers: { get: () => null },
+    body: null,
+  }
+}
+
+type FetchMock = { mock: { calls: any[][] } }
+type FetchCall = [string, any]
+
+/** Capture V1 per-event `options`, keyed by the legacy property each one replaces. */
+const V1_OPTION_PROPERTIES: Record<string, string> = {
+  cookieless_mode: '$cookieless_mode',
+  disable_skew_correction: '$ignore_sent_at',
+  process_person_profile: '$process_person_profile',
+  product_tour_id: '$product_tour_id',
+}
+
+function legacyPropertiesOf(v1Event: any, sdkInfo: string): Record<string, any> {
+  const versionAt = sdkInfo.lastIndexOf('/')
+  const properties: Record<string, any> = {
+    ...v1Event.properties,
+    $lib: sdkInfo.slice(0, versionAt),
+    $lib_version: sdkInfo.slice(versionAt + 1),
+  }
+  for (const [option, value] of Object.entries(v1Event.options ?? {})) {
+    properties[V1_OPTION_PROPERTIES[option] ?? option] = value
+  }
+  if (v1Event.session_id !== undefined) {
+    properties.$session_id = v1Event.session_id
+  }
+  if (v1Event.window_id !== undefined) {
+    properties.$window_id = v1Event.window_id
+  }
+  return properties
+}
+
+/**
+ * The events of one analytics capture request, in the legacy `/batch/` event shape whichever wire
+ * format carried them. A Capture V1 event's `options`, `session_id`, `window_id` and SDK info
+ * header go back into the properties they replace, so one assertion holds for both formats.
+ */
+export function sentEventsOf([url, options]: FetchCall): any[] {
+  const { batch } = JSON.parse(options.body)
+  if (new URL(url).pathname !== V1_ANALYTICS_CAPTURE_PATH) {
+    return batch
+  }
+  return batch.map((v1Event: any) => {
+    const event = { ...v1Event, properties: legacyPropertiesOf(v1Event, options.headers['PostHog-Sdk-Info']) }
+    delete event.options
+    delete event.session_id
+    delete event.window_id
+    return event
+  })
+}
+
+/** Analytics capture requests of either wire format, as `[url, options]` tuples in call order. */
+export const captureRequests = (fetchMock: FetchMock): FetchCall[] =>
+  fetchMock.mock.calls.filter((call) => isAnalyticsCaptureUrl(call[0])) as FetchCall[]
+
+/** Every event sent to the analytics capture endpoint, in the shape {@link sentEventsOf} returns. */
+export const sentEvents = (fetchMock: FetchMock): any[] => captureRequests(fetchMock).flatMap(sentEventsOf)
+
+/** The events of the most recent analytics capture request, or `undefined` if none was sent. */
+export const lastSentBatch = (fetchMock: FetchMock): any[] | undefined => {
+  const requests = captureRequests(fetchMock)
+  return requests.length ? sentEventsOf(requests[requests.length - 1]) : undefined
+}
+
 type ErrorResponse = {
   status: number
   json: () => Promise<any>
@@ -23,15 +109,8 @@ export const apiImplementationV4 = (flagsResponse: PostHogV2FlagsResponse | Erro
           })
     }
 
-    if ((url as any).includes('batch/')) {
-      return Promise.resolve({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () =>
-          Promise.resolve({
-            status: 'ok',
-          }),
-      }) as any
+    if (isAnalyticsCaptureUrl(url)) {
+      return Promise.resolve(v1Response())
     }
 
     return Promise.resolve({
@@ -100,15 +179,8 @@ export const apiImplementation = ({
       }) as any
     }
 
-    if ((url as any).includes('batch/')) {
-      return Promise.resolve({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () =>
-          Promise.resolve({
-            status: 'ok',
-          }),
-      }) as any
+    if (isAnalyticsCaptureUrl(url)) {
+      return Promise.resolve(v1Response())
     }
 
     return Promise.resolve({
diff --git a/packages/node/src/__tests__/utils/v1-wiring.ts b/packages/node/src/__tests__/utils/v1-wiring.ts
index 37b8251113..c440f4913b 100644
--- a/packages/node/src/__tests__/utils/v1-wiring.ts
+++ b/packages/node/src/__tests__/utils/v1-wiring.ts
@@ -1,21 +1,9 @@
 import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
 
-import { waitForPromises } from '.'
+import { v1Response, waitForPromises } from '.'
 
 export const V1_URL = 'http://example.com/i/v1/analytics/events'
 
-/** A Capture V1 2xx response whose per-event `results` map defaults to all-accepted. */
-export function v1Response(results: Record<string, unknown> = {}): any {
-  const body = JSON.stringify({ results })
-  return {
-    status: 200,
-    text: () => Promise.resolve(body),
-    json: () => Promise.resolve({ results }),
-    headers: { get: () => null },
-    body: null,
-  }
-}
-
 /** A legacy `/batch/` 2xx response. */
 export function v0Response(): any {
   return {
diff --git a/packages/node/src/__tests__/waituntil-flush.spec.ts b/packages/node/src/__tests__/waituntil-flush.spec.ts
index c147d9bdb3..e41c33f50d 100644
--- a/packages/node/src/__tests__/waituntil-flush.spec.ts
+++ b/packages/node/src/__tests__/waituntil-flush.spec.ts
@@ -1,5 +1,7 @@
 import { PostHog } from '@/entrypoints/index.node'
 
+import { captureRequests, sentEventsOf, v1Response } from './utils'
+
 vi.mock('../version', () => ({ version: '1.2.3' }))
 
 const mockedFetch = vi.spyOn(globalThis, 'fetch').mockImplementation()
@@ -7,9 +9,7 @@ const DEBOUNCE_MS = 50
 const HALF_DEBOUNCE_MS = DEBOUNCE_MS / 2
 
 function getFlushedBatches(): any[][] {
-  return mockedFetch.mock.calls
-    .filter((c) => (c[0] as string).includes('/batch/'))
-    .map((c) => JSON.parse((c[1] as any).body).batch)
+  return captureRequests(mockedFetch).map(sentEventsOf)
 }
 
 describe('flush combines events and spans', () => {
@@ -25,7 +25,7 @@ describe('flush combines events and spans', () => {
         order.push('traces-done')
         return { status: 200, text: () => Promise.resolve('{}'), json: () => Promise.resolve({}) } as any
       }
-      throw new Error('events endpoint down')
+      return v1Response()
     })
     const posthog = new PostHog('key', {
       host: 'http://example.com',
@@ -34,6 +34,8 @@ describe('flush combines events and spans', () => {
       traces: { serviceName: 'svc' },
       disableCompression: true,
     })
+    // Fail the send seam itself: only the legacy sender throws when the events request fails.
+    vi.spyOn(posthog as any, 'sendBatch').mockRejectedValue(new Error('events endpoint down'))
     posthog.capture({ distinctId: 'u', event: 'e' })
     posthog.startSpan('s').end()
 
@@ -72,11 +74,7 @@ describe('waitUntil debounced flush', () => {
         waitUntilDebounceMs: DEBOUNCE_MS,
       })
 
-      mockedFetch.mockResolvedValue({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () => Promise.resolve({ status: 'ok' }),
-      } as any)
+      mockedFetch.mockResolvedValue(v1Response())
     })
 
     afterEach(async () => {
@@ -142,7 +140,7 @@ describe('waitUntil debounced flush', () => {
       })
       mockedFetch.mockImplementationOnce(async () => {
         await delivery
-        return { status: 200, text: async () => 'ok', json: async () => ({ status: 'ok' }) } as any
+        return v1Response()
       })
 
       try {
@@ -248,11 +246,7 @@ describe('waitUntil debounced flush', () => {
         waitUntilMaxWaitMs: MAX_DEBOUNCE_MS,
       })
 
-      mockedFetch.mockResolvedValue({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () => Promise.resolve({ status: 'ok' }),
-      } as any)
+      mockedFetch.mockResolvedValue(v1Response())
     })
 
     afterEach(async () => {
@@ -332,11 +326,7 @@ describe('waitUntil debounced flush', () => {
         waitUntil: mockWaitUntil,
       })
 
-      mockedFetch.mockResolvedValue({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () => Promise.resolve({ status: 'ok' }),
-      } as any)
+      mockedFetch.mockResolvedValue(v1Response())
     })
 
     afterEach(async () => {
@@ -570,11 +560,7 @@ describe('waitUntil debounced flush', () => {
         waitUntilDebounceMs: DEBOUNCE_MS,
       })
 
-      mockedFetch.mockResolvedValue({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () => Promise.resolve({ status: 'ok' }),
-      } as any)
+      mockedFetch.mockResolvedValue(v1Response())
 
       posthog.capture({ distinctId: 'user-1', event: 'event_1' })
       posthog.capture({ distinctId: 'user-1', event: 'event_2' })
@@ -606,11 +592,7 @@ describe('waitUntil debounced flush', () => {
         waitUntilDebounceMs: DEBOUNCE_MS,
       })
 
-      mockedFetch.mockResolvedValue({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () => Promise.resolve({ status: 'ok' }),
-      } as any)
+      mockedFetch.mockResolvedValue(v1Response())
 
       posthog.capture({ distinctId: 'user-1', event: 'event_1' })
       posthog.capture({ distinctId: 'user-1', event: 'event_2' })
@@ -642,11 +624,7 @@ describe('waitUntil debounced flush', () => {
         waitUntilDebounceMs: 200,
       })
 
-      mockedFetch.mockResolvedValue({
-        status: 200,
-        text: () => Promise.resolve('ok'),
-        json: () => Promise.resolve({ status: 'ok' }),
-      } as any)
+      mockedFetch.mockResolvedValue(v1Response())
     })
 
     afterEach(async () => {

From 5db747f0f254d5f17a829fa9b39788f2fffad265 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Mon, 26 Oct 2026 21:53:18 -0700
Subject: [PATCH 03/20] feat(node)!: send every event through capture v1
 (#5409)

* refactor(node): name the capture lane on CaptureError and export it

Rename CaptureV1Error to CaptureError (and its params and drop types),
add the endpoint the batch was sent to, and export the class so callers
can instanceof it. The sender now takes its lane path from config so
the analytics and AI lanes can share it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: send every event through capture v1

Remove the POSTHOG_CAPTURE_MODE switch and the legacy /batch/ path.
Every capture() event, including $ai_* events, goes to
/i/v1/analytics/events; the SDK no longer reroutes by event name.
captureAi and captureAiImmediate send to /i/v1/ai/events through the
same sender, with one lazily created sender per lane. A 413 on the AI
lane is now a terminal CaptureError instead of a split-and-retry.

A client built while POSTHOG_CAPTURE_MODE is set logs one warning
that the variable is no longer read. Tests that read events through the
shared helpers pass unchanged; the wire snapshot, the capture lane
wiring tests and the delivery error tests now assert the v1 wire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* ci(compliance): run the node v2 harness on the capture v1 profile only

posthog-node no longer has a v0 capture mode, so drop the v0 matrix
leg and the node-legacy profile. The adapter stops setting
POSTHOG_CAPTURE_MODE and stops advertising capture_v0,
capture_v0_batch and capture_ai_v0. run-compliance.sh no longer takes
a mode argument, and the PR comment reports both suites for the one
profile. The job stays advisory.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for capture v1 only

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): keep the process alive while a capture send retries

The v1 sender waited between retries and timed each attempt with unref'd
timers. A script ending in `await posthog.shutdown()` could exit during a
retry wait and lose the batch. Use ref'd timers inside an in-flight send,
as the v0 path did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(ai): accept only capture v1 requests in the cassette collector

posthog-node no longer sends to /batch/, so the collector now rejects the
legacy endpoint and body, and requires the bearer token and the v1 event
fields on every request.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(convex): assert the capture v1 wire in the example tests

posthog-node sends events only to the capture v1 analytics endpoint.
Read events from that endpoint alone, and check the bearer token and the
absence of an api_key in the body.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ci): download the node compliance artifact into the folder the report reads

With one artifact left, a pattern download extracts it straight into the
target path, so the report found no node-v2-v1 folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-node-capture-v1-only.md    |   5 +
 .../sdk-compliance-tests-node-v2.yml          |  18 +-
 compliance/node/v2/Dockerfile                 |   2 +-
 compliance/node/v2/README.md                  |  20 +--
 compliance/node/v2/binding.mjs                |  10 +-
 compliance/node/v2/binding.test.mjs           |  23 ++-
 compliance/node/v2/report-ci.test.mjs         | 126 +++++++-------
 compliance/node/v2/run-compliance.sh          |  15 +-
 compliance/node/v2/run-compliance.test.mjs    |  16 +-
 compliance/node/v2/server.mjs                 |  14 +-
 compliance/node/v2/server.test.mjs            |  24 +--
 compliance/node/v2/snapshot-http.test.mjs     |   6 +-
 compliance/node/v2/worker.mjs                 |   2 +-
 .../example-convex/convex/example.test.ts     |  13 +-
 packages/ai/harness/collector.test.ts         |  36 ++--
 packages/ai/harness/collector.ts              |  18 +-
 .../posthog-node-references-latest.json       |  53 ++++++
 .../server-wire-snapshots.spec.ts.snap        |  13 +-
 .../src/__tests__/ai-capture/wiring.spec.ts   | 163 +++++++-----------
 .../src/__tests__/capture-v1/config.spec.ts   |  33 ----
 .../__tests__/capture-v1/process-exit.spec.ts |  81 +++++++++
 .../capture-v1/route-isolation.spec.ts        |  80 ++++-----
 .../src/__tests__/capture-v1/routing.spec.ts  |  35 ----
 .../src/__tests__/capture-v1/sender.spec.ts   | 119 +++++++------
 .../src/__tests__/capture-v1/wiring.spec.ts   | 163 +++++++++---------
 .../node/src/__tests__/edge-exports.spec.ts   |   4 +-
 .../src/__tests__/immediate-delivery.spec.ts  |  18 +-
 .../node/src/__tests__/posthog-node.spec.ts   |  22 ++-
 .../__tests__/server-wire-snapshots.spec.ts   |  42 ++---
 packages/node/src/__tests__/utils/index.ts    |  44 ++++-
 .../node/src/__tests__/utils/v1-wiring.ts     |  69 ++------
 packages/node/src/ai-capture/routing.ts       |   2 -
 packages/node/src/capture-v1/config.ts        |  18 --
 packages/node/src/capture-v1/errors.ts        |  29 ++--
 packages/node/src/capture-v1/routing.ts       |  28 ---
 packages/node/src/capture-v1/sender.ts        |  53 +++---
 packages/node/src/capture-v1/types.ts         |  10 +-
 packages/node/src/client.ts                   | 157 +++++++----------
 packages/node/src/exports.ts                  |   3 +
 39 files changed, 775 insertions(+), 812 deletions(-)
 create mode 100644 .changeset/posthog-node-capture-v1-only.md
 delete mode 100644 packages/node/src/__tests__/capture-v1/config.spec.ts
 create mode 100644 packages/node/src/__tests__/capture-v1/process-exit.spec.ts
 delete mode 100644 packages/node/src/__tests__/capture-v1/routing.spec.ts
 delete mode 100644 packages/node/src/capture-v1/config.ts
 delete mode 100644 packages/node/src/capture-v1/routing.ts

diff --git a/.changeset/posthog-node-capture-v1-only.md b/.changeset/posthog-node-capture-v1-only.md
new file mode 100644
index 0000000000..aa10db4c60
--- /dev/null
+++ b/.changeset/posthog-node-capture-v1-only.md
@@ -0,0 +1,5 @@
+---
+'posthog-node': major
+---
+
+Capture always uses capture v1: `POSTHOG_CAPTURE_MODE` is no longer read, `captureAi` sends to `/i/v1/ai/events`, and `CaptureV1Error` is now `CaptureError`.
diff --git a/.github/workflows/sdk-compliance-tests-node-v2.yml b/.github/workflows/sdk-compliance-tests-node-v2.yml
index 142d5e7a70..463d257823 100644
--- a/.github/workflows/sdk-compliance-tests-node-v2.yml
+++ b/.github/workflows/sdk-compliance-tests-node-v2.yml
@@ -46,10 +46,6 @@ jobs:
         continue-on-error: true
         permissions:
             contents: read
-        strategy:
-            fail-fast: false
-            matrix:
-                mode: [v0, v1]
         defaults:
             run:
                 shell: bash
@@ -57,7 +53,6 @@ jobs:
             NODE_IMAGE: node:24.21.0-bookworm-slim@sha256:0e0ff40c39bc087845bfb27465a0df4ea419520094bc35842ff83dd8cbe6f9b6
             # Harness release 1.16.0; pin the published multi-platform image index.
             HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness-v2@sha256:14c539d87c758a8798d3681d26e081cd156b739052d4fdefc51065f92e7cd2f2
-            CAPTURE_MODE: ${{ matrix.mode }}
         steps:
             # Test the PR head or the triggering commit for push/manual runs.
             - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -81,7 +76,7 @@ jobs:
               timeout-minutes: 35
               run: |
                   bash compliance/node/v2/run-compliance.sh node-compliance:local "$HARNESS_IMAGE" \
-                    "$CAPTURE_MODE" "$RUNNER_TEMP/node-compliance/reports" \
+                    "$RUNNER_TEMP/node-compliance/reports" \
                     2>&1 | tee "$RUNNER_TEMP/node-compliance/run.log"
             - name: Run isolated acceptance profile
               if: steps.prepare.outcome == 'success'
@@ -89,14 +84,14 @@ jobs:
               timeout-minutes: 25
               run: |
                   bash compliance/node/v2/run-compliance.sh node-compliance:local "$HARNESS_IMAGE" \
-                    "$CAPTURE_MODE" "$RUNNER_TEMP/node-compliance/acceptance" acceptance \
+                    "$RUNNER_TEMP/node-compliance/acceptance" acceptance \
                     2>&1 | tee "$RUNNER_TEMP/node-compliance/acceptance-run.log"
             - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
               if: always()
               continue-on-error: true
               timeout-minutes: 3
               with:
-                  name: node-v2-${{ matrix.mode }}
+                  name: node-v2-v1
                   path: ${{ runner.temp }}/node-compliance
                   if-no-files-found: error
                   retention-days: 14
@@ -121,8 +116,9 @@ jobs:
             - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
               continue-on-error: true
               with:
-                  pattern: node-v2-*
-                  path: ${{ runner.temp }}/node-compliance-results
+                  # A download by name extracts into `path` itself, so name the folder the report reads.
+                  name: node-v2-v1
+                  path: ${{ runner.temp }}/node-compliance-results/node-v2-v1
             # No checkout or execution of code from the tested revision in this job.
             - name: Summarize results and update PR comment
               continue-on-error: true
@@ -167,9 +163,7 @@ jobs:
                       const lines = [marker, '# Node SDK compliance v2', '',
                           `Commit: ${sha}`, `[Workflow run and artifacts](${runUrl})`, ''];
                       for (const [mode, profile, suite, reports] of [
-                          ['v0', 'node-legacy', 'acceptance', 'acceptance'],
                           ['v1', 'node-analytics-v1', 'acceptance', 'acceptance'],
-                          ['v0', 'node-legacy', 'migration', 'reports'],
                           ['v1', 'node-analytics-v1', 'migration', 'reports'],
                       ]) {
                           lines.push(`## Capture ${mode} — ${suite}`, '');
diff --git a/compliance/node/v2/Dockerfile b/compliance/node/v2/Dockerfile
index 41b6ddde8b..04ea894da7 100644
--- a/compliance/node/v2/Dockerfile
+++ b/compliance/node/v2/Dockerfile
@@ -18,6 +18,6 @@ WORKDIR /adapter
 COPY --from=build /output/consumer /consumer
 COPY --from=build /output/build.json /build.json
 COPY compliance/node/v2/binding.mjs compliance/node/v2/server.mjs compliance/node/v2/worker.mjs ./
-ENV POSTHOG_NODE_CONSUMER=/consumer HOST=0.0.0.0 PORT=8080 POSTHOG_CAPTURE_MODE=v0 POSTHOG_NODE_MODULE=cjs
+ENV POSTHOG_NODE_CONSUMER=/consumer HOST=0.0.0.0 PORT=8080 POSTHOG_NODE_MODULE=cjs
 USER node
 ENTRYPOINT ["node", "/adapter/server.mjs"]
diff --git a/compliance/node/v2/README.md b/compliance/node/v2/README.md
index d45e6bf691..537ea44523 100644
--- a/compliance/node/v2/README.md
+++ b/compliance/node/v2/README.md
@@ -8,11 +8,11 @@ Use Node 24 and a consumer directory with `posthog-node` installed from the sele
 
 ```sh
 POSTHOG_NODE_CONSUMER=/absolute/path/to/consumer \
-POSTHOG_CAPTURE_MODE=v0 POSTHOG_NODE_MODULE=cjs \
+POSTHOG_NODE_MODULE=cjs \
 HOST=127.0.0.1 PORT=8080 node compliance/node/v2/server.mjs
 ```
 
-`POSTHOG_CAPTURE_MODE` is fixed for the process: `v0` advertises `node-legacy`, `v1` advertises `node-analytics-v1`. `POSTHOG_NODE_MODULE=esm` selects native public ESM imports instead of CommonJS. These mappings were initially checked with Node SDK 5.52.4, core 1.54.2 and types 1.412.1; fresh source builds validate the selected revision independently.
+The adapter advertises one profile, `node-analytics-v1`. `POSTHOG_NODE_MODULE=esm` selects native public ESM imports instead of CommonJS. These mappings were initially checked with Node SDK 5.52.4, core 1.54.2 and types 1.412.1; fresh source builds validate the selected revision independently.
 
 The startup JSON line reports the actual bound address and port (`PORT=0` is supported). One listener owns one port. `HOST=::` is a dual-stack wildcard listener; use `127.0.0.1` or `::1` for loopback-only access. DNS hosts select one resolved address, preferring IPv4 when available so Linux clients that omit loopback IPv6 can reach `localhost`. Only bind wildcard addresses on an isolated test network. This unauthenticated service is not a production endpoint.
 
@@ -55,13 +55,9 @@ The final adapter image contains Node, the installed consumer and three runtime
 
 ```sh
 bash compliance/node/v2/run-compliance.sh posthog-node-compliance:local \
-  "$HARNESS_IMAGE" v0 /absolute/new/legacy-reports
+  "$HARNESS_IMAGE" /absolute/new/analytics-reports
 bash compliance/node/v2/run-compliance.sh posthog-node-compliance:local \
-  "$HARNESS_IMAGE" v1 /absolute/new/analytics-reports
-bash compliance/node/v2/run-compliance.sh posthog-node-compliance:local \
-  "$HARNESS_IMAGE" v0 /absolute/new/legacy-acceptance acceptance
-bash compliance/node/v2/run-compliance.sh posthog-node-compliance:local \
-  "$HARNESS_IMAGE" v1 /absolute/new/analytics-acceptance acceptance
+  "$HARNESS_IMAGE" /absolute/new/analytics-acceptance acceptance
 ```
 
 The default suite is migration parity. Passing `acceptance` as the fifth argument selects the opted-in server acceptance cases. Use a new report directory for each invocation.
@@ -70,13 +66,13 @@ Pull the harness image before running. Each invocation creates a separate `--int
 
 ## CI activation and validation
 
-[Node SDK v2 compliance](../../../.github/workflows/sdk-compliance-tests-node-v2.yml) is the canonical SDK-owned workflow; there is no separate template to synchronize. It runs both profiles on PRs and pushes to `main` affecting the adapter, SDKs or build inputs, including its own workflow file, and supports manual dispatch. It checks out the actual PR head for pull requests or the triggering commit for push and manual runs, runs the adapter with only `contents: read`, and needs no secrets or registry login.
+[Node SDK v2 compliance](../../../.github/workflows/sdk-compliance-tests-node-v2.yml) is the canonical SDK-owned workflow; there is no separate template to synchronize. It runs the profile on PRs and pushes to `main` affecting the adapter, SDKs or build inputs, including its own workflow file, and supports manual dispatch. It checks out the actual PR head for pull requests or the triggering commit for push and manual runs, runs the adapter with only `contents: read`, and needs no secrets or registry login.
 
 The workflow pins public multi-platform image digests for harness release `1.16.0` and Node `24.21.0-bookworm-slim` directly in `HARNESS_IMAGE` and `NODE_IMAGE`. Image updates are reviewed workflow changes. Preparation rejects missing or malformed image identities; unavailable images fail during pull/build.
 
-When updating the pins, verify anonymous image access, `linux/amd64` support, the Debian-based Node build tools, the draft2 adapter protocol, and strict `check-report` support. Validate both profiles in GitHub Actions against the released images. Compliance is advisory: assertion, preparation and execution failures do not block the workflow. Raw exit codes and diagnostics remain in the artifacts. A separate reporting job reads those artifacts without checking out or executing the tested code, writes both suites for both profiles to the job log and summary, and creates or updates one bot-owned PR comment. The comment shows ✅ passed / ❌ non-passing / ⚠️ not-selected totals without listing successful cases. Expand each failure for its message, assertion code, exact failed-step source and, when matching diagnostics provide them, step text, operation, public getter arguments or wire field, and expected/actual values. Clean specs provenance links to the pinned `PostHog/sdk-specs` commit; otherwise the source remains plain text. Older reports retain their message and step source without inferred values. The run-artifacts link names the exact `node-v2-v0` / `node-v2-v1` artifact and the migration `reports/report.json.diagnostics.json` or acceptance `acceptance/report.json.diagnostics.json` file; search that file by `case_id` for full diagnostics. Missing or invalid reports are explicitly marked unavailable or incomplete. Diagnostics are size-limited and matched to the report run, profile, case and source before use. Published assertion fields are allowlisted, escaped and bounded; full wire requests are not published. Each suite/profile section shows at most 20 failures within a 24,000-byte detail budget, with omitted-case counts; the whole comment is limited to 60,000 UTF-8 bytes with an explicit truncation notice. Push, manual, fork and Dependabot runs retain the summary without posting a comment. A green CI check is not a conformance claim; a human decides whether the reported results are acceptable.
+When updating the pins, verify anonymous image access, `linux/amd64` support, the Debian-based Node build tools, the draft2 adapter protocol, and strict `check-report` support. Validate the profile in GitHub Actions against the released images. Compliance is advisory: assertion, preparation and execution failures do not block the workflow. Raw exit codes and diagnostics remain in the artifacts. A separate reporting job reads those artifacts without checking out or executing the tested code, writes both suites to the job log and summary, and creates or updates one bot-owned PR comment. The comment shows ✅ passed / ❌ non-passing / ⚠️ not-selected totals without listing successful cases. Expand each failure for its message, assertion code, exact failed-step source and, when matching diagnostics provide them, step text, operation, public getter arguments or wire field, and expected/actual values. Clean specs provenance links to the pinned `PostHog/sdk-specs` commit; otherwise the source remains plain text. Older reports retain their message and step source without inferred values. The run-artifacts link names the `node-v2-v1` artifact and the migration `reports/report.json.diagnostics.json` or acceptance `acceptance/report.json.diagnostics.json` file; search that file by `case_id` for full diagnostics. Missing or invalid reports are explicitly marked unavailable or incomplete. Diagnostics are size-limited and matched to the report run, profile, case and source before use. Published assertion fields are allowlisted, escaped and bounded; full wire requests are not published. Each suite section shows at most 20 failures within a 24,000-byte detail budget, with omitted-case counts; the whole comment is limited to 60,000 UTF-8 bytes with an explicit truncation notice. Push, manual, fork and Dependabot runs retain the summary without posting a comment. A green CI check is not a conformance claim; a human decides whether the reported results are acceptable.
 
-Each matrix job has an 85-minute limit, with 20 minutes for preparation, 35 minutes for migration and 25 minutes for acceptance (including bounded startup and cleanup), leaving time for artifact upload even after a step timeout. Preparation bounds the harness pull to 3 minutes, the fresh source build to 15 minutes, and build-identity export to 30 seconds. Bash `pipefail` preserves failures through log capture. Artifacts (`node-v2-v0` / `node-v2-v1`, retained for 14 days) are uploaded even after preparation or run failures: selected source and working-tree status, validated image identities, preparation output/exit, successful build identity, wrapper output, raw harness exit, strict report-check exit, separate migration and acceptance reports and diagnostics, and container/cleanup logs where produced. A build failure cannot produce `build.json`; its build output remains in `prepare.log`.
+The compliance job has an 85-minute limit, with 20 minutes for preparation, 35 minutes for migration and 25 minutes for acceptance (including bounded startup and cleanup), leaving time for artifact upload even after a step timeout. Preparation bounds the harness pull to 3 minutes, the fresh source build to 15 minutes, and build-identity export to 30 seconds. Bash `pipefail` preserves failures through log capture. The `node-v2-v1` artifact (retained for 14 days) is uploaded even after preparation or run failures: selected source and working-tree status, validated image identities, preparation output/exit, successful build identity, wrapper output, raw harness exit, strict report-check exit, separate migration and acceptance reports and diagnostics, and container/cleanup logs where produced. A build failure cannot produce `build.json`; its build output remains in `prepare.log`.
 
 Local script tests use Docker stand-ins to check prerequisite failures, build failures, exit propagation, and private-network lifecycle. They do not validate image availability, Docker builds, migrated fixtures, or hosted fork behavior. Validate those paths separately with the selected released images.
 
@@ -94,4 +90,4 @@ shellcheck --exclude=SC2329 compliance/node/v2/{prepare-ci,run-compliance}.sh
 node --test compliance/node/v2/{prepare-ci,run-compliance}.test.mjs
 ```
 
-Binding tests use public-method spies for exact translations; HTTP tests also exercise real installed packages in both formats/modes. Controlled SDK stand-ins test deadline, cleanup and process failures, not SDK conformance. Caller tests check raw failure exits and private-network lifecycle. Full migrated profiles and current-base comparisons are separate integration gates owned by the harness run.
+Binding tests use public-method spies for exact translations; HTTP tests also exercise real installed packages in both module formats. Controlled SDK stand-ins test deadline, cleanup and process failures, not SDK conformance. Caller tests check raw failure exits and private-network lifecycle. Full migrated profiles and current-base comparisons are separate integration gates owned by the harness run.
diff --git a/compliance/node/v2/binding.mjs b/compliance/node/v2/binding.mjs
index 6f2e0fa58c..17076bde10 100644
--- a/compliance/node/v2/binding.mjs
+++ b/compliance/node/v2/binding.mjs
@@ -104,9 +104,9 @@ const optionProperties = {
     process_person_profile: '$process_person_profile',
     product_tour_id: '$product_tour_id',
 }
-function capture(args, captureMode) {
+function capture(args) {
     if (!own(args, 'options')) return rename(args, captureFields, '/capture')
-    if (captureMode !== 'v1' || !object(args.options)) unsupported('/capture/options')
+    if (!object(args.options)) unsupported('/capture/options')
     checkKeys(args.options, Object.keys(optionProperties), '/capture/options')
     const mapped = rename(
         Object.fromEntries(Object.entries(args).filter(([key]) => key !== 'options')),
@@ -223,9 +223,8 @@ async function snapshotReads(snapshot, reads) {
     return { results }
 }
 export class Binding {
-    constructor(PostHog, captureMode = 'v0') {
+    constructor(PostHog) {
         this.PostHog = PostHog
-        this.captureMode = captureMode
         this.client = undefined
         this.exceptions = new Map()
     }
@@ -253,8 +252,7 @@ export class Binding {
             if (this.client === undefined)
                 return failure('unsupported_binding', 'before-setup', 'This instance API requires public construction')
             if (route === '/capture' || route === '/capture_ai') {
-                const mapped =
-                    route === '/capture' ? capture(args, this.captureMode) : rename(args, captureFields, route)
+                const mapped = route === '/capture' ? capture(args) : rename(args, captureFields, route)
                 if (own(mapped, 'timestamp')) mapped.timestamp = timestamp(mapped.timestamp)
                 if (own(mapped, 'sendFeatureFlags'))
                     mapped.sendFeatureFlags = rename(
diff --git a/compliance/node/v2/binding.test.mjs b/compliance/node/v2/binding.test.mjs
index ed96884226..bff9fc4f1b 100644
--- a/compliance/node/v2/binding.test.mjs
+++ b/compliance/node/v2/binding.test.mjs
@@ -10,7 +10,7 @@ const { PostHog } = createRequire(resolve(consumer, 'package.json'))('posthog-no
 
 // Observe the genuine packaged public constructor and replace only its public
 // methods. The binding never receives a different SDK-shaped implementation.
-async function spies(run, captureMode = 'v0') {
+async function spies(run) {
     const originals = new Map()
     const calls = []
     const results = {
@@ -43,7 +43,7 @@ async function spies(run, captureMode = 'v0') {
         },
     })
     try {
-        await run(new Binding(NativeConstructor, captureMode), calls, results)
+        await run(new Binding(NativeConstructor), calls, results)
     } finally {
         for (const [name, descriptor] of originals) {
             if (descriptor) Object.defineProperty(PostHog.prototype, name, descriptor)
@@ -105,7 +105,7 @@ test('local reload calls its public method with native arguments and results', a
 })
 
 test('AI capture invokes its public method once and preserves native results and timestamp input', async () => {
-    for (const mode of ['v0', 'v1']) {
+    {
         await spies(async (binding, calls, results) => {
             await setup(binding)
             const args = {
@@ -159,12 +159,12 @@ test('AI capture invokes its public method once and preserves native results and
             assert.equal(calls.filter(([name]) => name === 'capture' || name === 'flush').length, 0)
             results.captureAi = new Error('native AI failure')
             assert.equal((await binding.invoke('/capture_ai', {})).outcome.kind, 'thrown')
-        }, mode)
+        })
     }
 })
 
 test('identify and alias preserve exact public arguments, omission, native void and failures', async () => {
-    for (const mode of ['v0', 'v1']) {
+    {
         await spies(async (binding, calls, results) => {
             for (const route of ['/identify', '/alias']) {
                 assert.equal((await binding.invoke(route, {})).failure.code, 'before-setup')
@@ -224,12 +224,12 @@ test('identify and alias preserve exact public arguments, omission, native void
                 assert.deepEqual(await binding.invoke(`/${name}`, {}), thrown)
             }
             assert.equal(calls.filter(([name]) => ['capture', 'captureAi', 'flush'].includes(name)).length, 0)
-        }, mode)
+        })
     }
 })
 
 test('captureException constructs a native fixture and preserves positional arguments and outcomes', async () => {
-    for (const mode of ['v0', 'v1']) {
+    {
         await spies(async (binding, calls, results) => {
             assert.equal((await binding.invoke('/capture_exception', {})).failure.code, 'before-setup')
             await setup(binding)
@@ -268,7 +268,7 @@ test('captureException constructs a native fixture and preserves positional argu
             assert.equal(thrown.outcome.kind, 'thrown')
             assert.deepEqual(await binding.invoke('/capture_exception', { error }), thrown)
             assert.equal(calls.filter(([name]) => ['capture', 'captureAi', 'flush'].includes(name)).length, 0)
-        }, mode)
+        })
     }
 })
 
@@ -300,7 +300,7 @@ test('captureException reports unsupported or unrepresentable fixture arguments
 })
 
 test('groupIdentify preserves public arguments, omission and native outcomes', async () => {
-    for (const mode of ['v0', 'v1']) {
+    {
         await spies(async (binding, calls, results) => {
             assert.equal((await binding.invoke('/group_identify', {})).failure.code, 'before-setup')
             await setup(binding)
@@ -360,7 +360,7 @@ test('groupIdentify preserves public arguments, omission and native outcomes', a
             assert.equal(thrown.outcome.error.kind, 'exception')
             assert.deepEqual(await binding.invoke('/group_identify', {}), thrown)
             assert.equal(calls.filter(([name]) => ['capture', 'captureAi', 'flush'].includes(name)).length, 0)
-        }, mode)
+        })
     }
 })
 
@@ -512,7 +512,6 @@ test('unsupported supplied fields remain attributed gaps before native work', as
         await setup(binding)
         for (const [route, args] of [
             ['/capture', { event: 'event', set: null }],
-            ['/capture', { options: {} }],
             ['/capture', { send_feature_flags: { device_id: 'd' } }],
             ['/flush', { timeout_ms: 0 }],
             ['/get_feature_flag', { key: 'f', fresh: false }],
@@ -595,4 +594,4 @@ test('analytics-v1 options translate to native input properties without coercion
         ])
             assert.equal((await binding.invoke('/capture', args)).failure.kind, kind)
         assert.equal(calls.length, 4)
-    }, 'v1'))
+    }))
diff --git a/compliance/node/v2/report-ci.test.mjs b/compliance/node/v2/report-ci.test.mjs
index 5e4d90dc9a..4ff8f0a35e 100644
--- a/compliance/node/v2/report-ci.test.mjs
+++ b/compliance/node/v2/report-ci.test.mjs
@@ -136,7 +136,7 @@ async function exercise(options = {}) {
         },
     }
     try {
-        for (const mode of ['v0', 'v1']) {
+        for (const mode of ['v1']) {
             if (options.missing?.includes(mode)) continue
             const dir = join(root, `node-v2-${mode}`)
             mkdirSync(dir)
@@ -180,14 +180,13 @@ async function exercise(options = {}) {
     }
 }
 
-test('creates one combined comment for both profiles and writes the same summary', async () => {
+test('creates one combined comment for both suites and writes the same summary', async () => {
     const { summary, calls, error } = await exercise()
     assert.equal(error, undefined)
-    assert.match(summary, /Capture v0/)
-    assert.match(summary, /Capture v1/)
-    assert.match(summary, /Capture v0 — acceptance/)
+    assert.doesNotMatch(summary, /Capture v0/)
+    assert.match(summary, /Capture v1 — acceptance/)
     assert.match(summary, /Capture v1 — migration/)
-    assert.equal((summary.match(/All selected cases passed/g) || []).length, 4)
+    assert.equal((summary.match(/All selected cases passed/g) || []).length, 2)
     assert.doesNotMatch(summary, /example|<details>/)
     assert.equal(calls[0], 'summary')
     assert.equal(calls.at(-1)[0], 'create')
@@ -215,31 +214,30 @@ test('shows acceptance failures without losing migration results', async () => {
     assert.match(summary, /Capture v1 — acceptance[\s\S]*❌ 1 non-passing/)
     assert.match(summary, /acceptance\/report.json.diagnostics.json/)
     assert.match(summary, /identify-example/)
-    assert.match(summary, /Capture v0 — migration/)
-    assert.equal((summary.match(/All selected cases passed/g) || []).length, 2)
+    assert.match(summary, /Capture v1 — migration/)
+    assert.equal((summary.match(/All selected cases passed/g) || []).length, 1)
 })
 
-test('shows failed cases without losing the other profile', async () => {
+test('shows migration failures without losing acceptance results', async () => {
     const { summary, error } = await exercise({
-        reports: { v0: report('v0', 'failed_assertion') },
+        reports: { v1: report('v1', 'failed_assertion') },
         exit: '1',
         validation: '1',
     })
     assert.equal(error, undefined)
-    assert.match(summary, /✅ 0 passed \/ ❌ 1 non-passing/)
+    assert.match(summary, /Capture v1 — migration[\s\S]*✅ 0 passed \/ ❌ 1 non-passing/)
     assert.match(summary, /Unexpected flag value/)
-    assert.match(summary, /Capture v1/)
-    assert.equal((summary.match(/All selected cases passed/g) || []).length, 2)
+    assert.match(summary, /Capture v1 — acceptance/)
+    assert.equal((summary.match(/All selected cases passed/g) || []).length, 1)
 })
 
 for (const options of [
-    { missing: ['v0'] },
-    { missing: ['v0', 'v1'] },
-    { reports: { v0: 'not json' } },
+    { missing: ['v1'] },
+    { reports: { v1: 'not json' } },
     { acceptanceReports: { v1: 'not json' } },
-    { missingAcceptance: ['v0'] },
+    { missingAcceptance: ['v1'] },
     { source: 'wrong-sha' },
-    { reports: { v0: report('v1') } },
+    { reports: { v1: report('v0') } },
 ]) {
     test(`reports unavailable/incomplete data: ${JSON.stringify(options)}`, async () => {
         const { summary, calls, error } = await exercise(options)
@@ -252,7 +250,7 @@ for (const options of [
 for (const options of [{ noPr: true }, { fork: true }, { actor: 'dependabot[bot]' }, { currentSha: 'b'.repeat(40) }]) {
     test(`retains summary without posting: ${JSON.stringify(options)}`, async () => {
         const { summary, calls } = await exercise(options)
-        assert.match(summary, /Capture v0/)
+        assert.match(summary, /Capture v1/)
         assert.ok(!calls.some((call) => Array.isArray(call)))
     })
 }
@@ -264,30 +262,27 @@ test('preserves summary when comment publication fails', async () => {
 })
 
 test('escapes artifact markup and mentions and bounds the comment size', async () => {
-    const data = report('v0', 'failed_assertion')
+    const data = report('v1', 'failed_assertion')
     data.results[0].case_id = '<script>@someone **bad**</script>'
     data.results[0].result.failure.message = '[click](https://example.com)'.repeat(1000)
     data.results = Array(100).fill(data.results[0])
-    const v1 = JSON.parse(JSON.stringify(data))
-    v1.profiles[0].id = 'node-analytics-v1'
-    for (const result of v1.results) result.profile_id = 'node-analytics-v1'
-    const { summary } = await exercise({ reports: { v0: data, v1 }, diagnostics: { v0: null, v1: null } })
+    const { summary } = await exercise({ reports: { v1: data }, diagnostics: { v1: null } })
     assert.doesNotMatch(summary, /<script>|@someone|\[click\]/)
     assert.match(summary, /80 more non-passing/)
     assert.ok(summary.length < 65536)
 })
 
 test('empty selections retain zero totals and harness errors', async () => {
-    const data = report('v0')
+    const data = report('v1')
     data.results = []
     data.errors = [{ message: 'fixture startup failed' }]
-    const { summary } = await exercise({ reports: { v0: data } })
+    const { summary } = await exercise({ reports: { v1: data } })
     assert.match(summary, /fixture startup failed/)
     assert.match(summary, /✅ 0 passed \/ ❌ 0 non-passing/)
 })
 
 test('renders attributed getter failure, public arguments, expected/actual, specs commit and artifact drill-down', async () => {
-    const data = report('v0', 'failed_assertion')
+    const data = report('v1', 'failed_assertion')
     const diagnostic = diagnostics(data)
     diagnostic.cases[0].wire_requests = [{ headers: { authorization: 'wire-secret' } }]
     Object.assign(diagnostic.cases[0].failure.details, { headers: 'header-secret', unknown: 'unknown-secret' })
@@ -296,7 +291,7 @@ test('renders attributed getter failure, public arguments, expected/actual, spec
         config: { token: 'config-secret' },
     })
     diagnostic.cases[0].failure.details.arguments.person_properties.token = 'nested-secret'
-    const { summary } = await exercise({ reports: { v0: data }, diagnostics: { v0: diagnostic } })
+    const { summary } = await exercise({ reports: { v1: data }, diagnostics: { v1: diagnostic } })
     assert.match(summary, /<details>\n<summary>❌ example/)
     assert.match(summary, /Then the local flag value is false/)
     assert.match(summary, /Operation: <code>\/get&#95;feature&#95;flag<\/code>/)
@@ -305,7 +300,7 @@ test('renders attributed getter failure, public arguments, expected/actual, spec
     assert.match(summary, /Actual value:<pre>true<\/pre>/)
     assert.ok(summary.includes(`https://github.com/PostHog/sdk-specs/blob/${specsCommit}/${source.path}#L1187`))
     assert.doesNotMatch(summary, /-secret|cccccccccccccccc|unknown|wire_requests/)
-    assert.match(summary, /node-v2-v0/)
+    assert.match(summary, /node-v2-v1/)
     assert.match(summary, /reports\/report.json.diagnostics.json/)
     assert.match(summary, /actions\/runs\/123#artifacts/)
 })
@@ -329,10 +324,10 @@ for (const [expected, actual, rendered] of [
     [0, { kind: 'value', value: { kind: 'value', value: 1 } }, 'Actual value:<pre>{"kind":"value","value":1}</pre>'],
 ]) {
     test(`renders actual values distinctly from field states and SDK outcomes: ${JSON.stringify(actual)}`, async () => {
-        const data = report('v0', 'failed_assertion')
+        const data = report('v1', 'failed_assertion')
         const { summary } = await exercise({
-            reports: { v0: data },
-            diagnostics: { v0: diagnostics(data, { operation: '/get_feature_flag', expected, actual }) },
+            reports: { v1: data },
+            diagnostics: { v1: diagnostics(data, { operation: '/get_feature_flag', expected, actual }) },
         })
         const decode = (text) => text.replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
         assert.ok(decode(summary).includes(`Expected:<pre>${JSON.stringify(expected)}</pre>`))
@@ -341,11 +336,11 @@ for (const [expected, actual, rendered] of [
 }
 
 test('retains bounded, escaped error details for a thrown outcome', async () => {
-    const data = report('v0', 'failed_assertion')
+    const data = report('v1', 'failed_assertion')
     const { summary } = await exercise({
-        reports: { v0: data },
+        reports: { v1: data },
         diagnostics: {
-            v0: diagnostics(data, {
+            v1: diagnostics(data, {
                 operation: '/get_feature_flag',
                 expected: true,
                 actual: { kind: 'thrown', error: { message: '<failure>', token: 'secret-token' } },
@@ -359,11 +354,11 @@ test('retains bounded, escaped error details for a thrown outcome', async () =>
 
 for (const operation of ['/flags', '/flags/']) {
     test(`renders remote wire assertion fields and missing values for ${operation}`, async () => {
-        const data = report('v0', 'failed_assertion')
+        const data = report('v1', 'failed_assertion')
         const { summary } = await exercise({
-            reports: { v0: data },
+            reports: { v1: data },
             diagnostics: {
-                v0: diagnostics(data, {
+                v1: diagnostics(data, {
                     operation,
                     field: 'person_properties.email',
                     expected: 'user@example.com',
@@ -379,10 +374,10 @@ for (const operation of ['/flags', '/flags/']) {
 }
 
 test('old diagnostics preserve exact failed step without invented values', async () => {
-    const data = report('v0', 'failed_assertion')
+    const data = report('v1', 'failed_assertion')
     const diagnostic = diagnostics(data)
     delete diagnostic.cases[0].failure
-    const { summary } = await exercise({ reports: { v0: data }, diagnostics: { v0: diagnostic } })
+    const { summary } = await exercise({ reports: { v1: data }, diagnostics: { v1: diagnostic } })
     assert.match(summary, /Unexpected flag value/)
     assert.match(summary, /local-evaluation-v1.feature:1187/)
     assert.doesNotMatch(summary, /Expected:|Actual (value|field|outcome):|Arguments:|Detailed diagnostics unavailable/)
@@ -398,7 +393,7 @@ for (const [name, mutate] of [
     [
         'profile',
         (d) => {
-            d.cases[0].profile_id = 'node-analytics-v1'
+            d.cases[0].profile_id = 'node-legacy'
         },
     ],
     [
@@ -424,12 +419,12 @@ for (const [name, mutate] of [
     ['missing', () => null],
 ]) {
     test(`rejects ${name} diagnostics without losing report totals and source`, async () => {
-        const data = report('v0', 'failed_assertion')
+        const data = report('v1', 'failed_assertion')
         const diagnostic = diagnostics(data)
         const replacement = mutate(diagnostic)
         const { summary } = await exercise({
-            reports: { v0: data },
-            diagnostics: { v0: replacement === undefined ? diagnostic : replacement },
+            reports: { v1: data },
+            diagnostics: { v1: replacement === undefined ? diagnostic : replacement },
         })
         assert.match(summary, /Detailed diagnostics unavailable or mismatched/)
         assert.match(summary, /❌ 1 non-passing/)
@@ -439,10 +434,10 @@ for (const [name, mutate] of [
 }
 
 test('rejects failure details attributed to a different step', async () => {
-    const data = report('v0', 'failed_assertion')
+    const data = report('v1', 'failed_assertion')
     const diagnostic = diagnostics(data)
     diagnostic.cases[0].failure.failed_step = { ...failedStep, index: 6 }
-    const { summary } = await exercise({ reports: { v0: data }, diagnostics: { v0: diagnostic } })
+    const { summary } = await exercise({ reports: { v1: data }, diagnostics: { v1: diagnostic } })
     assert.match(summary, /Unexpected flag value/)
     assert.doesNotMatch(summary, /Expected:|Actual (value|field|outcome):|Then the local/)
 })
@@ -455,10 +450,10 @@ for (const provenance of [
     { dirty: false, commit: 'https://example.com' },
 ]) {
     test(`does not link uncertain specs provenance: ${JSON.stringify(provenance)}`, async () => {
-        const data = report('v0', 'failed_assertion')
+        const data = report('v1', 'failed_assertion')
         const diagnostic = diagnostics(data)
         diagnostic.distribution.source = provenance
-        const { summary } = await exercise({ reports: { v0: data }, diagnostics: { v0: diagnostic } })
+        const { summary } = await exercise({ reports: { v1: data }, diagnostics: { v1: diagnostic } })
         assert.match(summary, /local-evaluation-v1.feature:1187/)
         assert.doesNotMatch(summary, /sdk-specs\/blob/)
     })
@@ -473,23 +468,23 @@ for (const path of [
     'a\nbad.feature',
 ]) {
     test(`does not link unsafe source path: ${JSON.stringify(path)}`, async () => {
-        const data = report('v0', 'failed_assertion')
+        const data = report('v1', 'failed_assertion')
         data.results[0].result.failure.failed_step = { index: 5, source: { ...source, path } }
-        const { summary } = await exercise({ reports: { v0: data } })
+        const { summary } = await exercise({ reports: { v1: data } })
         assert.doesNotMatch(summary, /sdk-specs\/blob/)
     })
 }
 
 test('encodes source URL path segments', async () => {
-    const data = report('v0', 'failed_assertion')
+    const data = report('v1', 'failed_assertion')
     data.results[0].result.failure.failed_step = { index: 5, source: { ...source, path: 'migration/a b#(c).feature' } }
-    const { summary } = await exercise({ reports: { v0: data } })
+    const { summary } = await exercise({ reports: { v1: data } })
     assert.match(summary, /\/migration\/a%20b%23%28c%29.feature#L1118/)
 })
 
-test('bounds worst-case escaped and multibyte failures across both profiles without broken details', async () => {
+test('bounds worst-case escaped and multibyte failures across both suites without broken details', async () => {
     const reports = {}
-    for (const mode of ['v0', 'v1']) {
+    for (const mode of ['v1']) {
         const data = report(mode, 'failed_assertion')
         const failure = data.results[0]
         failure.result.failure.message = '<@[`&\\*_\n'.repeat(1000)
@@ -509,10 +504,15 @@ test('bounds worst-case escaped and multibyte failures across both profiles with
             return [mode, d]
         })
     )
-    const { summary } = await exercise({ reports, diagnostics: allDiagnostics })
+    const { summary } = await exercise({
+        reports,
+        diagnostics: allDiagnostics,
+        acceptanceReports: reports,
+        acceptanceDiagnostics: allDiagnostics,
+    })
     assert.ok(Buffer.byteLength(summary, 'utf8') <= 60000)
-    assert.match(summary, /Capture v0/)
-    assert.match(summary, /Capture v1/)
+    assert.match(summary, /Capture v1 — acceptance/)
+    assert.match(summary, /Capture v1 — migration/)
     assert.match(summary, /more non-passing cases/)
     assert.doesNotMatch(summary, /<script>|@mention|&#\d*…/)
     assert.equal((summary.match(/<details>/g) || []).length, (summary.match(/<\/details>/g) || []).length)
@@ -522,7 +522,7 @@ test('bounds worst-case escaped and multibyte failures across both profiles with
 test('enforces the overall UTF-8 comment budget with an explicit artifact truncation notice', async () => {
     const reports = {}
     const allDiagnostics = {}
-    for (const mode of ['v0', 'v1']) {
+    for (const mode of ['v1']) {
         const data = report(mode, 'failed_assertion')
         data.results[0].result.failure.message = 'x'.repeat(400)
         data.results = Array.from({ length: 100 }, (_, i) => ({
@@ -534,11 +534,15 @@ test('enforces the overall UTF-8 comment budget with an explicit artifact trunca
         allDiagnostics[mode] = diagnostics(data)
         for (const c of allDiagnostics[mode].cases) delete c.failure
     }
-    const { summary, calls } = await exercise({ reports, diagnostics: allDiagnostics })
+    const { summary, calls } = await exercise({
+        reports,
+        diagnostics: allDiagnostics,
+        acceptanceReports: reports,
+        acceptanceDiagnostics: allDiagnostics,
+    })
     assert.ok(Buffer.byteLength(summary, 'utf8') <= 60000)
     assert.match(summary, /Report truncated; see \[workflow artifacts\]/)
-    assert.match(summary, /Capture v0/)
-    assert.match(summary, /Capture v1/)
+    assert.match(summary, /Capture v1 — acceptance/)
     assert.equal((summary.match(/<details>/g) || []).length, (summary.match(/<\/details>/g) || []).length)
     assert.equal(calls.at(-1)[1].body, summary)
 })
diff --git a/compliance/node/v2/run-compliance.sh b/compliance/node/v2/run-compliance.sh
index e8fa576352..f69e1c8868 100644
--- a/compliance/node/v2/run-compliance.sh
+++ b/compliance/node/v2/run-compliance.sh
@@ -9,21 +9,16 @@ run_docker() { node "$script_dir/run-command.mjs" "$1" docker "${@:2}"; }
 docker() { run_docker "$command_timeout" "$@"; }
 adapter_image=${1:?adapter image required}
 harness_image=${2:?harness image required}
-mode=${3:?v0 or v1 required}
-reports=${4:?new absolute report directory required}
-suite=${5:-migration}
+reports=${3:?new absolute report directory required}
+suite=${4:-migration}
 case "$suite" in
     migration|acceptance) ;;
     *) echo 'Unknown compliance suite' >&2; exit 2 ;;
 esac
-case "$mode" in
-    v0) profile=node-legacy ;;
-    v1) profile=node-analytics-v1 ;;
-    *) echo 'Unknown capture mode' >&2; exit 2 ;;
-esac
+profile=node-analytics-v1
 [[ "$reports" = /* ]] || { echo 'Absolute report directory required' >&2; exit 2; }
 mkdir "$reports"
-network="node-v2-${mode}-$$"
+network="node-v2-$$"
 adapter="${network}-adapter"
 harness="${network}-harness"
 check="${network}-check"
@@ -57,7 +52,7 @@ trap 'exit 143' TERM
 docker network create --internal "$network" > "$reports/network.txt"
 network_created=true
 docker create --name "$adapter" --network "$network" --network-alias adapter \
-    -e HOST=0.0.0.0 -e PORT=8080 -e "POSTHOG_CAPTURE_MODE=$mode" "$adapter_image" > "$reports/adapter.txt"
+    -e HOST=0.0.0.0 -e PORT=8080 "$adapter_image" > "$reports/adapter.txt"
 adapter_created=true
 docker start "$adapter" > /dev/null
 ready=false
diff --git a/compliance/node/v2/run-compliance.test.mjs b/compliance/node/v2/run-compliance.test.mjs
index 4ac6d76fa8..cb15e862ed 100644
--- a/compliance/node/v2/run-compliance.test.mjs
+++ b/compliance/node/v2/run-compliance.test.mjs
@@ -6,12 +6,10 @@ import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
 
 const script = new URL('./run-compliance.sh', import.meta.url).pathname
-for (const [scenario, exit, mode = 'v0', suite] of [
+for (const [scenario, exit, suite] of [
     ['success', 0],
-    ['success', 0, 'v1'],
-    ['success', 0, 'v0', 'acceptance'],
-    ['success', 0, 'v1', 'acceptance'],
-    ['cli-failed', 7, 'v1', 'acceptance'],
+    ['success', 0, 'acceptance'],
+    ['cli-failed', 7, 'acceptance'],
     ['cli-and-cleanup-failed', 7],
     ['cli-failed', 7],
     ['missing-report', 1],
@@ -26,7 +24,7 @@ for (const [scenario, exit, mode = 'v0', suite] of [
     ['startup-hung', 1],
     ['cleanup-hung', 1],
 ]) {
-    test(`compliance caller (${mode}, ${suite || 'migration'}): ${scenario}`, (t) => {
+    test(`compliance caller (${suite || 'migration'}): ${scenario}`, (t) => {
         const root = mkdtempSync(join(tmpdir(), 'node-caller-test-'))
         t.after(() => rmSync(root, { recursive: true, force: true }))
         const bin = join(root, 'bin')
@@ -70,7 +68,7 @@ esac
         const started = Date.now()
         const result = spawnSync(
             'bash',
-            [script, 'adapter:test', 'harness:test', mode, join(root, 'reports'), ...(suite ? [suite] : [])],
+            [script, 'adapter:test', 'harness:test', join(root, 'reports'), ...(suite ? [suite] : [])],
             {
                 env: {
                     ...process.env,
@@ -92,11 +90,11 @@ esac
         assert.ok(!commands.includes('--publish'))
         assert.ok(commands.includes('network rm'))
         if (!scenario.startsWith('startup-')) {
-            const profile = mode === 'v0' ? 'node-legacy' : 'node-analytics-v1'
+            const profile = 'node-analytics-v1'
             assert.ok(commands.includes(`check-report --report /reports/report.json --profile ${profile}`))
             assert.ok(commands.includes(`run --${suite || 'migration'}-suite --adapter-url`))
             assert.ok(commands.includes(`--profile ${profile} --timeout-ms`))
-            assert.ok(commands.includes(`POSTHOG_CAPTURE_MODE=${mode}`))
+            assert.ok(!commands.includes('POSTHOG_CAPTURE_MODE'))
             assert.ok(commands.includes('--network none'))
             assert.equal(
                 readFileSync(join(root, 'reports/cli-exit.txt'), 'utf8').trim(),
diff --git a/compliance/node/v2/server.mjs b/compliance/node/v2/server.mjs
index 354d3cf64f..d3d1506333 100644
--- a/compliance/node/v2/server.mjs
+++ b/compliance/node/v2/server.mjs
@@ -47,7 +47,7 @@ function parseRequest(body) {
 }
 
 class Fixture {
-    constructor(consumer, mode, format) {
+    constructor(consumer, format) {
         const worker = new URL('./worker.mjs', import.meta.url).href
         const load =
             format === 'esm'
@@ -62,7 +62,6 @@ class Fixture {
             ],
             {
                 cwd: consumer,
-                env: { ...process.env, POSTHOG_CAPTURE_MODE: mode },
                 stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
             }
         )
@@ -128,17 +127,15 @@ class Fixture {
     }
 }
 
-export async function startServer({ consumer, mode = 'v0', format = 'cjs', host = '127.0.0.1', port = 8080 }) {
-    requireRequest(['v0', 'v1'].includes(mode), 'Invalid POSTHOG_CAPTURE_MODE')
+export async function startServer({ consumer, format = 'cjs', host = '127.0.0.1', port = 8080 }) {
     requireRequest(['cjs', 'esm'].includes(format), 'Invalid POSTHOG_NODE_MODULE')
     requireRequest(typeof consumer === 'string' && consumer.length > 0, 'POSTHOG_NODE_CONSUMER required')
     requireRequest(Number.isInteger(port) && port >= 0 && port <= 65535, 'Invalid PORT')
     const profile = {
-        id: mode === 'v0' ? 'node-legacy' : 'node-analytics-v1',
+        id: 'node-analytics-v1',
         sdk_type: 'server',
         sdk_capabilities: [
-            ...(mode === 'v0' ? ['capture_v0', 'capture_v0_batch'] : ['capture_v1']),
-            'capture_ai_v0',
+            'capture_v1',
             'encoding_gzip',
             'flags_v2',
             'flags_getter_remote_uncached',
@@ -172,7 +169,7 @@ export async function startServer({ consumer, mode = 'v0', format = 'cjs', host
             identifier(data.case_id)
             requireRequest(data.profile_id === profile.id, 'Unknown profile')
             requireRequest(!fixtures.has(id), 'Duplicate fixture_id')
-            const fixture = new Fixture(resolve(consumer), mode, format)
+            const fixture = new Fixture(resolve(consumer), format)
             fixtures.set(id, fixture)
             const ready = await fixture.exchange(null, milliseconds)
             requireRequest(ready.ready === true, 'SDK process not ready')
@@ -249,7 +246,6 @@ export async function startServer({ consumer, mode = 'v0', format = 'cjs', host
 if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
     const adapter = await startServer({
         consumer: process.env.POSTHOG_NODE_CONSUMER,
-        mode: process.env.POSTHOG_CAPTURE_MODE ?? 'v0',
         format: process.env.POSTHOG_NODE_MODULE ?? 'cjs',
         host: process.env.HOST ?? '127.0.0.1',
         port: Number(process.env.PORT ?? 8080),
diff --git a/compliance/node/v2/server.test.mjs b/compliance/node/v2/server.test.mjs
index 8efb5e76ef..8c11c9a98e 100644
--- a/compliance/node/v2/server.test.mjs
+++ b/compliance/node/v2/server.test.mjs
@@ -31,7 +31,7 @@ async function harness(t, options = {}) {
         post('fixtures/allocate', {
             fixture_id,
             case_id: 'test',
-            profile_id: options.mode === 'v1' ? 'node-analytics-v1' : 'node-legacy',
+            profile_id: 'node-analytics-v1',
             timeout_ms,
         })
     const invoke = async (route, args = {}, fixture_id = 'f', timeout_ms = 5000) =>
@@ -48,7 +48,7 @@ async function harness(t, options = {}) {
     return { adapter, post, allocate, invoke, close }
 }
 
-for (const mode of ['v0', 'v1'])
+for (const mode of ['v1'])
     for (const format of ['cjs', 'esm']) {
         test(`public ${format}/${mode}: identify, alias and groupIdentify deliver literal properties after flush`, async (t) => {
             const traffic = []
@@ -68,7 +68,7 @@ for (const mode of ['v0', 'v1'])
                         mock.close(done)
                     })
             )
-            const { post, allocate, invoke, close } = await harness(t, { mode, format })
+            const { post, allocate, invoke, close } = await harness(t, { format })
             const negotiation = await post('negotiate', { protocol })
             assert.ok(negotiation.supported_routes.includes('/identify'))
             assert.ok(negotiation.supported_routes.includes('/alias'))
@@ -137,7 +137,7 @@ for (const mode of ['v0', 'v1'])
                 assert.deepEqual(await invoke('/flush'), { kind: 'sdk', outcome: { kind: 'void' } })
                 assert.equal(traffic.length, count + 1)
                 const request = traffic.at(-1)
-                assert.ok(request.path.startsWith(mode === 'v0' ? '/batch' : '/i/v1/analytics/events'))
+                assert.ok(request.path.startsWith('/i/v1/analytics/events'))
                 assert.equal(request.body.batch.length, 1)
                 const event = request.body.batch[0]
                 assert.equal(event.event, expectedEvent)
@@ -174,7 +174,7 @@ for (const mode of ['v0', 'v1'])
                         mock.close(done)
                     })
             )
-            const { post, allocate, invoke, close } = await harness(t, { mode, format })
+            const { post, allocate, invoke, close } = await harness(t, { format })
             const negotiation = await post('negotiate', { protocol })
             assert.ok(negotiation.supported_routes.includes('/capture_exception'))
             await allocate()
@@ -206,7 +206,7 @@ for (const mode of ['v0', 'v1'])
                 assert.deepEqual(await invoke('/flush'), { kind: 'sdk', outcome: { kind: 'void' } })
                 assert.equal(traffic.length, count + 1)
                 const request = traffic.at(-1)
-                assert.ok(request.path.startsWith(mode === 'v0' ? '/batch' : '/i/v1/analytics/events'))
+                assert.ok(request.path.startsWith('/i/v1/analytics/events'))
                 assert.equal(request.body.batch.length, 1)
                 const event = request.body.batch[0]
                 assert.equal(event.event, '$exception')
@@ -261,7 +261,7 @@ for (const mode of ['v0', 'v1'])
                         mock.close(done)
                     })
             )
-            const { post, allocate, invoke, close } = await harness(t, { mode, format })
+            const { post, allocate, invoke, close } = await harness(t, { format })
             const negotiation = await post('negotiate', { protocol })
             assert.equal(negotiation.protocol, protocol)
             assert.deepEqual(negotiation.profiles[0].fixture_capabilities, ['storage.empty.v1'])
@@ -290,7 +290,7 @@ for (const mode of ['v0', 'v1'])
                 { kind: 'void' }
             )
             assert.deepEqual((await invoke('/flush')).outcome, { kind: 'void' })
-            const capture = traffic.find(({ path }) => path.startsWith(mode === 'v0' ? '/batch' : '/i/v1/analytics'))
+            const capture = traffic.find(({ path }) => path.startsWith('/i/v1/analytics/events'))
             assert.ok(capture)
             assert.ok(capture.body.includes('slice'))
             assert.deepEqual(
@@ -403,14 +403,14 @@ test('transport errors remain non-200; SDK throws are completions and case IDs c
     await post('negotiate', { protocol: 'obsolete' }, 400)
     await post(
         'fixtures/allocate',
-        { fixture_id: 'bad', case_id: 'test', profile_id: 'node-legacy', timeout_ms: 60001 },
+        { fixture_id: 'bad', case_id: 'test', profile_id: 'node-analytics-v1', timeout_ms: 60001 },
         400
     )
     await post('invoke', { fixture_id: 'missing', call_id: 'x', route: '/flush', args: {}, timeout_ms: 1000 }, 400)
     await allocate()
     await post(
         'fixtures/allocate',
-        { fixture_id: 'f', case_id: 'test', profile_id: 'node-legacy', timeout_ms: 1000 },
+        { fixture_id: 'f', case_id: 'test', profile_id: 'node-analytics-v1', timeout_ms: 1000 },
         400
     )
     const data = {
@@ -599,7 +599,7 @@ test('an invalid consumer directory fails allocation within its deadline', async
     const { post } = await harness(t, { consumer: '/nonexistent/node-compliance-consumer' })
     await post(
         'fixtures/allocate',
-        { fixture_id: 'f', case_id: 'test', profile_id: 'node-legacy', timeout_ms: 100 },
+        { fixture_id: 'f', case_id: 'test', profile_id: 'node-analytics-v1', timeout_ms: 100 },
         400
     )
 })
@@ -610,7 +610,7 @@ test('missing public package fails allocation rather than claiming execution', a
     const { post } = await harness(t, { consumer: root })
     await post(
         'fixtures/allocate',
-        { fixture_id: 'f', case_id: 'test', profile_id: 'node-legacy', timeout_ms: 1000 },
+        { fixture_id: 'f', case_id: 'test', profile_id: 'node-analytics-v1', timeout_ms: 1000 },
         400
     )
 })
diff --git a/compliance/node/v2/snapshot-http.test.mjs b/compliance/node/v2/snapshot-http.test.mjs
index 8ae18e1cef..8eb810f842 100644
--- a/compliance/node/v2/snapshot-http.test.mjs
+++ b/compliance/node/v2/snapshot-http.test.mjs
@@ -10,7 +10,7 @@ const consumer = process.env.POSTHOG_NODE_CONSUMER
 if (!consumer) throw new Error('Set POSTHOG_NODE_CONSUMER to an installed consumer')
 const value = (data) => ({ kind: 'value', value: data })
 
-for (const mode of ['v0', 'v1'])
+for (const mode of ['v1'])
     for (const format of ['cjs', 'esm']) {
         test(`installed public snapshot HTTP: ${mode}/${format}`, async (t) => {
             const traffic = []
@@ -35,7 +35,7 @@ for (const mode of ['v0', 'v1'])
             })
             mock.listen(0, '127.0.0.1')
             await once(mock, 'listening')
-            const adapter = await startServer({ consumer, mode, format, port: 0 })
+            const adapter = await startServer({ consumer, format, port: 0 })
             t.after(async () => {
                 await adapter.close()
                 mock.closeAllConnections()
@@ -55,7 +55,7 @@ for (const mode of ['v0', 'v1'])
                 await post('fixtures/allocate', {
                     fixture_id: id,
                     case_id: 'snapshot',
-                    profile_id: mode === 'v0' ? 'node-legacy' : 'node-analytics-v1',
+                    profile_id: 'node-analytics-v1',
                     timeout_ms: 5000,
                 })
                 await invoke(id, '/setup', {
diff --git a/compliance/node/v2/worker.mjs b/compliance/node/v2/worker.mjs
index 7345e7102f..2d6c6f227c 100644
--- a/compliance/node/v2/worker.mjs
+++ b/compliance/node/v2/worker.mjs
@@ -3,7 +3,7 @@ import { Binding } from './binding.mjs'
 // A process per case isolates SDK timers, environment selection, and late traffic.
 // Only the public lifecycle is used; a failed deadline kills the process.
 export function start(PostHog) {
-    const binding = new Binding(PostHog, process.env.POSTHOG_CAPTURE_MODE)
+    const binding = new Binding(PostHog)
     process.on('message', async ({ route, args, close }) => {
         try {
             if (close) {
diff --git a/examples/example-convex/convex/example.test.ts b/examples/example-convex/convex/example.test.ts
index 31f9043e3b..a6285bc467 100644
--- a/examples/example-convex/convex/example.test.ts
+++ b/examples/example-convex/convex/example.test.ts
@@ -6,8 +6,8 @@ import { api, components } from './_generated/api.js'
 // Keep a guard above Jest's 5s default; scheduled functions are driven deterministically below.
 vi.setConfig({ testTimeout: 15000 })
 
-// posthog-node sends events to the legacy `/batch/` endpoint or the capture v1 analytics endpoint.
-const CAPTURE_PATHS = ['/batch/', '/i/v1/analytics/events']
+// posthog-node sends events to the capture v1 analytics endpoint.
+const CAPTURE_PATHS = ['/i/v1/analytics/events']
 
 // Collect all fetch calls for assertion
 let fetchCalls: Array<{ url: string; headers: Record<string, string>; body: unknown }> = []
@@ -62,11 +62,6 @@ function batchCalls() {
     return fetchCalls.filter((c) => CAPTURE_PATHS.some((path) => new URL(c.url).pathname === path))
 }
 
-// The project key travels as `api_key` in a legacy body and as a bearer token in capture v1.
-function apiKeyOf(call: (typeof fetchCalls)[number]): string | undefined {
-    return (call.body as { api_key?: string }).api_key ?? call.headers.Authorization?.replace(/^Bearer /, '')
-}
-
 // Fails every capture request with `status`, whichever endpoint the client uses.
 function captureStatus(status: number): Record<string, number> {
     return Object.fromEntries(CAPTURE_PATHS.map((path) => [path, status]))
@@ -121,7 +116,9 @@ describe('capture', () => {
         await finishScheduledFunctions(t)
 
         expect(batchCalls().length).toBeGreaterThanOrEqual(1)
-        expect(apiKeyOf(batchCalls()[0])).toBe('phc_test_key')
+        // Capture v1 authenticates with a bearer token instead of an api_key in the body.
+        expect(batchCalls()[0].headers.Authorization).toBe('Bearer phc_test_key')
+        expect(batchCalls()[0].body).not.toHaveProperty('api_key')
 
         const event = firstBatchEvent()
         expect(event.distinct_id).toBe('user-123')
diff --git a/packages/ai/harness/collector.test.ts b/packages/ai/harness/collector.test.ts
index 17f3855cd7..c6e947845a 100644
--- a/packages/ai/harness/collector.test.ts
+++ b/packages/ai/harness/collector.test.ts
@@ -25,34 +25,27 @@ function v1Event(event: string, options: Record<string, unknown> = {}) {
 }
 
 it.each([
-  ['$ai_generation', '/batch/'],
-  ['$ai_embedding', '/batch/'],
   ['$ai_generation', '/i/v1/ai/events'],
   ['$ai_embedding', '/i/v1/ai/events/'],
   ['$ai_generation', '/i/v1/analytics/events'],
 ])('accepts compressed %s analytics on %s and retains decode failures', async (eventName, path) => {
   const collector = await startCollector()
   try {
-    const legacy = path === '/batch/'
-    const body = legacy
-      ? legacyBody([{ event: eventName, distinct_id: 'test', properties: {} }])
-      : v1Body([v1Event(eventName)])
     const response = await fetch(`${collector.url}${path}`, {
       method: 'POST',
       headers: { ...AUTH, 'content-encoding': 'gzip' },
-      body: gzipSync(body),
+      body: gzipSync(v1Body([v1Event(eventName)])),
     })
     expect(response.status).toBe(200)
+    expect(await response.json()).toEqual({ results: {} })
     expect(collector.events).toEqual([
-      legacy
-        ? { event: eventName, distinct_id: 'test', properties: {} }
-        : {
-            event: eventName,
-            uuid: '01890000-0000-7000-8000-000000000000',
-            distinct_id: 'test',
-            timestamp: '2026-01-01T00:00:00.000Z',
-            properties: { $session_id: 'session-1' },
-          },
+      {
+        event: eventName,
+        uuid: '01890000-0000-7000-8000-000000000000',
+        distinct_id: 'test',
+        timestamp: '2026-01-01T00:00:00.000Z',
+        properties: { $session_id: 'session-1' },
+      },
     ])
     collector.verify()
     const invalid = await fetch(`${collector.url}${path}`, {
@@ -84,12 +77,17 @@ it('reads capture v1 options as the legacy properties they replace', async () =>
 })
 
 it.each([
-  ['non-AI events', '/batch/', {}, legacyBody([{ event: '$pageview', distinct_id: 'test', properties: {} }])],
-  ['non-AI v1 events', '/i/v1/ai/events', AUTH, v1Body([v1Event('$pageview')])],
+  ['non-AI events', '/i/v1/ai/events', AUTH, v1Body([v1Event('$pageview')])],
+  [
+    'the legacy batch endpoint',
+    '/batch/',
+    AUTH,
+    legacyBody([{ event: '$ai_generation', distinct_id: 'test', properties: {} }]),
+  ],
   ['a missing bearer token', '/i/v1/ai/events', {}, v1Body([v1Event('$ai_generation')])],
   ['a legacy body on a v1 endpoint', '/i/v1/ai/events', AUTH, legacyBody([])],
   [
-    'v1 events without v1 fields',
+    'events without v1 fields',
     '/i/v1/ai/events',
     AUTH,
     v1Body([{ event: '$ai_generation', distinct_id: 'test', properties: {} }]),
diff --git a/packages/ai/harness/collector.ts b/packages/ai/harness/collector.ts
index a8e6d17bda..f3a84a3f5a 100644
--- a/packages/ai/harness/collector.ts
+++ b/packages/ai/harness/collector.ts
@@ -2,7 +2,6 @@ import { createServer, type IncomingHttpHeaders } from 'node:http'
 import { gunzipSync } from 'node:zlib'
 
 const API_KEY = 'phc_cassette_test'
-const LEGACY_CAPTURE_PATH = '/batch/'
 const V1_CAPTURE_PATHS = new Set(['/i/v1/analytics/events', '/i/v1/ai/events'])
 
 // Capture v1 per-event `options`, keyed by the legacy property each one replaces.
@@ -19,7 +18,7 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
-/** One capture v1 event in the legacy `/batch/` shape, so assertions hold for both wire formats. */
+/** One capture v1 event in the legacy `/batch/` event shape the replay assertions use. */
 function toLegacyEvent(item: unknown): unknown {
   if (
     !isObject(item) ||
@@ -38,12 +37,8 @@ function toLegacyEvent(item: unknown): unknown {
   return { ...event, properties: legacyProperties }
 }
 
-/** The events of one capture request, from either the legacy `/batch/` or the capture v1 wire format. */
-function readEvents(isLegacy: boolean, headers: IncomingHttpHeaders, payload: Record<string, unknown>): unknown[] {
-  if (isLegacy) {
-    if (payload.api_key !== API_KEY || !Array.isArray(payload.batch)) throw new Error('Invalid analytics payload')
-    return payload.batch
-  }
+/** The events of one capture v1 request. */
+function readEvents(headers: IncomingHttpHeaders, payload: Record<string, unknown>): unknown[] {
   if (headers.authorization !== `Bearer ${API_KEY}`) throw new Error('Invalid analytics credentials')
   if (typeof payload.created_at !== 'string' || !Array.isArray(payload.batch))
     throw new Error('Invalid analytics payload')
@@ -59,9 +54,8 @@ export async function startCollector() {
         response.end(JSON.stringify({ count: events.length }))
         return
       }
-      const isLegacy = request.url === LEGACY_CAPTURE_PATH
-      const isV1 = V1_CAPTURE_PATHS.has(request.url?.replace(/\/$/, '') ?? '')
-      if (request.method !== 'POST' || (!isLegacy && !isV1)) throw new Error('Unexpected collector request')
+      const path = request.url?.replace(/\/$/, '') ?? ''
+      if (request.method !== 'POST' || !V1_CAPTURE_PATHS.has(path)) throw new Error('Unexpected collector request')
       const chunks: Buffer[] = []
       let size = 0
       for await (const chunk of request) {
@@ -75,7 +69,7 @@ export async function startCollector() {
       const bytes = encoding === 'gzip' ? gunzipSync(compressed, { maxOutputLength: 1024 * 1024 }) : compressed
       const payload = JSON.parse(bytes.toString('utf8'))
       if (!isObject(payload)) throw new Error('Invalid analytics payload')
-      for (const item of readEvents(isLegacy, request.headers, payload)) {
+      for (const item of readEvents(request.headers, payload)) {
         if (
           !isObject(item) ||
           !['$ai_generation', '$ai_embedding'].includes(item.event as string) ||
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index dbe0b9d64e..371131ff1c 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -1991,6 +1991,59 @@
       "path": "src/types.ts",
       "example": "(event: EventMessage) => EventMessage | null"
     },
+    {
+      "id": "CaptureDroppedEvent",
+      "name": "CaptureDroppedEvent",
+      "properties": [
+        {
+          "type": "string",
+          "name": "details"
+        },
+        {
+          "type": "string",
+          "name": "uuid"
+        }
+      ],
+      "path": "src/capture-v1/errors.ts"
+    },
+    {
+      "id": "CaptureEndpoint",
+      "name": "CaptureEndpoint",
+      "properties": [],
+      "path": "src/capture-v1/types.ts",
+      "example": "typeof ANALYTICS_CAPTURE_ENDPOINT | typeof AI_CAPTURE_ENDPOINT"
+    },
+    {
+      "id": "CaptureErrorParams",
+      "name": "CaptureErrorParams",
+      "properties": [
+        {
+          "description": "The underlying transport/HTTP/parse failure, when the whole batch failed.",
+          "type": "unknown",
+          "name": "cause"
+        },
+        {
+          "description": "Events the server rejected outright (billing/validation).",
+          "type": "CaptureDroppedEvent[]",
+          "name": "drops"
+        },
+        {
+          "description": "The capture lane the batch was sent to.",
+          "type": "CaptureEndpoint",
+          "name": "endpoint"
+        },
+        {
+          "type": "string",
+          "name": "requestId"
+        },
+        {
+          "description": "UUIDs of events still pending `retry` after the attempt budget was exhausted, or lost to a batch-level failure.",
+          "type": "string[]",
+          "name": "retryExhausted"
+        }
+      ],
+      "path": "src/capture-v1/errors.ts"
+    },
     {
       "id": "CaptureEvent",
       "name": "CaptureEvent",
diff --git a/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap b/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap
index 95b0692d3b..ed6ed57a73 100644
--- a/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap
+++ b/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap
@@ -3,11 +3,11 @@
 exports[`server wire snapshots > snapshots a deterministic complete captureException wire event 1`] = `
 {
   "body": {
-    "api_key": "<redacted>",
     "batch": [
       {
         "distinct_id": "person-exception",
         "event": "$exception",
+        "options": {},
         "properties": {
           "$exception_level": "error",
           "$exception_list": [
@@ -47,8 +47,6 @@ exports[`server wire snapshots > snapshots a deterministic complete captureExcep
           ],
           "$geoip_disable": true,
           "$is_server": true,
-          "$lib": "posthog-node",
-          "$lib_version": "<sdk-version>",
           "endpoint": "/v1/orders",
           "request": {
             "method": "POST",
@@ -63,14 +61,19 @@ exports[`server wire snapshots > snapshots a deterministic complete captureExcep
         "uuid": "0194cc39-1f25-7000-8000-000000000001",
       },
     ],
-    "sent_at": "2025-02-03T04:05:06.789Z",
+    "created_at": "2025-02-03T04:05:06.789Z",
   },
   "headers": {
+    "Authorization": "Bearer <redacted>",
     "Content-Type": "application/json",
+    "PostHog-Attempt": "1",
+    "PostHog-Request-Id": "<generated>",
+    "PostHog-Request-Timestamp": "2025-02-03T04:05:06.789Z",
+    "PostHog-Sdk-Info": "posthog-node/<sdk-version>",
     "User-Agent": "posthog-node/<sdk-version>",
   },
   "method": "POST",
-  "url": "https://us.example.test/batch/",
+  "url": "https://us.example.test/i/v1/analytics/events",
 }
 `;
 
diff --git a/packages/node/src/__tests__/ai-capture/wiring.spec.ts b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
index 27e9c31555..355be1a6fe 100644
--- a/packages/node/src/__tests__/ai-capture/wiring.spec.ts
+++ b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
@@ -1,8 +1,9 @@
 import { PostHogPersistedProperty } from '@posthog/core'
 
-import { PostHog } from '@/entrypoints/index.node'
+import { CaptureError, PostHog } from '@/entrypoints/index.node'
 
-import { V1WiringHarness, v413Response, v0Response, waitForFlushTimer } from '../utils/v1-wiring'
+import { AI_CAPTURE_PATH, AI_CAPTURE_URL, ANALYTICS_CAPTURE_PATH, v1Response, v413Response } from '../utils'
+import { V1WiringHarness, routeByUrl } from '../utils/v1-wiring'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
 
@@ -42,46 +43,56 @@ describe('AI capture lane wiring (Node SDK)', () => {
     vi.clearAllMocks()
   })
 
-  it('captureAi posts to the AI endpoint with the V0 body shape', async () => {
+  it('captureAi posts to the AI endpoint with v1 headers and the v1 body shape', async () => {
     const posthog = harness.makeClient()
-    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt' } })
+    const uuid = posthog.captureAi({
+      distinctId: 'user-42',
+      event: '$ai_generation',
+      timestamp: new Date('2026-01-02T03:04:05.678Z'),
+      properties: { $ai_model: 'gpt-4o-mini', $ai_trace_id: 'trace-1', $session_id: 'session-1' },
+    })
     await posthog.flush()
 
-    const calls = harness.callsTo('/i/v0/ai/batch/')
+    const calls = harness.callsTo(AI_CAPTURE_PATH)
     expect(calls).toHaveLength(1)
-    const body = JSON.parse(calls[0][1].body)
-    expect(Object.keys(body).sort()).toEqual(['api_key', 'batch', 'sent_at'])
-    expect(body.batch.map((event: any) => event.event)).toEqual(['$ai_generation'])
-    expect(harness.callsTo('example.com/batch/')).toHaveLength(0)
-  })
-
-  it('capture() is never rerouted to the AI endpoint, in either capture mode', async () => {
-    for (const mode of ['v0', 'v1'] as const) {
-      const posthog = harness.makeClient({}, mode)
-      posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: {} })
-      await posthog.flush()
-    }
-    expect(harness.callsTo('/i/v0/ai/batch/')).toHaveLength(0)
-    expect(harness.eventsIn('example.com/batch/')).toEqual(['$ai_generation', '$ai_generation'])
+    const [url, options] = calls[0]
+    expect(url).toBe(AI_CAPTURE_URL)
+    expect(options.headers).toMatchObject({
+      'Content-Type': 'application/json',
+      Authorization: 'Bearer TEST_API_KEY',
+      'PostHog-Sdk-Info': 'posthog-node/1.2.3',
+      'PostHog-Attempt': '1',
+    })
+    const body = JSON.parse(options.body)
+    expect(Object.keys(body).sort()).toEqual(['batch', 'created_at'])
+    expect(body.batch).toEqual([
+      {
+        event: '$ai_generation',
+        uuid,
+        distinct_id: 'user-42',
+        timestamp: '2026-01-02T03:04:05.678Z',
+        session_id: 'session-1',
+        options: {},
+        properties: expect.objectContaining({ $ai_model: 'gpt-4o-mini', $ai_trace_id: 'trace-1' }),
+      },
+    ])
+    expect(body.batch[0].properties).not.toHaveProperty('$lib')
+    expect(harness.callsTo(ANALYTICS_CAPTURE_PATH)).toHaveLength(0)
   })
 
-  it('captureAi stays on the AI endpoint in v1 mode, isolated from both other routes', async () => {
-    const posthog = harness.makeClient({}, 'v1')
-    posthog.capture({ distinctId: 'u', event: 'custom', properties: {} })
+  it('capture() is never rerouted to the AI endpoint', async () => {
+    const posthog = harness.makeClient()
     posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: {} })
-    posthog.captureAi({ distinctId: 'u', event: '$ai_span', properties: {} })
-    await waitForFlushTimer()
     await posthog.flush()
 
-    expect(harness.eventsIn('/i/v1/analytics/events')).toEqual(['custom'])
-    expect(harness.eventsIn('example.com/batch/')).toEqual(['$ai_generation'])
-    expect(harness.eventsIn('/i/v0/ai/batch/')).toEqual(['$ai_span'])
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(0)
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['$ai_generation'])
   })
 
   it('captureAiImmediate sends a single event only to the AI endpoint', async () => {
     const posthog = harness.makeClient()
     await posthog.captureAiImmediate({ distinctId: 'u', event: '$ai_embedding', properties: {} })
-    expect(harness.eventsIn('/i/v0/ai/batch/')).toEqual(['$ai_embedding'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_embedding'])
     expect(harness.fetch).toHaveBeenCalledTimes(1)
   })
 
@@ -95,7 +106,7 @@ describe('AI capture lane wiring (Node SDK)', () => {
     posthog.captureAi({ distinctId: 'u', event: '$ai_span', properties: {} })
     await posthog.flush()
 
-    expect(harness.eventsIn('/i/v0/ai/batch/')).toEqual(['$ai_span'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_span'])
     const errorLog = (console.error as vi.Mock).mock.calls.flat().join(' ')
     expect(errorLog).toContain('$ai_generation')
     expect(errorLog).toMatch(/\d+ bytes/)
@@ -117,90 +128,50 @@ describe('AI capture lane wiring (Node SDK)', () => {
     }
     await posthog.flush()
 
-    const calls = harness.callsTo('/i/v0/ai/batch/')
+    const calls = harness.callsTo(AI_CAPTURE_PATH)
     expect(calls).toHaveLength(2)
-    expect(harness.eventsIn('/i/v0/ai/batch/')).toEqual(['$ai_a', '$ai_b', '$ai_c'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_a', '$ai_b', '$ai_c'])
   })
 
-  it('bisects a sub-batch in-lane on 413 without tripping the shared batch-size halving', async () => {
-    const posthog = harness.makeClient()
-    harness.fetch.mockImplementationOnce(() => Promise.resolve(v413Response()))
-    harness.fetch.mockImplementation(() => Promise.resolve(v0Response()))
-
-    const envelopes = ['$ai_a', '$ai_b', '$ai_c'].map((event, index) => ({
-      event,
-      distinct_id: `user-${index}`,
-      timestamp: `2024-01-0${index + 1}T00:00:00.000Z`,
-      uuid: `0198c0de-0000-7000-8000-00000000000${index}`,
-    }))
-    for (const { event, distinct_id, timestamp, uuid } of envelopes) {
-      posthog.captureAi({ distinctId: distinct_id, event, timestamp: new Date(timestamp), uuid, properties: {} })
-    }
-    await expect(posthog.flush()).resolves.not.toThrow()
-
-    const batches = harness.callsTo('/i/v0/ai/batch/').map(([, options]) => JSON.parse(options.body).batch)
-    expect(batches.map((batch) => batch.map((event: any) => event.event))).toEqual([
-      ['$ai_a', '$ai_b', '$ai_c'],
-      ['$ai_a', '$ai_b'],
-      ['$ai_c'],
-    ])
-    expect(batches[0]).toMatchObject(envelopes)
-    expect(batches.slice(1).flat()).toEqual(batches[0])
-    expect(await deliveredEventsIn('/i/v0/ai/batch/')).toEqual(['$ai_a', '$ai_b', '$ai_c'])
-
-    harness.useDefaultRouting()
-    for (const event of ['custom_1', 'custom_2', 'custom_3'] as const) {
-      posthog.capture({ distinctId: 'u', event, properties: {} })
-    }
-    await posthog.flush()
-
-    const analyticsCalls = harness.callsTo('example.com/batch/')
-    expect(analyticsCalls).toHaveLength(1)
-    expect(JSON.parse(analyticsCalls[0][1].body).batch.map((e: any) => e.event)).toEqual([
-      'custom_1',
-      'custom_2',
-      'custom_3',
-    ])
-  })
-
-  it('drops a single event that still 413s alone, without throwing, and keeps the lane usable', async () => {
-    const posthog = harness.makeClient()
-    posthog.debug(true)
+  it('treats a 413 as terminal: one request, a CaptureError naming the AI lane, no bisection', async () => {
+    const posthog = harness.makeClient({ fetchRetryCount: 3, fetchRetryDelay: 1 })
     const onError = vi.fn()
     posthog.on('error', onError)
     harness.fetch.mockImplementation((url: any) =>
-      Promise.resolve(url.includes('/i/v0/ai/batch/') ? v413Response() : v0Response())
+      Promise.resolve(url.includes(AI_CAPTURE_PATH) ? v413Response() : routeByUrl(url))
     )
 
-    posthog.captureAi({ distinctId: 'u', event: '$ai_undeliverable', properties: {} })
+    const uuids = ['$ai_a', '$ai_b', '$ai_c'].map((event) =>
+      posthog.captureAi({ distinctId: 'u', event, properties: { $ai_model: 'gpt-4o-mini' } })
+    )
     await expect(posthog.flush()).resolves.not.toThrow()
 
-    expect(await deliveredEventsIn('/i/v0/ai/batch/')).toEqual([])
-    const errorLog = (console.error as vi.Mock).mock.calls.flat().join(' ')
-    expect(errorLog).toContain('$ai_undeliverable')
-    expect(errorLog).toMatch(/\d+ bytes/)
-
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_a', '$ai_b', '$ai_c'])
     expect(onError).toHaveBeenCalledTimes(1)
-    const emittedError = onError.mock.calls[0][0]
-    expect(emittedError).toBeInstanceOf(Error)
-    expect(emittedError.message).toContain('$ai_undeliverable')
-    expect(emittedError.message).toMatch(/\d+ bytes/)
+    const error = onError.mock.calls[0][0] as CaptureError
+    expect(error).toBeInstanceOf(CaptureError)
+    expect(error.endpoint).toBe(AI_CAPTURE_PATH)
+    expect(error.retryExhausted).toEqual(uuids)
+    expect((error.cause as Error).message).toContain('HTTP 413')
 
     harness.useDefaultRouting()
     posthog.captureAi({ distinctId: 'u', event: '$ai_next', properties: {} })
+    posthog.capture({ distinctId: 'u', event: 'custom', properties: {} })
     await posthog.flush()
-    expect(await deliveredEventsIn('/i/v0/ai/batch/')).toEqual(['$ai_next'])
+    expect(await deliveredEventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_next'])
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
   })
 
   it('keeps the AI route inactive (and flush silent) until first use', async () => {
     const posthog = harness.makeClient()
     posthog.capture({ distinctId: 'u', event: 'custom', properties: {} })
     await posthog.flush()
-    expect(harness.callsTo('/i/v0/ai/batch/')).toHaveLength(0)
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(0)
 
     posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
     await posthog.shutdown()
-    expect(harness.eventsIn('/i/v0/ai/batch/')).toEqual(['$ai_generation'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_generation'])
     expect(aiCaptureQueueEvents(posthog)).toEqual([])
   })
 
@@ -209,7 +180,7 @@ describe('AI capture lane wiring (Node SDK)', () => {
     posthog.debug(true)
     posthog.captureAi({ distinctId: 'u', event: 'custom_event', properties: {} })
     await posthog.flush()
-    expect(harness.eventsIn('/i/v0/ai/batch/')).toEqual(['custom_event'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['custom_event'])
     const debugLog = (console.debug as vi.Mock).mock.calls.flat().join(' ')
     expect(debugLog).toContain('custom_event')
   })
@@ -226,7 +197,7 @@ describe('AI capture lane wiring (Node SDK)', () => {
     const posthog = harness.makeClient()
     const uuid = posthog.captureAi({ distinctId: 'u', event: '$ai_generation' })
     await posthog.flush()
-    const body = JSON.parse(harness.callsTo('/i/v0/ai/batch/')[0][1].body)
+    const body = JSON.parse(harness.callsTo(AI_CAPTURE_PATH)[0][1].body)
     expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/)
     expect(body.batch[0].uuid).toBe(uuid)
   })
@@ -236,7 +207,7 @@ describe('AI capture lane wiring (Node SDK)', () => {
     const supplied = '0198c0de-0000-7000-8000-000000000abc'
     expect(posthog.captureAi({ distinctId: 'u', event: '$ai_generation', uuid: supplied })).toBe(supplied)
     await posthog.flush()
-    const calls = harness.callsTo('/i/v0/ai/batch/')
+    const calls = harness.callsTo(AI_CAPTURE_PATH)
     expect(calls).toHaveLength(1)
     expect(JSON.parse(calls[0][1].body).batch[0].uuid).toBe(supplied)
   })
@@ -252,8 +223,8 @@ describe('AI capture lane wiring (Node SDK)', () => {
     const started = new Promise<void>((resolve) => {
       startFetch = resolve
     })
-    let completeFetch!: (response: ReturnType<typeof v0Response>) => void
-    const response = new Promise<ReturnType<typeof v0Response>>((resolve) => {
+    let completeFetch!: (response: ReturnType<typeof v1Response>) => void
+    const response = new Promise<ReturnType<typeof v1Response>>((resolve) => {
       completeFetch = resolve
     })
     harness.fetch.mockImplementation(() => {
@@ -268,12 +239,12 @@ describe('AI capture lane wiring (Node SDK)', () => {
       await vi.advanceTimersByTimeAsync(0)
       expect(settled).not.toHaveBeenCalled()
     } finally {
-      completeFetch(v0Response())
+      completeFetch(v1Response())
       await capture
     }
     const uuid = await capture
     expect(settled).toHaveBeenCalledWith(uuid)
-    const calls = harness.callsTo('/i/v0/ai/batch/')
+    const calls = harness.callsTo(AI_CAPTURE_PATH)
     expect(calls).toHaveLength(1)
     expect(JSON.parse(calls[0][1].body).batch[0].uuid).toBe(uuid)
   })
diff --git a/packages/node/src/__tests__/capture-v1/config.spec.ts b/packages/node/src/__tests__/capture-v1/config.spec.ts
deleted file mode 100644
index 3da398899a..0000000000
--- a/packages/node/src/__tests__/capture-v1/config.spec.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-import { resolveCaptureMode } from '@/capture-v1/config'
-
-describe('resolveCaptureMode', () => {
-  const original = process.env.POSTHOG_CAPTURE_MODE
-
-  afterEach(() => {
-    if (original === undefined) {
-      delete process.env.POSTHOG_CAPTURE_MODE
-    } else {
-      process.env.POSTHOG_CAPTURE_MODE = original
-    }
-  })
-
-  it('defaults to v0 when the environment variable is unset', () => {
-    delete process.env.POSTHOG_CAPTURE_MODE
-    expect(resolveCaptureMode()).toBe('v0')
-  })
-
-  it('resolves v1 from the environment variable', () => {
-    process.env.POSTHOG_CAPTURE_MODE = 'v1'
-    expect(resolveCaptureMode()).toBe('v1')
-  })
-
-  it('resolves v0 from the environment variable', () => {
-    process.env.POSTHOG_CAPTURE_MODE = 'v0'
-    expect(resolveCaptureMode()).toBe('v0')
-  })
-
-  it('ignores an invalid environment value and defaults to v0', () => {
-    process.env.POSTHOG_CAPTURE_MODE = 'v2'
-    expect(resolveCaptureMode()).toBe('v0')
-  })
-})
diff --git a/packages/node/src/__tests__/capture-v1/process-exit.spec.ts b/packages/node/src/__tests__/capture-v1/process-exit.spec.ts
new file mode 100644
index 0000000000..794faeece8
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/process-exit.spec.ts
@@ -0,0 +1,81 @@
+/** @vitest-environment node */
+
+import { spawn } from 'node:child_process'
+import { type IncomingMessage, type Server, createServer } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { fileURLToPath } from 'node:url'
+
+const packageRoot = fileURLToPath(new URL('../../../', import.meta.url))
+
+interface ChildResult {
+  code: number | null
+  stderr: string
+}
+
+async function readBody(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = []
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+function runChild(host: string): Promise<ChildResult> {
+  // Uses the built package, like a real script would. Nothing but the SDK's own timers can keep this process alive.
+  const script = `
+    import { PostHog } from 'posthog-node'
+    const posthog = new PostHog('phc_process_exit_test', {
+      host: '${host}',
+      disableCompression: true,
+      fetchRetryCount: 3,
+      fetchRetryDelay: 50,
+    })
+    posthog.capture({ distinctId: 'exit-user', event: 'exit-event' })
+    await posthog.shutdown()
+  `
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, ['--input-type=module', '-e', script], { cwd: packageRoot })
+    let stderr = ''
+    child.stderr.on('data', (chunk) => (stderr += chunk.toString()))
+    child.on('error', reject)
+    child.on('close', (code) => resolve({ code, stderr }))
+  })
+}
+
+describe('capture v1 in a short-lived process', () => {
+  let server: Server
+  let host: string
+  let attempts: number
+  const delivered: unknown[] = []
+
+  beforeEach(async () => {
+    vi.useRealTimers()
+    attempts = 0
+    delivered.length = 0
+    server = createServer(async (req, res) => {
+      const body = await readBody(req)
+      attempts++
+      if (attempts === 1) {
+        res.writeHead(500).end()
+        return
+      }
+      delivered.push(...JSON.parse(body).batch)
+      res.writeHead(200, { 'Content-Type': 'application/json' }).end('{"results":{}}')
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    host = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+  })
+
+  afterEach(async () => {
+    await new Promise((resolve) => server.close(resolve))
+  })
+
+  it('keeps the process alive through a retry wait until an awaited shutdown delivers the event', async () => {
+    const result = await runChild(host)
+
+    expect(result.stderr).not.toContain('unsettled top-level await')
+    expect(result.code).toBe(0)
+    expect(attempts).toBe(2)
+    expect(delivered).toEqual([expect.objectContaining({ event: 'exit-event', distinct_id: 'exit-user' })])
+  }, 15_000)
+})
diff --git a/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts b/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
index fbeed6e55c..000d34c236 100644
--- a/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
@@ -1,25 +1,21 @@
 import { PostHogPersistedProperty } from '@posthog/core'
 
-import { PostHog } from '@/entrypoints/index.node'
+import { CaptureError, PostHog } from '@/entrypoints/index.node'
 
-import { v1Response } from '../utils'
+import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, v1Response } from '../utils'
 import { V1WiringHarness, waitForFlushTimer } from '../utils/v1-wiring'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
 
-// Regression coverage for the mixed-batch double-delivery risk (H1): with v1 and legacy $ai_*
-// events sharing a flush cycle, a failure on the legacy leg must not roll back or re-send the
-// events already accepted on the V1 leg. Route partitioning gives each transport its own queue.
-describe('capture v1 route isolation (Node SDK)', () => {
+// With analytics and captureAi events sharing a flush cycle, a failure on one lane must not roll
+// back or re-send the events already accepted on the other. Each lane has its own queue.
+describe('capture lane isolation (Node SDK)', () => {
   vi.useFakeTimers()
 
   const harness = new V1WiringHarness()
 
-  const aiQueueEvents = (posthog: PostHog): string[] =>
-    (posthog.getPersistedProperty(PostHogPersistedProperty.AiQueue) || []).map((item: any) => item.message.event)
-
-  const analyticsQueueEvents = (posthog: PostHog): string[] =>
-    (posthog.getPersistedProperty(PostHogPersistedProperty.Queue) || []).map((item: any) => item.message.event)
+  const queuedEvents = (posthog: PostHog, key: PostHogPersistedProperty): string[] =>
+    (posthog.getPersistedProperty(key) || []).map((item: any) => item.message.event)
 
   beforeEach(() => {
     vi.spyOn(console, 'warn').mockImplementation(() => {})
@@ -33,60 +29,48 @@ describe('capture v1 route isolation (Node SDK)', () => {
     vi.clearAllMocks()
   })
 
-  it('keeps V1-accepted events from being re-sent when the legacy AI leg fails', async () => {
-    // v1 endpoint accepts everything; the legacy /batch/ leg (AI route) fails with a network error.
+  it('keeps analytics events from being re-sent when the AI lane fails', async () => {
     harness.fetch.mockImplementation((url: any) =>
-      (url as string).includes('/i/v1/analytics/events')
+      (url as string).includes(ANALYTICS_CAPTURE_PATH)
         ? Promise.resolve(v1Response())
         : Promise.reject(new Error('network down'))
     )
 
-    const posthog = harness.makeClient({}, 'v1')
+    const posthog = harness.makeClient()
+    const errors: Error[] = []
+    posthog.on('error', (error) => errors.push(error))
     posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
-    posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt' } })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt-4o-mini' } })
     await waitForFlushTimer()
+    await posthog.flush()
 
-    // Analytics route delivered its batch to V1 exactly once; the AI route attempted /batch/ and failed.
-    expect(harness.eventsIn('/i/v1/analytics/events')).toEqual(['custom'])
-    expect(harness.callsTo('/batch/').length).toBeGreaterThanOrEqual(1)
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toBeInstanceOf(CaptureError)
+    expect((errors[0] as CaptureError).endpoint).toBe(AI_CAPTURE_PATH)
 
-    // The failed AI event is retained on its isolated queue; the accepted V1 event is gone.
-    expect(aiQueueEvents(posthog)).toEqual(['$ai_generation'])
-    expect(analyticsQueueEvents(posthog)).toEqual([])
+    // The sender owns retries, so the failed AI batch is reported and consumed rather than requeued.
+    expect(queuedEvents(posthog, PostHogPersistedProperty.AiCaptureQueue)).toEqual([])
+    expect(queuedEvents(posthog, PostHogPersistedProperty.Queue)).toEqual([])
 
-    // Recover the legacy leg and flush again.
-    const callsBeforeRecovery = harness.fetch.mock.calls.length
     harness.useDefaultRouting()
+    const callsBeforeRecovery = harness.fetch.mock.calls.length
     await posthog.flush()
-
-    const recoveryCalls = harness.fetch.mock.calls.slice(callsBeforeRecovery)
-    expect(recoveryCalls).toHaveLength(1)
-    expect(recoveryCalls[0][0]).toBe('http://example.com/batch/')
-    expect(JSON.parse(recoveryCalls[0][1].body).batch.map((event: any) => event.event)).toEqual(['$ai_generation'])
-    expect((await harness.fetch.mock.results[callsBeforeRecovery].value).status).toBe(200)
-
-    // The V1 event was never re-sent (still a single delivery); the AI event now reaches /batch/.
-    expect(harness.eventsIn('/i/v1/analytics/events')).toEqual(['custom'])
-    expect(aiQueueEvents(posthog)).toEqual([])
+    expect(harness.fetch.mock.calls.length).toBe(callsBeforeRecovery)
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
   })
 
-  it('flushes each route as its own homogeneous request (no mixed batch)', async () => {
-    const posthog = harness.makeClient({}, 'v1')
+  it('flushes each lane as its own homogeneous request (no mixed batch)', async () => {
+    const posthog = harness.makeClient()
     posthog.capture({ distinctId: 'u', event: 'a', properties: {} })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_span', properties: {} })
     posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: {} })
-    posthog.capture({ distinctId: 'u', event: 'b', properties: {} })
     await waitForFlushTimer()
+    await posthog.flush()
 
-    // Every /batch/ request holds only AI events; every v1 request holds only non-AI events.
-    for (const [, options] of harness.callsTo('/batch/')) {
-      const events = JSON.parse(options.body).batch.map((e: any) => e.event)
-      expect(events.every((name: string) => name.startsWith('$ai_'))).toBe(true)
-    }
-    for (const [, options] of harness.callsTo('/i/v1/analytics/events')) {
-      const events = JSON.parse(options.body).batch.map((e: any) => e.event)
-      expect(events.some((name: string) => name.startsWith('$ai_'))).toBe(false)
-    }
-    expect(harness.eventsIn('/i/v1/analytics/events')).toEqual(['a', 'b'])
-    expect(harness.eventsIn('/batch/')).toEqual(['$ai_generation'])
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['a', '$ai_generation'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_span'])
+    expect(harness.callsTo('/batch/')).toHaveLength(0)
   })
 })
diff --git a/packages/node/src/__tests__/capture-v1/routing.spec.ts b/packages/node/src/__tests__/capture-v1/routing.spec.ts
deleted file mode 100644
index d9b9dbb370..0000000000
--- a/packages/node/src/__tests__/capture-v1/routing.spec.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import type { PostHogEventProperties } from '@posthog/core'
-
-import { isLegacyOnlyEvent } from '@/capture-v1/routing'
-
-describe('isLegacyOnlyEvent', () => {
-  it.each(['$ai_generation', '$ai_span', '$ai_trace', '$ai_embedding', '$ai_metric', '$ai_feedback', '$ai_'])(
-    'routes AI event %s to the legacy submitter',
-    (event) => {
-      expect(isLegacyOnlyEvent({ event })).toBe(true)
-    }
-  )
-
-  it.each([
-    '$pageview',
-    '$identify',
-    '$create_alias',
-    '$groupidentify',
-    '$exception',
-    'custom_event',
-    'my$ai_event',
-    'prefixed_$ai_generation',
-    'ai_generation',
-    '$AI_generation',
-  ])('keeps non-AI event %s eligible for v1', (event) => {
-    expect(isLegacyOnlyEvent({ event })).toBe(false)
-  })
-
-  it.each([
-    ['missing event', {}],
-    ['empty event', { event: '' }],
-    ['non-string event', { event: 123 }],
-  ])('treats %s as not legacy-only', (_label, message) => {
-    expect(isLegacyOnlyEvent(message as PostHogEventProperties)).toBe(false)
-  })
-})
diff --git a/packages/node/src/__tests__/capture-v1/sender.spec.ts b/packages/node/src/__tests__/capture-v1/sender.spec.ts
index b4ec655789..4fc46caba4 100644
--- a/packages/node/src/__tests__/capture-v1/sender.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/sender.spec.ts
@@ -1,6 +1,6 @@
 import { type PostHogEventProperties, type PostHogFetchResponse, isGzipSupported } from '@posthog/core'
 
-import { CaptureV1Error } from '@/capture-v1/errors'
+import { CaptureError } from '@/capture-v1/errors'
 import { V1CaptureSender, type V1CaptureSenderConfig, type V1CaptureSenderHooks } from '@/capture-v1/sender'
 
 const CLOCK_START = Date.parse('2024-01-01T00:00:00.000Z')
@@ -52,6 +52,7 @@ function makeSender(
   const sender = new V1CaptureSender(
     {
       host: 'https://t.posthog.com',
+      path: '/i/v1/analytics/events',
       apiKey: 'phc_test',
       libraryId: 'posthog-node',
       libraryVersion: '1.2.3',
@@ -92,26 +93,29 @@ function headersOf(fetch: Harness['fetch'], call: number): Record<string, string
 
 describe('V1CaptureSender', () => {
   describe('request contract', () => {
-    it('POSTs to the v1 analytics endpoint with the batch envelope and no v0 fields', async () => {
-      const { sender, fetch, errors } = makeSender()
-      fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
-
-      await sender.sendV1Batch([msg('u1')])
-
-      expect(fetch).toHaveBeenCalledTimes(1)
-      const [url, options] = fetch.mock.calls[0]
-      expect(url).toBe('https://t.posthog.com/i/v1/analytics/events')
-      expect(options.method).toBe('POST')
-
-      const body = bodyOf(fetch, 0)
-      expect(body.created_at).toBe('2024-01-01T00:00:00.000Z')
-      expect(body.batch).toHaveLength(1)
-      expect(body.batch[0].uuid).toBe('u1')
-      expect(body).not.toHaveProperty('api_key')
-      expect(body).not.toHaveProperty('sent_at')
-      expect(body).not.toHaveProperty('historical_migration')
-      expect(errors).toEqual([])
-    })
+    it.each(['/i/v1/analytics/events', '/i/v1/ai/events'] as const)(
+      'POSTs to its %s lane with the batch envelope and no v0 fields',
+      async (path) => {
+        const { sender, fetch, errors } = makeSender({ path })
+        fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+        await sender.sendV1Batch([msg('u1')])
+
+        expect(fetch).toHaveBeenCalledTimes(1)
+        const [url, options] = fetch.mock.calls[0]
+        expect(url).toBe(`https://t.posthog.com${path}`)
+        expect(options.method).toBe('POST')
+
+        const body = bodyOf(fetch, 0)
+        expect(body.created_at).toBe('2024-01-01T00:00:00.000Z')
+        expect(body.batch).toHaveLength(1)
+        expect(body.batch[0].uuid).toBe('u1')
+        expect(body).not.toHaveProperty('api_key')
+        expect(body).not.toHaveProperty('sent_at')
+        expect(body).not.toHaveProperty('historical_migration')
+        expect(errors).toEqual([])
+      }
+    )
 
     it('sets all required v1 headers with Bearer auth and no api_key in the body', async () => {
       const { sender, fetch } = makeSender()
@@ -194,8 +198,8 @@ describe('V1CaptureSender', () => {
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
-      expect(errors[0]).toBeInstanceOf(CaptureV1Error)
-      expect((errors[0] as CaptureV1Error).retryExhausted).toEqual(['u1'])
+      expect(errors[0]).toBeInstanceOf(CaptureError)
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
     })
   })
 
@@ -270,19 +274,25 @@ describe('V1CaptureSender', () => {
       expect(errors).toEqual([])
     })
 
-    it('surfaces a drop as a terminal failure without retrying', async () => {
-      const { sender, fetch, errors } = makeSender()
-      fetch.mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'drop', details: 'billing' } } }))
+    it.each(['/i/v1/analytics/events', '/i/v1/ai/events'] as const)(
+      'surfaces a drop on the %s lane as a terminal CaptureError naming that lane',
+      async (path) => {
+        const { sender, fetch, errors } = makeSender({ path })
+        fetch.mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'drop', details: 'billing' } } }))
 
-      await sender.sendV1Batch([msg('u1')])
+        await sender.sendV1Batch([msg('u1', { properties: { $ai_input: 'private prompt text' } })])
 
-      expect(fetch).toHaveBeenCalledTimes(1)
-      expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
-      expect(error).toBeInstanceOf(CaptureV1Error)
-      expect(error.drops).toEqual([{ uuid: 'u1', details: 'billing' }])
-      expect(error.retryExhausted).toEqual([])
-    })
+        expect(fetch).toHaveBeenCalledTimes(1)
+        expect(errors).toHaveLength(1)
+        const error = errors[0] as CaptureError
+        expect(error).toBeInstanceOf(CaptureError)
+        expect(error.name).toBe('CaptureError')
+        expect(error.endpoint).toBe(path)
+        expect(error.drops).toEqual([{ uuid: 'u1', details: 'billing' }])
+        expect(error.retryExhausted).toEqual([])
+        expect(error.message).toBe(`Capture batch req-fixed to ${path} did not fully deliver: 1 dropped, 0 undelivered`)
+      }
+    )
 
     it('surfaces a drop with no details', async () => {
       const { sender, fetch, errors } = makeSender()
@@ -290,7 +300,7 @@ describe('V1CaptureSender', () => {
 
       await sender.sendV1Batch([msg('u1')])
 
-      expect((errors[0] as CaptureV1Error).drops).toEqual([{ uuid: 'u1', details: undefined }])
+      expect((errors[0] as CaptureError).drops).toEqual([{ uuid: 'u1', details: undefined }])
     })
 
     it('resends only the retry-tagged events on the next attempt', async () => {
@@ -318,7 +328,7 @@ describe('V1CaptureSender', () => {
       await sender.sendV1Batch([msg('u1'), msg('u2')])
 
       expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect(error.drops).toEqual([{ uuid: 'u1', details: 'bad' }])
       expect(error.retryExhausted).toEqual([])
     })
@@ -330,7 +340,7 @@ describe('V1CaptureSender', () => {
       await sender.sendV1Batch([msg('u1')])
 
       expect(fetch).toHaveBeenCalledTimes(3)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect(error.retryExhausted).toEqual(['u1'])
       expect(error.drops).toEqual([])
     })
@@ -345,7 +355,7 @@ describe('V1CaptureSender', () => {
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect(error.retryExhausted).toEqual(['u1'])
       expect((error.cause as Error).message).toContain('unparseable')
     })
@@ -360,7 +370,7 @@ describe('V1CaptureSender', () => {
       await sender.sendV1Batch([msg('u1')])
 
       expect(fetch).toHaveBeenCalledTimes(1)
-      expect((errors[0] as CaptureV1Error).retryExhausted).toEqual(['u1'])
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
     })
   })
 
@@ -382,7 +392,7 @@ describe('V1CaptureSender', () => {
       await sender.sendV1Batch([msg('u1')])
 
       expect(fetch).toHaveBeenCalledTimes(1)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect(error.retryExhausted).toEqual(['u1'])
       expect((error.cause as Error).message).toContain('429')
     })
@@ -395,7 +405,7 @@ describe('V1CaptureSender', () => {
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
-      expect((errors[0] as CaptureV1Error).retryExhausted).toEqual(['u1'])
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
     })
 
     it('exhausts the budget on a persistently retryable status', async () => {
@@ -405,7 +415,7 @@ describe('V1CaptureSender', () => {
       await sender.sendV1Batch([msg('u1')])
 
       expect(fetch).toHaveBeenCalledTimes(4)
-      expect((errors[0] as CaptureV1Error).retryExhausted).toEqual(['u1'])
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
     })
 
     it('bounds response body cancellation by the request deadline before retrying a 5xx', async () => {
@@ -427,9 +437,9 @@ describe('V1CaptureSender', () => {
       expect(fetch).toHaveBeenCalledTimes(2)
       expect(sleeps).toEqual([100])
       expect(errors).toHaveLength(1)
-      expect(errors[0]).toBeInstanceOf(CaptureV1Error)
-      expect((errors[0] as CaptureV1Error).retryExhausted).toEqual(['u1'])
-      expect(((errors[0] as CaptureV1Error).cause as Error).message).toContain('HTTP 503: still unavailable')
+      expect(errors[0]).toBeInstanceOf(CaptureError)
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
+      expect(((errors[0] as CaptureError).cause as Error).message).toContain('HTTP 503: still unavailable')
       expect(vi.getTimerCount()).toBe(0)
     })
   })
@@ -452,7 +462,7 @@ describe('V1CaptureSender', () => {
       await sender.sendV1Batch([msg('u1'), msg('u2')])
 
       expect(fetch).toHaveBeenCalledTimes(3)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect(error.retryExhausted).toEqual(['u1', 'u2'])
       expect((error.cause as Error).message).toBe('timeout')
     })
@@ -471,7 +481,7 @@ describe('V1CaptureSender', () => {
       await sendPromise
 
       expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect((error.cause as Error).name).toBe('AbortError')
       expect((error.cause as Error).message).toBe(
         'Capture V1 request timed out waiting for response headers after 1000ms'
@@ -537,7 +547,7 @@ describe('V1CaptureSender', () => {
       await sendPromise
 
       expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
+      const error = errors[0] as CaptureError
       expect((error.cause as Error).name).toBe('AbortError')
       expect((error.cause as Error).message).toBe(
         'Capture V1 request timed out while reading the response body after 1000ms'
@@ -546,7 +556,7 @@ describe('V1CaptureSender', () => {
       expect(vi.getTimerCount()).toBe(0)
     })
 
-    it('surfaces CaptureV1Error after stalled success bodies exhaust the timeout retry budget', async () => {
+    it('surfaces CaptureError after stalled success bodies exhaust the timeout retry budget', async () => {
       const { sender, fetch, errors } = makeSender({ maxAttempts: 2, requestTimeoutMs: 1000 })
       const cancels: vi.Mock<Promise<void>, []>[] = []
       fetch.mockImplementation(() => {
@@ -564,8 +574,8 @@ describe('V1CaptureSender', () => {
       expect(cancels).toHaveLength(2)
       expect(cancels.every((cancel) => cancel.mock.calls.length === 1)).toBe(true)
       expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
-      expect(error).toBeInstanceOf(CaptureV1Error)
+      const error = errors[0] as CaptureError
+      expect(error).toBeInstanceOf(CaptureError)
       expect(error.retryExhausted).toEqual(['u1'])
       expect((error.cause as Error).name).toBe('AbortError')
       expect((error.cause as Error).message).toBe(
@@ -586,9 +596,9 @@ describe('V1CaptureSender', () => {
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(cancel).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
-      expect(errors[0]).toBeInstanceOf(CaptureV1Error)
-      expect((errors[0] as CaptureV1Error).retryExhausted).toEqual(['u1'])
-      expect(((errors[0] as CaptureV1Error).cause as Error).message).toContain('HTTP 400')
+      expect(errors[0]).toBeInstanceOf(CaptureError)
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
+      expect(((errors[0] as CaptureError).cause as Error).message).toContain('HTTP 400')
       expect(vi.getTimerCount()).toBe(0)
     })
   })
@@ -709,6 +719,7 @@ describe('V1CaptureSender', () => {
   describe('default hooks (no injection)', () => {
     const baseConfig: V1CaptureSenderConfig = {
       host: 'https://t.posthog.com',
+      path: '/i/v1/analytics/events',
       apiKey: 'phc_test',
       libraryId: 'posthog-node',
       libraryVersion: '1.2.3',
diff --git a/packages/node/src/__tests__/capture-v1/wiring.spec.ts b/packages/node/src/__tests__/capture-v1/wiring.spec.ts
index ad2f35cac4..c63ce14969 100644
--- a/packages/node/src/__tests__/capture-v1/wiring.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/wiring.spec.ts
@@ -1,9 +1,8 @@
 import { gunzipSync } from 'node:zlib'
 
-import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
-import { CaptureV1Error } from '@/capture-v1/errors'
-import { v1Response } from '../utils'
-import { V1_URL, V1WiringHarness, v0Response, waitForFlushTimer } from '../utils/v1-wiring'
+import { CaptureError, PostHog, PostHogOptions } from '@/entrypoints/index.node'
+import { ANALYTICS_CAPTURE_URL, AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, v1Response } from '../utils'
+import { V1WiringHarness, okResponse, waitForFlushTimer } from '../utils/v1-wiring'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
 
@@ -13,7 +12,6 @@ describe('capture v1 wiring (Node SDK)', () => {
   const harness = new V1WiringHarness()
   const mockedFetch = harness.fetch
   const makeClient = (options?: PostHogOptions): PostHog => harness.makeClient(options)
-  const makeV1Client = (options?: PostHogOptions): PostHog => harness.makeClient(options, 'v1')
   const callsTo = (fragment: string): [string, any][] => harness.callsTo(fragment)
   const eventsIn = (fragment: string): string[] => harness.eventsIn(fragment)
 
@@ -29,17 +27,37 @@ describe('capture v1 wiring (Node SDK)', () => {
     vi.clearAllMocks()
   })
 
-  describe('v0 mode (default)', () => {
-    it('sends every event to /batch/ and never touches the v1 endpoint', async () => {
+  describe('POSTHOG_CAPTURE_MODE', () => {
+    const original = process.env.POSTHOG_CAPTURE_MODE
+
+    afterEach(() => {
+      if (original === undefined) {
+        delete process.env.POSTHOG_CAPTURE_MODE
+      } else {
+        process.env.POSTHOG_CAPTURE_MODE = original
+      }
+    })
+
+    it('warns once per client that the variable is ignored, and still sends to capture v1', async () => {
+      process.env.POSTHOG_CAPTURE_MODE = 'v0'
       const posthog = makeClient()
-      posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
-      posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt' } })
-      await waitForFlushTimer()
+      posthog.capture({ distinctId: 'u', event: 'first', properties: {} })
+      posthog.capture({ distinctId: 'u', event: 'second', properties: {} })
+      await posthog.flush()
 
-      expect(callsTo('/i/v1/analytics/events')).toHaveLength(0)
-      const events = eventsIn('/batch/')
-      expect(events).toContain('custom')
-      expect(events).toContain('$ai_generation')
+      const warnings = (console.warn as vi.Mock).mock.calls.filter((call) =>
+        String(call[0]).includes('POSTHOG_CAPTURE_MODE')
+      )
+      expect(warnings).toEqual([['[PostHog] POSTHOG_CAPTURE_MODE is no longer read. Capture always uses capture v1.']])
+      expect(callsTo('/batch/')).toHaveLength(0)
+      expect(eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['first', 'second'])
+    })
+
+    it('does not warn when the variable is unset', () => {
+      delete process.env.POSTHOG_CAPTURE_MODE
+      makeClient()
+
+      expect(console.warn).not.toHaveBeenCalledWith(expect.stringContaining('POSTHOG_CAPTURE_MODE'))
     })
   })
 
@@ -72,27 +90,23 @@ describe('capture v1 wiring (Node SDK)', () => {
       }
     })
 
-    it('uses Node gzip for the legacy batch endpoint', async () => {
+    it.each([
+      ['capture()', ANALYTICS_CAPTURE_PATH],
+      ['captureAi()', AI_CAPTURE_PATH],
+    ] as const)('uses Node gzip for %s on %s', async (method, path) => {
       const posthog = makeClient({ disableCompression: false })
-      posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
-      await posthog.flush()
-
-      const [, options] = callsTo('/batch/')[0]
-      expect(options.headers['Content-Encoding']).toBe('gzip')
-      expect(options.body).toBeInstanceOf(Uint8Array)
-      expect((await readCompressedBody(options.body)).batch[0].event).toBe('custom')
-      expect(compressionStreamSpy).not.toHaveBeenCalled()
-    })
-
-    it('uses Node gzip for the Capture V1 endpoint', async () => {
-      const posthog = makeV1Client({ disableCompression: false })
-      posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
+      const event = { distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt-4o-mini' } }
+      if (method === 'capture()') {
+        posthog.capture(event)
+      } else {
+        posthog.captureAi(event)
+      }
       await posthog.flush()
 
-      const [, options] = callsTo('/i/v1/analytics/events')[0]
+      const [, options] = callsTo(path)[0]
       expect(options.headers['Content-Encoding']).toBe('gzip')
       expect(options.body).toBeInstanceOf(Uint8Array)
-      expect((await readCompressedBody(options.body)).batch[0].event).toBe('custom')
+      expect((await readCompressedBody(options.body)).batch[0].event).toBe('$ai_generation')
       expect(compressionStreamSpy).not.toHaveBeenCalled()
     })
 
@@ -115,17 +129,17 @@ describe('capture v1 wiring (Node SDK)', () => {
     })
   })
 
-  describe('v1 mode - batched path', () => {
+  describe('batched path', () => {
     it('sends a normal event to the v1 endpoint with Bearer auth and the v1 envelope', async () => {
-      const posthog = makeV1Client()
+      const posthog = makeClient()
       posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
       await waitForFlushTimer()
 
       expect(callsTo('/batch/')).toHaveLength(0)
-      const calls = callsTo('/i/v1/analytics/events')
+      const calls = callsTo(ANALYTICS_CAPTURE_PATH)
       expect(calls).toHaveLength(1)
       const [url, options] = calls[0]
-      expect(url).toBe(V1_URL)
+      expect(url).toBe(ANALYTICS_CAPTURE_URL)
       expect(options.headers['Authorization']).toBe('Bearer TEST_API_KEY')
       expect(options.headers['PostHog-Sdk-Info']).toBe('posthog-node/1.2.3')
       const body = JSON.parse(options.body)
@@ -134,83 +148,69 @@ describe('capture v1 wiring (Node SDK)', () => {
       expect(body.batch[0].options).toEqual({})
     })
 
-    it('routes $ai_* events to the legacy /batch/ endpoint', async () => {
-      const posthog = makeV1Client()
-      posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt' } })
-      await waitForFlushTimer()
-
-      expect(callsTo('/i/v1/analytics/events')).toHaveLength(0)
-      expect(eventsIn('/batch/')).toContain('$ai_generation')
-    })
-
-    it('splits a mixed batch across both endpoints with no loss or duplication', async () => {
-      const posthog = makeV1Client()
+    it('keeps $ai_* capture() events on the analytics endpoint, in the same request as other events', async () => {
+      const posthog = makeClient()
       posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
       posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt' } })
       await waitForFlushTimer()
 
-      expect(eventsIn('/i/v1/analytics/events')).toEqual(['custom'])
-      expect(eventsIn('/batch/')).toEqual(['$ai_generation'])
+      expect(callsTo(ANALYTICS_CAPTURE_PATH)).toHaveLength(1)
+      expect(eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom', '$ai_generation'])
+      expect(callsTo(AI_CAPTURE_PATH)).toHaveLength(0)
+      expect(callsTo('/batch/')).toHaveLength(0)
     })
   })
 
-  describe('v1 mode - immediate path', () => {
+  describe('immediate path', () => {
     it('sends an immediate non-AI event to the v1 endpoint', async () => {
-      const posthog = makeV1Client()
+      const posthog = makeClient()
       await posthog.captureImmediate({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
 
       expect(callsTo('/batch/')).toHaveLength(0)
-      expect(eventsIn('/i/v1/analytics/events')).toEqual(['custom'])
+      expect(eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
     })
 
-    it('sends an immediate $ai_* event to the legacy endpoint', async () => {
-      const posthog = makeV1Client()
+    it('sends an immediate $ai_* event to the analytics endpoint', async () => {
+      const posthog = makeClient()
       await posthog.captureImmediate({ distinctId: 'u', event: '$ai_span', properties: { $ai_model: 'gpt' } })
 
-      expect(callsTo('/i/v1/analytics/events')).toHaveLength(0)
-      expect(eventsIn('/batch/')).toContain('$ai_span')
+      expect(eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['$ai_span'])
+      expect(callsTo(AI_CAPTURE_PATH)).toHaveLength(0)
+      expect(callsTo('/batch/')).toHaveLength(0)
     })
 
     it('sends immediate identify/alias/groupIdentify (special non-AI events) to the v1 endpoint', async () => {
-      const posthog = makeV1Client()
+      const posthog = makeClient()
 
       await posthog.identifyImmediate({ distinctId: 'u', properties: { name: 'a' } })
       await posthog.aliasImmediate({ distinctId: 'u', alias: 'anon-1' })
       await posthog.groupIdentifyImmediate({ groupType: 'company', groupKey: 'acme', properties: { plan: 'pro' } })
 
       expect(callsTo('/batch/')).toHaveLength(0)
-      expect(eventsIn('/i/v1/analytics/events')).toEqual(['$identify', '$create_alias', '$groupidentify'])
+      expect(eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['$identify', '$create_alias', '$groupidentify'])
     })
   })
 
-  describe('v1 mode - before_send interaction', () => {
-    it('routes an event renamed into $ai_* by before_send to the legacy endpoint', async () => {
-      const posthog = makeV1Client({
-        before_send: (event) => (event ? { ...event, event: '$ai_generation' } : event),
-      })
-      posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
-      await waitForFlushTimer()
-
-      expect(callsTo('/i/v1/analytics/events')).toHaveLength(0)
-      expect(eventsIn('/batch/')).toContain('$ai_generation')
-    })
-
-    it('routes an event renamed out of $ai_* by before_send to the v1 endpoint', async () => {
-      const posthog = makeV1Client({
-        before_send: (event) => (event ? { ...event, event: 'renamed' } : event),
+  describe('before_send interaction', () => {
+    it.each([
+      ['into', 'custom', '$ai_generation'],
+      ['out of', '$ai_generation', 'renamed'],
+    ])('keeps an event renamed %s $ai_* by before_send on the analytics endpoint', async (_, original, renamed) => {
+      const posthog = makeClient({
+        before_send: (event) => (event ? { ...event, event: renamed } : event),
       })
-      posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt' } })
+      posthog.capture({ distinctId: 'u', event: original, properties: { x: 1 } })
       await waitForFlushTimer()
 
-      expect(callsTo('/batch/')).toHaveLength(0)
-      expect(eventsIn('/i/v1/analytics/events')).toContain('renamed')
+      expect(eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual([renamed])
+      expect(callsTo(AI_CAPTURE_PATH)).toHaveLength(0)
     })
   })
 
-  describe('v1 mode - error surfacing', () => {
-    it('emits a CaptureV1Error on the error channel when the server drops an event', async () => {
+  describe('error surfacing', () => {
+    it('emits an exported CaptureError naming the analytics lane when the server drops an event', async () => {
       mockedFetch.mockImplementation((url, options) => {
-        if ((url as string).includes('/i/v1/analytics/events')) {
+        if ((url as string).includes(ANALYTICS_CAPTURE_PATH)) {
           const body = JSON.parse((options as any).body)
           const results: Record<string, unknown> = {}
           for (const event of body.batch) {
@@ -218,10 +218,10 @@ describe('capture v1 wiring (Node SDK)', () => {
           }
           return Promise.resolve(v1Response(results))
         }
-        return Promise.resolve(v0Response())
+        return Promise.resolve(okResponse())
       })
 
-      const posthog = makeV1Client()
+      const posthog = makeClient()
       const errors: Error[] = []
       posthog.on('error', (error) => errors.push(error))
 
@@ -229,8 +229,9 @@ describe('capture v1 wiring (Node SDK)', () => {
       await waitForFlushTimer()
 
       expect(errors).toHaveLength(1)
-      const error = errors[0] as CaptureV1Error
-      expect(error).toBeInstanceOf(CaptureV1Error)
+      const error = errors[0] as CaptureError
+      expect(error).toBeInstanceOf(CaptureError)
+      expect(error.endpoint).toBe(ANALYTICS_CAPTURE_PATH)
       expect(error.drops[0].details).toBe('billing')
     })
   })
diff --git a/packages/node/src/__tests__/edge-exports.spec.ts b/packages/node/src/__tests__/edge-exports.spec.ts
index 8db27fd6d6..4a194f1fa9 100644
--- a/packages/node/src/__tests__/edge-exports.spec.ts
+++ b/packages/node/src/__tests__/edge-exports.spec.ts
@@ -45,7 +45,9 @@ describe('built edge entrypoints', () => {
       }
     )
 
-    expect(JSON.parse(output).flatMap(sentEventsOf)).toEqual([
+    const requests = JSON.parse(output)
+    expect(requests.map(([url]: [string]) => url)).toEqual(['https://example.test/i/v1/analytics/events'])
+    expect(requests.flatMap(sentEventsOf)).toEqual([
       expect.objectContaining({
         distinct_id: 'edge-user',
         event: 'edge-event',
diff --git a/packages/node/src/__tests__/immediate-delivery.spec.ts b/packages/node/src/__tests__/immediate-delivery.spec.ts
index b71e761888..9a97dcf66b 100644
--- a/packages/node/src/__tests__/immediate-delivery.spec.ts
+++ b/packages/node/src/__tests__/immediate-delivery.spec.ts
@@ -2,12 +2,14 @@ import { PostHog } from '@/entrypoints/index.node'
 
 vi.mock('../version', () => ({ version: '1.2.3' }))
 
+const accepted = (): Response => new Response(JSON.stringify({ results: {} }), { status: 200 })
+
 describe('immediate write responses', () => {
   let posthog: PostHog
   const fetch = vi.spyOn(globalThis, 'fetch')
 
   beforeEach(() => {
-    fetch.mockReset().mockResolvedValue(new Response(null, { status: 200 }))
+    fetch.mockReset().mockImplementation(() => Promise.resolve(accepted()))
     posthog = new PostHog('TEST_API_KEY', {
       host: 'http://example.com',
       flushInterval: 0,
@@ -18,7 +20,7 @@ describe('immediate write responses', () => {
   })
 
   afterEach(async () => {
-    fetch.mockResolvedValue(new Response(null, { status: 200 }))
+    fetch.mockImplementation(() => Promise.resolve(accepted()))
     await posthog.shutdown()
   })
 
@@ -32,14 +34,17 @@ describe('immediate write responses', () => {
     await expect(posthog.captureImmediate({ distinctId: '123', event: 'test-event' })).resolves.toBeUndefined()
 
     expect(onError).toHaveBeenCalledTimes(1)
-    expect(onError.mock.calls[0][0]).toMatchObject({ name: 'PostHogFetchHttpError', status })
+    expect(onError.mock.calls[0][0]).toMatchObject({
+      name: 'CaptureError',
+      endpoint: '/i/v1/analytics/events',
+      cause: expect.objectContaining({ message: expect.stringContaining(`HTTP ${status}`) }),
+    })
     expect(fetch).toHaveBeenCalledTimes(1)
   })
 
-  it.each([200, 204])('accepts HTTP %i without emitting an error', async (status) => {
+  it('accepts a 2xx results body without emitting an error', async () => {
     const onError = vi.fn()
     posthog.on('error', onError)
-    fetch.mockResolvedValue(new Response(null, { status }))
 
     await expect(posthog.captureImmediate({ distinctId: '123', event: 'test-event' })).resolves.toBeUndefined()
 
@@ -47,7 +52,8 @@ describe('immediate write responses', () => {
     expect(fetch).toHaveBeenCalledTimes(1)
   })
 
-  it('drains queued events within the shutdown budget when an immediate error body stalls', async () => {
+  // Skipped: the capture sender reads a terminal error body for up to requestTimeout, which outlasts this shutdown budget.
+  it.skip('drains queued events within the shutdown budget when an immediate error body stalls', async () => {
     let respond!: (response: Response) => void
     fetch.mockImplementationOnce(
       () =>
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index 40b6263942..85972cc57b 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -1,4 +1,4 @@
-import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
+import { CaptureError, PostHog, PostHogOptions } from '@/entrypoints/index.node'
 import ErrorTracking from '@/extensions/error-tracking'
 import type { IPostHog } from '@/types'
 import {
@@ -6,6 +6,7 @@ import {
   anyFlagsCall,
   anyLocalEvalCall,
   apiImplementation,
+  lastCaptureBatch,
   lastSentBatch,
   sentEvents,
   v1Response,
@@ -111,6 +112,10 @@ describe('PostHog Node.js', () => {
           timestamp: expect.any(String),
         },
       ])
+      // On the wire, `$lib`/`$lib_version` travel in the SDK info header, not in properties.
+      expect(lastCaptureBatch(mockedFetch)?.[0].properties).not.toHaveProperty('$lib')
+      const [, options] = mockedFetch.mock.calls.at(-1)!
+      expect((options as any).headers['PostHog-Sdk-Info']).toBe('posthog-node/1.2.3')
     })
 
     it('flush waits for pending captureException async work before flushing', async () => {
@@ -1044,7 +1049,9 @@ describe('PostHog Node.js', () => {
         await vi.advanceTimersByTimeAsync(0)
         expect(mockedFetch).toHaveBeenCalledTimes(1)
 
+        // The failed batch is reported and consumed, so two new events are needed to reach flushAt again.
         ph.capture({ event: 'offline-event-20', distinctId: '123' })
+        ph.capture({ event: 'offline-event-21', distinctId: '123' })
         await vi.advanceTimersByTimeAsync(0)
         expect(mockedFetch).toHaveBeenCalledTimes(2)
         rejectFetch.shift()!(new Error('network down'))
@@ -1205,16 +1212,15 @@ describe('PostHog Node.js', () => {
 
       ph.capture({ event: 'test-event', distinctId: '123' })
 
-      // shutdown() joins the promise queue (waits for capture's async prepareEventMessage),
-      // then flushes. The flush calls fetchWithRetry → hangingFetch → abort fires after 10ms.
-      // _flush() catch emits 'error' (posthog-core-stateless.ts:1159) and re-throws.
-      // doShutdown() catches the PostHogFetchError and returns cleanly.
+      // shutdown() waits for capture preparation, then flushes. The capture sender aborts the
+      // hanging request after requestTimeout and reports the batch on the error channel.
       await ph.shutdown()
 
-      expect(hangingFetch).toHaveBeenCalled()
+      expect(hangingFetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
-      expect(errors[0].name).toBe('PostHogFetchNetworkError')
-      expect(errors[0].error.name).toBe('AbortError')
+      expect(errors[0]).toBeInstanceOf(CaptureError)
+      expect(errors[0].endpoint).toBe('/i/v1/analytics/events')
+      expect(errors[0].cause.name).toBe('AbortError')
     }, 10000)
   })
 
diff --git a/packages/node/src/__tests__/server-wire-snapshots.spec.ts b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
index 9a14e30fdc..025f17762e 100644
--- a/packages/node/src/__tests__/server-wire-snapshots.spec.ts
+++ b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
@@ -4,8 +4,8 @@ import type { PostHogFetchOptions } from '@posthog/core'
 
 import { V1CaptureSender } from '@/capture-v1/sender'
 import { PostHog } from '@/entrypoints/index.node'
-import { v1Response } from './utils'
-import { v0Response } from './utils/v1-wiring'
+import { captureCalls, v1Response } from './utils'
+import { okResponse } from './utils/v1-wiring'
 
 type FetchCall = [string, PostHogFetchOptions]
 
@@ -61,7 +61,7 @@ describe('server wire snapshots', () => {
   beforeEach(() => {
     vi.setSystemTime(FIXED_NOW)
     mockedFetch.mockImplementation((url) =>
-      Promise.resolve((url as string).includes('/i/v1/analytics/events') ? v1Response() : v0Response())
+      Promise.resolve((url as string).includes('/i/v1/analytics/events') ? v1Response() : okResponse())
     )
   })
 
@@ -75,6 +75,7 @@ describe('server wire snapshots', () => {
     const sender = new V1CaptureSender(
       {
         host: 'https://us.example.test',
+        path: '/i/v1/analytics/events',
         apiKey: 'phc_capture_secret',
         libraryId: 'posthog-node',
         libraryVersion: '1.2.3',
@@ -137,23 +138,11 @@ describe('server wire snapshots', () => {
   })
 
   it('snapshots a deterministic complete captureException wire event', async () => {
-    const previousCaptureMode = process.env.POSTHOG_CAPTURE_MODE
-    process.env.POSTHOG_CAPTURE_MODE = 'v0'
-
-    let posthog: PostHog
-    try {
-      posthog = new PostHog('phc_exception_secret', {
-        host: 'https://us.example.test',
-        fetchRetryCount: 0,
-        disableCompression: true,
-      })
-    } finally {
-      if (previousCaptureMode === undefined) {
-        delete process.env.POSTHOG_CAPTURE_MODE
-      } else {
-        process.env.POSTHOG_CAPTURE_MODE = previousCaptureMode
-      }
-    }
+    const posthog = new PostHog('phc_exception_secret', {
+      host: 'https://us.example.test',
+      fetchRetryCount: 0,
+      disableCompression: true,
+    })
     clients.push(posthog)
 
     const error = new TypeError('database unavailable')
@@ -176,8 +165,15 @@ describe('server wire snapshots', () => {
     await (posthog as any).promiseQueue.join()
     await posthog.flush()
 
-    const call = mockedFetch.mock.calls.find(([url]) => (url as string).includes('/batch/')) as FetchCall
-    expect(snapshotRequest(call)).toMatchSnapshot()
+    const calls = captureCalls(mockedFetch)
+    expect(calls).toHaveLength(1)
+    const [url, options] = calls[0] as FetchCall
+    const headers = options.headers as Record<string, string>
+    // The client generates a fresh request id per batch, so pin its shape rather than its value.
+    expect(headers['PostHog-Request-Id']).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[0-9a-f]{4}-[0-9a-f]{12}$/)
+    expect(
+      snapshotRequest([url, { ...options, headers: { ...headers, 'PostHog-Request-Id': '<generated>' } }])
+    ).toMatchSnapshot()
   })
 
   it('snapshots a maximal flags request body', async () => {
@@ -189,7 +185,7 @@ describe('server wire snapshots', () => {
           json: () => Promise.resolve({ flags: {}, errorsWhileComputingFlags: false }),
         } as any)
       }
-      return Promise.resolve(v0Response())
+      return Promise.resolve(okResponse())
     })
 
     const posthog = new PostHog('phc_flags_secret', {
diff --git a/packages/node/src/__tests__/utils/index.ts b/packages/node/src/__tests__/utils/index.ts
index 225d2cee3d..4b12b3ce9e 100644
--- a/packages/node/src/__tests__/utils/index.ts
+++ b/packages/node/src/__tests__/utils/index.ts
@@ -1,15 +1,22 @@
 import { PostHogV2FlagsResponse } from '@posthog/core'
 import util from 'util'
 
+export const ANALYTICS_CAPTURE_PATH = '/i/v1/analytics/events'
+export const AI_CAPTURE_PATH = '/i/v1/ai/events'
+export const ANALYTICS_CAPTURE_URL = `http://example.com${ANALYTICS_CAPTURE_PATH}`
+export const AI_CAPTURE_URL = `http://example.com${AI_CAPTURE_PATH}`
+
 const LEGACY_CAPTURE_PATH = '/batch/'
-const V1_ANALYTICS_CAPTURE_PATH = '/i/v1/analytics/events'
-const ANALYTICS_CAPTURE_PATHS = [LEGACY_CAPTURE_PATH, V1_ANALYTICS_CAPTURE_PATH]
+const ANALYTICS_CAPTURE_PATHS = [LEGACY_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH]
 
 const isAnalyticsCaptureUrl = (url: unknown): boolean => {
   const { pathname } = new URL(String(url))
   return ANALYTICS_CAPTURE_PATHS.includes(pathname)
 }
 
+export const isCaptureUrl = (url: unknown): boolean =>
+  isAnalyticsCaptureUrl(url) || String(url).includes(AI_CAPTURE_PATH)
+
 /** Matches the analytics capture URL of either wire format: legacy `/batch/` or Capture V1. */
 export const anyCaptureUrl = expect.stringMatching(/^https?:\/\/[^/]+(\/batch\/|\/i\/v1\/analytics\/events)$/)
 
@@ -25,9 +32,36 @@ export function v1Response(results: Record<string, unknown> = {}): any {
   }
 }
 
+export function v413Response(): any {
+  return {
+    status: 413,
+    text: () => Promise.resolve('Content Too Large'),
+    json: () => Promise.resolve({ status: 'Content Too Large' }),
+    headers: { get: () => null },
+    body: null,
+  }
+}
+
 type FetchMock = { mock: { calls: any[][] } }
 type FetchCall = [string, any]
 
+/** Fetch calls whose URL contains `path`, as `[url, options]` tuples. */
+export const captureCalls = (fetchMock: FetchMock, path: string = ANALYTICS_CAPTURE_PATH): FetchCall[] =>
+  fetchMock.mock.calls.filter((call) => String(call[0]).includes(path)) as FetchCall[]
+
+/** The decoded (uncompressed) Capture V1 body of one fetch call. */
+export const captureBody = (call: FetchCall): any => JSON.parse(call[1].body)
+
+/** Capture V1 wire events from every capture request to `path`, in call order. */
+export const captureEvents = (fetchMock: FetchMock, path: string = ANALYTICS_CAPTURE_PATH): any[] =>
+  captureCalls(fetchMock, path).flatMap((call) => captureBody(call).batch)
+
+/** Capture V1 wire events from the most recent capture request to `path`, or `undefined` if none was sent. */
+export const lastCaptureBatch = (fetchMock: FetchMock, path: string = ANALYTICS_CAPTURE_PATH): any[] | undefined => {
+  const calls = captureCalls(fetchMock, path)
+  return calls.length ? captureBody(calls[calls.length - 1]).batch : undefined
+}
+
 /** Capture V1 per-event `options`, keyed by the legacy property each one replaces. */
 const V1_OPTION_PROPERTIES: Record<string, string> = {
   cookieless_mode: '$cookieless_mode',
@@ -62,7 +96,7 @@ function legacyPropertiesOf(v1Event: any, sdkInfo: string): Record<string, any>
  */
 export function sentEventsOf([url, options]: FetchCall): any[] {
   const { batch } = JSON.parse(options.body)
-  if (new URL(url).pathname !== V1_ANALYTICS_CAPTURE_PATH) {
+  if (new URL(url).pathname !== ANALYTICS_CAPTURE_PATH) {
     return batch
   }
   return batch.map((v1Event: any) => {
@@ -109,7 +143,7 @@ export const apiImplementationV4 = (flagsResponse: PostHogV2FlagsResponse | Erro
           })
     }
 
-    if (isAnalyticsCaptureUrl(url)) {
+    if (isCaptureUrl(url)) {
       return Promise.resolve(v1Response())
     }
 
@@ -179,7 +213,7 @@ export const apiImplementation = ({
       }) as any
     }
 
-    if (isAnalyticsCaptureUrl(url)) {
+    if (isCaptureUrl(url)) {
       return Promise.resolve(v1Response())
     }
 
diff --git a/packages/node/src/__tests__/utils/v1-wiring.ts b/packages/node/src/__tests__/utils/v1-wiring.ts
index c440f4913b..d5bd86f85c 100644
--- a/packages/node/src/__tests__/utils/v1-wiring.ts
+++ b/packages/node/src/__tests__/utils/v1-wiring.ts
@@ -1,11 +1,9 @@
 import { PostHog, PostHogOptions } from '@/entrypoints/index.node'
 
-import { v1Response, waitForPromises } from '.'
+import { captureCalls, captureEvents, isCaptureUrl, v1Response, waitForPromises } from '.'
 
-export const V1_URL = 'http://example.com/i/v1/analytics/events'
-
-/** A legacy `/batch/` 2xx response. */
-export function v0Response(): any {
+/** A generic 2xx response for the non-capture endpoints (logs, metrics, flags). */
+export function okResponse(): any {
   return {
     status: 200,
     text: () => Promise.resolve('ok'),
@@ -15,29 +13,18 @@ export function v0Response(): any {
   }
 }
 
-export function v413Response(): any {
-  return {
-    status: 413,
-    text: () => Promise.resolve('Content Too Large'),
-    json: () => Promise.resolve({ status: 'Content Too Large' }),
-    headers: { get: () => null },
-    body: null,
-  }
-}
-
-/** Default fetch behavior: the v1 endpoint returns all-accepted, everything else a v0 200. */
+/** Default fetch behavior: capture endpoints accept every event, everything else returns a 200. */
 export function routeByUrl(url: string): any {
-  return url.includes('/i/v1/analytics/events') ? v1Response() : v0Response()
+  return isCaptureUrl(url) ? v1Response() : okResponse()
 }
 
 /**
- * Shared fixture for the Capture V1 wiring/integration specs: owns the global `fetch` spy, tracks
+ * Shared fixture for the capture wiring/integration specs: owns the global `fetch` spy, tracks
  * clients for teardown, and exposes call inspectors so each suite only writes its own scenario.
  */
 export class V1WiringHarness {
   readonly fetch: vi.SpyInstance
   private readonly clients: PostHog[] = []
-  private readonly originalCaptureMode = process.env.POSTHOG_CAPTURE_MODE
 
   constructor() {
     this.fetch = vi.spyOn(globalThis, 'fetch').mockImplementation()
@@ -48,53 +35,31 @@ export class V1WiringHarness {
     this.fetch.mockImplementation((url: any) => Promise.resolve(routeByUrl(url as string)))
   }
 
-  /**
-   * Capture V1 is opt-in via the `POSTHOG_CAPTURE_MODE` env var only (no public option).
-   * The mode is resolved once, in the PostHog constructor, so toggling the env var around
-   * construction keeps each client hermetic even when v0 and v1 clients coexist in a suite.
-   */
-  makeClient(options: PostHogOptions = {}, captureMode?: 'v0' | 'v1'): PostHog {
-    const previous = process.env.POSTHOG_CAPTURE_MODE
-    if (captureMode !== undefined) {
-      process.env.POSTHOG_CAPTURE_MODE = captureMode
-    }
-    try {
-      const client = new PostHog('TEST_API_KEY', {
-        host: 'http://example.com',
-        fetchRetryCount: 0,
-        disableCompression: true,
-        ...options,
-      })
-      this.clients.push(client)
-      return client
-    } finally {
-      if (previous === undefined) {
-        delete process.env.POSTHOG_CAPTURE_MODE
-      } else {
-        process.env.POSTHOG_CAPTURE_MODE = previous
-      }
-    }
+  makeClient(options: PostHogOptions = {}): PostHog {
+    const client = new PostHog('TEST_API_KEY', {
+      host: 'http://example.com',
+      fetchRetryCount: 0,
+      disableCompression: true,
+      ...options,
+    })
+    this.clients.push(client)
+    return client
   }
 
   /** All fetch calls whose URL contains `fragment`, as `[url, options]` tuples. */
   callsTo(fragment: string): [string, any][] {
-    return this.fetch.mock.calls.filter((call: any[]) => (call[0] as string).includes(fragment)) as [string, any][]
+    return captureCalls(this.fetch, fragment)
   }
 
   /** Event names carried in every batch posted to a URL containing `fragment`, in call order. */
   eventsIn(fragment: string): string[] {
-    return this.callsTo(fragment).flatMap((call) => JSON.parse(call[1].body).batch.map((event: any) => event.event))
+    return captureEvents(this.fetch, fragment).map((event: any) => event.event)
   }
 
   async cleanup(): Promise<void> {
     while (this.clients.length) {
       await this.clients.pop()?.shutdown()
     }
-    if (this.originalCaptureMode === undefined) {
-      delete process.env.POSTHOG_CAPTURE_MODE
-    } else {
-      process.env.POSTHOG_CAPTURE_MODE = this.originalCaptureMode
-    }
   }
 }
 
diff --git a/packages/node/src/ai-capture/routing.ts b/packages/node/src/ai-capture/routing.ts
index 819f53f97c..3a4afc3263 100644
--- a/packages/node/src/ai-capture/routing.ts
+++ b/packages/node/src/ai-capture/routing.ts
@@ -1,7 +1,5 @@
 export const AI_CAPTURE_ROUTE = 'ai-capture'
 
-export const AI_CAPTURE_ENDPOINT_PATH = '/i/v0/ai/batch/'
-
 export const AI_MAX_EVENT_BYTES = 8 * 1024 * 1024
 
 export const AI_BATCH_TARGET_BYTES = 5 * 1024 * 1024
diff --git a/packages/node/src/capture-v1/config.ts b/packages/node/src/capture-v1/config.ts
deleted file mode 100644
index 2784d0d468..0000000000
--- a/packages/node/src/capture-v1/config.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-/** Capture submission mode: `v0` is the legacy `/batch/` endpoint, `v1` is `/i/v1/analytics/events`. */
-export type CaptureMode = 'v0' | 'v1'
-
-function isCaptureMode(value: unknown): value is CaptureMode {
-  return value === 'v0' || value === 'v1'
-}
-
-/**
- * Resolve the effective capture mode from the `POSTHOG_CAPTURE_MODE` environment
- * variable (guarded for edge / no-`process` runtimes). The default is `v0`, so
- * existing users are unaffected unless they explicitly opt in. Capture V1 is
- * intentionally env-var-only during the transition — there is no public option,
- * so nothing on the API surface has to be removed when v1 becomes the default.
- */
-export function resolveCaptureMode(): CaptureMode {
-  const envMode = typeof process !== 'undefined' ? process.env?.POSTHOG_CAPTURE_MODE : undefined
-  return isCaptureMode(envMode) ? envMode : 'v0'
-}
diff --git a/packages/node/src/capture-v1/errors.ts b/packages/node/src/capture-v1/errors.ts
index c361632ffa..9568128450 100644
--- a/packages/node/src/capture-v1/errors.ts
+++ b/packages/node/src/capture-v1/errors.ts
@@ -1,13 +1,17 @@
+import type { CaptureEndpoint } from './types'
+
 /** A single event the server explicitly rejected (`drop`). */
-export interface V1DroppedEvent {
+export interface CaptureDroppedEvent {
   uuid: string
   details?: string
 }
 
-export interface CaptureV1ErrorParams {
+export interface CaptureErrorParams {
+  /** The capture lane the batch was sent to. */
+  endpoint: CaptureEndpoint
   requestId: string
   /** Events the server rejected outright (billing/validation). */
-  drops: V1DroppedEvent[]
+  drops: CaptureDroppedEvent[]
   /** UUIDs of events still pending `retry` after the attempt budget was exhausted, or lost to a batch-level failure. */
   retryExhausted: string[]
   /** The underlying transport/HTTP/parse failure, when the whole batch failed. */
@@ -15,22 +19,24 @@ export interface CaptureV1ErrorParams {
 }
 
 /**
- * Surfaced on the client error channel whenever a Capture V1 batch did not
+ * Surfaced on the client error channel whenever a capture batch did not
  * fully deliver: some events were `drop`ped, some `retry` events outlived the
  * attempt budget, or the batch hit a terminal transport/HTTP/parse failure.
  *
  * A 2xx with drops is still a partial failure and is reported here — a
  * successful HTTP status does not mean every event was accepted.
  */
-export class CaptureV1Error extends Error {
-  name = 'CaptureV1Error'
+export class CaptureError extends Error {
+  name = 'CaptureError'
+  readonly endpoint: CaptureEndpoint
   readonly requestId: string
-  readonly drops: V1DroppedEvent[]
+  readonly drops: CaptureDroppedEvent[]
   readonly retryExhausted: string[]
   cause?: unknown
 
-  constructor({ requestId, drops, retryExhausted, cause }: CaptureV1ErrorParams) {
-    super(CaptureV1Error.buildMessage(requestId, drops, retryExhausted, cause))
+  constructor({ endpoint, requestId, drops, retryExhausted, cause }: CaptureErrorParams) {
+    super(CaptureError.buildMessage(endpoint, requestId, drops, retryExhausted, cause))
+    this.endpoint = endpoint
     this.requestId = requestId
     this.drops = drops
     this.retryExhausted = retryExhausted
@@ -38,12 +44,13 @@ export class CaptureV1Error extends Error {
   }
 
   private static buildMessage(
+    endpoint: CaptureEndpoint,
     requestId: string,
-    drops: V1DroppedEvent[],
+    drops: CaptureDroppedEvent[],
     retryExhausted: string[],
     cause: unknown
   ): string {
-    let message = `Capture V1 batch ${requestId} did not fully deliver: ${drops.length} dropped, ${retryExhausted.length} undelivered`
+    let message = `Capture batch ${requestId} to ${endpoint} did not fully deliver: ${drops.length} dropped, ${retryExhausted.length} undelivered`
     if (cause instanceof Error) {
       message += ` (${cause.message})`
     }
diff --git a/packages/node/src/capture-v1/routing.ts b/packages/node/src/capture-v1/routing.ts
deleted file mode 100644
index 1023680e40..0000000000
--- a/packages/node/src/capture-v1/routing.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import type { PostHogEventProperties } from '@posthog/core'
-
-/** Event-name prefix for AI analytics events, which have no Capture V1 form yet. */
-const AI_EVENT_PREFIX = '$ai_'
-
-/**
- * Queue route for events eligible for Capture V1 (everything except `$ai_*`). Its queue is the
- * historical {@link PostHogPersistedProperty.Queue}, so v0 mode is byte-identical to before.
- */
-export const ANALYTICS_ROUTE = 'analytics'
-
-/**
- * Queue route for `$ai_*` events, kept on the legacy (v0) transport in v1 mode and isolated on
- * its own queue so a v0 failure can't re-send events already accepted on the V1 route. This route
- * will later host a dedicated v1 AI-events transport once that endpoint exists — segregating it
- * now means no re-plumbing then.
- */
-export const AI_ROUTE = 'ai'
-
-/**
- * True for events that must keep using the legacy (v0) submitter even when the
- * client is in v1 mode. Today that is only `$ai_*` events: the dedicated AI
- * ingestion path has no v1 form, so they stay on v0 until AI v1 is designed.
- * The check runs on the post-`before_send` event name.
- */
-export function isLegacyOnlyEvent(message: PostHogEventProperties): boolean {
-  return typeof message.event === 'string' && message.event.startsWith(AI_EVENT_PREFIX)
-}
diff --git a/packages/node/src/capture-v1/sender.ts b/packages/node/src/capture-v1/sender.ts
index 7f469c90ba..094ad1a699 100644
--- a/packages/node/src/capture-v1/sender.ts
+++ b/packages/node/src/capture-v1/sender.ts
@@ -6,15 +6,13 @@ import {
   type PostHogFetchResponse,
   gzipCompress,
   safeJsonStringify,
-  safeSetTimeout,
   uuidv7,
 } from '@posthog/core'
 
-import { CaptureV1Error, type V1DroppedEvent } from './errors'
+import { CaptureError, type CaptureDroppedEvent, type CaptureErrorParams } from './errors'
 import { buildV1Batch } from './transform'
-import type { V1BatchResponse, V1Event } from './types'
+import type { CaptureEndpoint, V1BatchResponse, V1Event } from './types'
 
-const V1_ANALYTICS_PATH = '/i/v1/analytics/events'
 const DEFAULT_MAX_BACKOFF_MS = 30_000
 
 /** HTTP statuses the v1 backend wants retried. 429 is intentionally terminal in v1. */
@@ -22,6 +20,8 @@ const RETRYABLE_STATUSES = new Set([408, 500, 502, 503, 504])
 
 export interface V1CaptureSenderConfig {
   host: string
+  /** The capture lane this sender posts to. */
+  path: CaptureEndpoint
   apiKey: string
   /** Canonical `$lib` identity, materialized by the server from `PostHog-Sdk-Info`. */
   libraryId: string
@@ -60,15 +60,15 @@ interface V1CaptureAttempt {
 }
 
 /**
- * Sends already-normalized events to the Capture V1 endpoint
- * (`POST /i/v1/analytics/events`), owning the full attempt loop: per-event
- * partial retry, exponential backoff clamped against `Retry-After`, v1 status
- * classification, and surfacing drops / undelivered events on the error
- * channel. Used by both the batched and immediate send paths.
+ * Sends already-normalized events to one Capture V1 lane (`config.path`),
+ * owning the full attempt loop: per-event partial retry, exponential backoff
+ * clamped against `Retry-After`, v1 status classification, and surfacing drops
+ * / undelivered events on the error channel. Used by both the batched and
+ * immediate send paths.
  *
  * Never throws for a handled outcome: after exhausting its own attempt budget it
  * reports the failure via `onError` and resolves, so the caller's queue treats
- * the batch as consumed (the internal budget replaces v0's queue-level retry).
+ * the batch as consumed (the internal budget replaces the core queue-level retry).
  */
 export class V1CaptureSender {
   private readonly config: V1CaptureSenderConfig
@@ -86,7 +86,9 @@ export class V1CaptureSender {
     this.fetchFn = hooks.fetch
     this.onError = hooks.onError
     this.now = hooks.now ?? Date.now
-    this.sleep = hooks.sleep ?? ((ms) => new Promise((resolve) => safeSetTimeout(resolve, ms)))
+    // Retry waits and request deadlines use ref'd timers, unlike safeSetTimeout, so an
+    // awaited flush or shutdown keeps the process alive until the send finishes.
+    this.sleep = hooks.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
     this.generateRequestId = hooks.generateRequestId ?? uuidv7
     this.compress = hooks.compress ?? gzipCompress
   }
@@ -104,8 +106,8 @@ export class V1CaptureSender {
       historicalMigration: this.config.historicalMigration,
     })
 
-    const url = `${this.config.host}${V1_ANALYTICS_PATH}`
-    const drops: V1DroppedEvent[] = []
+    const url = `${this.config.host}${this.config.path}`
+    const drops: CaptureDroppedEvent[] = []
     let pending = batch
 
     // Guard against a misconfigured budget (e.g. fetchRetryCount: -1): always make
@@ -157,7 +159,7 @@ export class V1CaptureSender {
             return this.surfacePartialDrops(requestId, drops)
           }
           if (isLastAttempt) {
-            this.onError(new CaptureV1Error({ requestId, drops, retryExhausted: retryable.map((event) => event.uuid) }))
+            this.onError(this.captureError({ requestId, drops, retryExhausted: retryable.map((event) => event.uuid) }))
             return
           }
           pending = retryable
@@ -200,12 +202,12 @@ export class V1CaptureSender {
 
     const controller = new AbortController()
     let timeoutPhase = 'waiting for response headers'
-    let timer: ReturnType<typeof safeSetTimeout>
+    let timer: ReturnType<typeof setTimeout> | undefined
     // hooks.fetch is user-injectable, so it may ignore an abort signal while
     // resolving headers or reading the body. Race both phases against the same
     // deadline rather than relying only on standards-compliant fetch behavior.
     const deadline = new Promise<never>((_resolve, reject) => {
-      timer = safeSetTimeout(() => {
+      timer = setTimeout(() => {
         const timeoutError = new Error(
           `Capture V1 request timed out ${timeoutPhase} after ${this.config.requestTimeoutMs}ms`
         )
@@ -280,7 +282,7 @@ export class V1CaptureSender {
    * a terminal failure, `retry` is returned for the next attempt, and
    * `ok`/`warning`/unknown/absent are terminal successes.
    */
-  private classify(pending: V1Event[], parsed: V1BatchResponse, drops: V1DroppedEvent[]): V1Event[] {
+  private classify(pending: V1Event[], parsed: V1BatchResponse, drops: CaptureDroppedEvent[]): V1Event[] {
     const results = parsed.results ?? {}
     const retryable: V1Event[] = []
     for (const event of pending) {
@@ -354,16 +356,25 @@ export class V1CaptureSender {
     return new Error(`Capture V1 request failed with HTTP ${status}${suffix}`)
   }
 
-  private surfaceBatchFailure(requestId: string, drops: V1DroppedEvent[], pending: V1Event[], cause: unknown): void {
-    this.onError(new CaptureV1Error({ requestId, drops, retryExhausted: pending.map((event) => event.uuid), cause }))
+  private surfaceBatchFailure(
+    requestId: string,
+    drops: CaptureDroppedEvent[],
+    pending: V1Event[],
+    cause: unknown
+  ): void {
+    this.onError(this.captureError({ requestId, drops, retryExhausted: pending.map((event) => event.uuid), cause }))
   }
 
-  private surfacePartialDrops(requestId: string, drops: V1DroppedEvent[]): void {
+  private surfacePartialDrops(requestId: string, drops: CaptureDroppedEvent[]): void {
     if (drops.length > 0) {
-      this.onError(new CaptureV1Error({ requestId, drops, retryExhausted: [] }))
+      this.onError(this.captureError({ requestId, drops, retryExhausted: [] }))
     }
   }
 
+  private captureError(params: Omit<CaptureErrorParams, 'endpoint'>): CaptureError {
+    return new CaptureError({ endpoint: this.config.path, ...params })
+  }
+
   private async cancelBody(response: PostHogFetchResponse): Promise<void> {
     try {
       await response.body?.cancel()
diff --git a/packages/node/src/capture-v1/types.ts b/packages/node/src/capture-v1/types.ts
index 253927aff4..dad3db093f 100644
--- a/packages/node/src/capture-v1/types.ts
+++ b/packages/node/src/capture-v1/types.ts
@@ -1,5 +1,13 @@
 import type { PostHogEventProperties } from '@posthog/core'
 
+/** Capture lane for analytics events. */
+export const ANALYTICS_CAPTURE_ENDPOINT = '/i/v1/analytics/events'
+
+/** Capture lane for events sent through `captureAi`. */
+export const AI_CAPTURE_ENDPOINT = '/i/v1/ai/events'
+
+export type CaptureEndpoint = typeof ANALYTICS_CAPTURE_ENDPOINT | typeof AI_CAPTURE_ENDPOINT
+
 /**
  * Typed `options` object on a Capture V1 event. Legacy `$`-prefixed sentinel
  * properties are lifted here (renamed + strictly typed) by the transform.
@@ -13,7 +21,7 @@ export interface V1EventOptions {
 }
 
 /**
- * A single event in a Capture V1 batch (`POST /i/v1/analytics/events`).
+ * A single event in a Capture V1 batch.
  * `session_id`/`window_id` are promoted from the `$session_id`/`$window_id`
  * sentinels; there is no top-level `api_key`.
  */
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index 8e1fa3daba..4d10338e4f 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -6,7 +6,6 @@ import {
   getEventUuid,
   isBlockedUA,
   isPlainObject,
-  isPostHogFetchContentTooLargeError,
   JsonType,
   minimizeFlagCalledEventProperties,
   PostHogCaptureOptions,
@@ -72,11 +71,10 @@ import ErrorTracking from './extensions/error-tracking'
 import { getActiveTraceProperties } from './extensions/error-tracking/trace-context'
 import { PostHogMemoryStorage } from './storage-memory'
 import { ContextData, ContextOptions, IPostHogContext } from './extensions/context/types'
-import { type CaptureMode, resolveCaptureMode } from './capture-v1/config'
-import { AI_ROUTE, ANALYTICS_ROUTE, isLegacyOnlyEvent } from './capture-v1/routing'
-import { V1CaptureSender } from './capture-v1/sender'
-import { eventByteSize, partitionAiBatch } from './ai-capture/batching'
-import { AI_CAPTURE_ENDPOINT_PATH, AI_CAPTURE_ROUTE, AI_MAX_EVENT_BYTES } from './ai-capture/routing'
+import { V1CaptureSender, type V1CaptureSenderConfig } from './capture-v1/sender'
+import { AI_CAPTURE_ENDPOINT, ANALYTICS_CAPTURE_ENDPOINT, type CaptureEndpoint } from './capture-v1/types'
+import { partitionAiBatch } from './ai-capture/batching'
+import { AI_CAPTURE_ROUTE, AI_MAX_EVENT_BYTES } from './ai-capture/routing'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
 // so the fastest a poller should ever be set is 100ms.
@@ -88,6 +86,9 @@ const WAITUNTIL_DEBOUNCE_MS = 50
 const WAITUNTIL_MAX_WAIT_MS = 500
 const DEFAULT_NODE_HOST = 'https://us.i.posthog.com'
 
+/** Queue route for `capture()` events; its queue is the historical {@link PostHogPersistedProperty.Queue}. */
+const ANALYTICS_ROUTE = 'analytics'
+
 // Process-wide dedup for deprecation warnings — without this, calling a deprecated
 // method in a loop would spam logs. Matches Python's `warnings.warn` default-dedup behavior.
 const _emittedDeprecations = new Set<string>()
@@ -162,8 +163,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   private _traces?: PostHogTraces
   private _spanContext?: SpanContextManager
 
-  private readonly captureMode: CaptureMode
-  private _v1Sender?: V1CaptureSender
+  private readonly _captureSenders = new Map<CaptureEndpoint, V1CaptureSender>()
   /** Whether this client captures full AI content: see `enableFullAiCapture` in `PostHogOptions`. */
   public readonly enableFullAiCapture: boolean
   /** Whether PostHog AI integrations redact content: see `privacyMode` in `PostHogOptions`. */
@@ -251,7 +251,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     super(normalizedApiKey, normalizedOptions)
 
     this.options = normalizedOptions
-    this.captureMode = resolveCaptureMode()
+    this.warnIfCaptureModeSet()
     this.enableFullAiCapture = normalizedOptions.enableFullAiCapture === true
     this.privacyMode = normalizedOptions.privacyMode === true
     this.context = this.initializeContext()
@@ -506,127 +506,90 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return this.options.fetch ? this.options.fetch(url, options) : fetch(url, options)
   }
 
-  /**
-   * Route an event to its queue. In v1 mode `$ai_*` events go to the isolated {@link AI_ROUTE}
-   * (legacy transport) and everything else to {@link ANALYTICS_ROUTE} (Capture V1); in v0 mode
-   * every event stays on {@link ANALYTICS_ROUTE}, which maps to the historical queue. Routing runs
-   * on the post-`before_send`, normalized event name (core calls this after `processBeforeEnqueue`).
-   */
-  protected getQueueRouteKey(message: PostHogEventProperties): string {
-    return this.captureMode === 'v1' && isLegacyOnlyEvent(message) ? AI_ROUTE : ANALYTICS_ROUTE
+  /** Every `capture()` event, including `$ai_*`, stays on the analytics route. */
+  protected getQueueRouteKey(_message: PostHogEventProperties): string {
+    return ANALYTICS_ROUTE
   }
 
   protected persistedQueueKeyForRoute(route: string): PostHogPersistedProperty {
-    if (route === AI_CAPTURE_ROUTE) {
-      return PostHogPersistedProperty.AiCaptureQueue
-    }
-    return route === AI_ROUTE ? PostHogPersistedProperty.AiQueue : PostHogPersistedProperty.Queue
+    return route === AI_CAPTURE_ROUTE ? PostHogPersistedProperty.AiCaptureQueue : PostHogPersistedProperty.Queue
   }
 
   protected getActiveQueueRoutes(): string[] {
-    const routes = this.captureMode === 'v1' ? [ANALYTICS_ROUTE, AI_ROUTE] : [ANALYTICS_ROUTE]
-    if (this._aiCaptureRouteActive) {
-      routes.push(AI_CAPTURE_ROUTE)
-    }
-    return routes
-  }
-
-  protected getBatchEndpointPath(route: string): string {
-    return route === AI_CAPTURE_ROUTE ? AI_CAPTURE_ENDPOINT_PATH : super.getBatchEndpointPath(route)
+    return this._aiCaptureRouteActive ? [ANALYTICS_ROUTE, AI_CAPTURE_ROUTE] : [ANALYTICS_ROUTE]
   }
 
   /**
    * Capture submission seam shared by the batched (`_flush`) and immediate (`sendImmediate`)
-   * paths. Events are routed to homogeneous per-route queues at enqueue time, so a batch here is
-   * never mixed: the {@link AI_ROUTE} (and all of v0 mode) uses the legacy `/batch/` transport,
-   * which throws so `_flush` can shrink/persist/retry its own queue; the {@link ANALYTICS_ROUTE}
-   * in v1 mode uses the Capture V1 endpoint. Because the routes flush independently, a v0/AI leg
-   * failure can never re-send analytics events already accepted on the V1 leg.
+   * paths. Each route has its own queue and capture lane, so a failure on one lane can never
+   * re-send events already accepted on the other. The sender reports failures on the error
+   * channel and resolves, so `_flush` treats every batch as consumed.
    */
   protected async sendBatch(
     batchMessages: (PostHogEventProperties | undefined)[],
-    retryOptions?: Partial<RetriableOptions>,
+    _retryOptions?: Partial<RetriableOptions>,
     route: string = ANALYTICS_ROUTE
   ): Promise<void> {
     if (route === AI_CAPTURE_ROUTE) {
-      return this.sendAiCaptureBatch(batchMessages, retryOptions)
-    }
-
-    if (this.captureMode !== 'v1' || route === AI_ROUTE) {
-      return super.sendBatch(batchMessages, retryOptions, route)
+      return this.sendAiCaptureBatch(batchMessages)
     }
 
-    // Analytics route in v1 mode: homogeneous (no `$ai_*`, routed away at enqueue) and never
-    // undefined for a freshly-enqueued event; drop any legacy undefined queue artifacts.
-    const v1Events = batchMessages.filter((message): message is PostHogEventProperties => message !== undefined)
-    await this.getV1Sender().sendV1Batch(v1Events)
+    // A freshly-enqueued event is never undefined; drop any legacy undefined queue artifacts.
+    const events = batchMessages.filter((message): message is PostHogEventProperties => message !== undefined)
+    await this.getCaptureSender(ANALYTICS_CAPTURE_ENDPOINT).sendV1Batch(events)
   }
 
-  private async sendAiCaptureBatch(
-    batchMessages: (PostHogEventProperties | undefined)[],
-    retryOptions?: Partial<RetriableOptions>
-  ): Promise<void> {
+  private async sendAiCaptureBatch(batchMessages: (PostHogEventProperties | undefined)[]): Promise<void> {
     const { batches, dropped } = partitionAiBatch(batchMessages)
     for (const { event, bytes } of dropped) {
-      const message = `Event ${event} (${bytes} bytes) exceeds the ${AI_MAX_EVENT_BYTES / (1024 * 1024)}MiB limit for ${AI_CAPTURE_ENDPOINT_PATH}, dropping.`
+      const message = `Event ${event} (${bytes} bytes) exceeds the ${AI_MAX_EVENT_BYTES / (1024 * 1024)}MiB limit for ${AI_CAPTURE_ENDPOINT}, dropping.`
       this._logger.error(message)
       this._events.emit('error', new Error(message))
     }
+    const sender = this.getCaptureSender(AI_CAPTURE_ENDPOINT)
     for (const batch of batches) {
-      await this.sendAiSubBatch(batch, retryOptions)
+      await sender.sendV1Batch(batch)
     }
   }
 
-  // A single-event 413 means the server's cap is below that event's size, so no split can save it.
-  private async sendAiSubBatch(
-    batch: PostHogEventProperties[],
-    retryOptions?: Partial<RetriableOptions>
-  ): Promise<void> {
-    try {
-      await super.sendBatch(batch, retryOptions, AI_CAPTURE_ROUTE)
-    } catch (err) {
-      if (!isPostHogFetchContentTooLargeError(err)) {
-        throw err
-      }
-      if (batch.length === 1) {
-        const [event] = batch
-        const eventName = typeof event.event === 'string' ? event.event : 'unknown'
-        const message = `Event ${eventName} (${eventByteSize(event)} bytes) was rejected with 413 by ${AI_CAPTURE_ENDPOINT_PATH} on its own, dropping.`
-        this._logger.error(message)
-        this._events.emit('error', new Error(message))
-        return
-      }
-      const mid = Math.ceil(batch.length / 2)
-      await this.sendAiSubBatch(batch.slice(0, mid), retryOptions)
-      await this.sendAiSubBatch(batch.slice(mid), retryOptions)
+  private getCaptureSender(path: CaptureEndpoint): V1CaptureSender {
+    let sender = this._captureSenders.get(path)
+    if (!sender) {
+      sender = new V1CaptureSender(this.captureSenderConfig(path), {
+        fetch: (url, fetchOptions) => this.fetch(url, fetchOptions),
+        onError: (error) => this._events.emit('error', error),
+        compress: (payload) => this.compressPayload(payload),
+      })
+      this._captureSenders.set(path, sender)
     }
+    return sender
   }
 
-  private getV1Sender(): V1CaptureSender {
-    if (!this._v1Sender) {
-      this._v1Sender = new V1CaptureSender(
-        {
-          host: this.host,
-          apiKey: this.apiKey,
-          libraryId: this.getLibraryId(),
-          libraryVersion: this.getLibraryVersion(),
-          userAgent: this.getCustomUserAgent() || undefined,
-          historicalMigration: this.historicalMigration,
-          compressionEnabled: !this.disableCompression,
-          requestTimeoutMs: this.requestTimeout,
-          // Reuse the existing v0 retry knobs: 1 initial attempt + fetchRetryCount retries.
-          maxAttempts: (this.options.fetchRetryCount ?? 3) + 1,
-          initialRetryDelayMs: this.options.fetchRetryDelay ?? 3000,
-          isDebug: this.isDebug,
-        },
-        {
-          fetch: (url, fetchOptions) => this.fetch(url, fetchOptions),
-          onError: (error) => this._events.emit('error', error),
-          compress: (payload) => this.compressPayload(payload),
-        }
-      )
+  /** Every lane shares the client's retry, timeout and compression settings. */
+  private captureSenderConfig(path: CaptureEndpoint): V1CaptureSenderConfig {
+    return {
+      host: this.host,
+      path,
+      apiKey: this.apiKey,
+      libraryId: this.getLibraryId(),
+      libraryVersion: this.getLibraryVersion(),
+      userAgent: this.getCustomUserAgent() || undefined,
+      historicalMigration: this.historicalMigration,
+      compressionEnabled: !this.disableCompression,
+      requestTimeoutMs: this.requestTimeout,
+      // 1 initial attempt + fetchRetryCount retries.
+      maxAttempts: (this.options.fetchRetryCount ?? 3) + 1,
+      initialRetryDelayMs: this.options.fetchRetryDelay ?? 3000,
+      isDebug: this.isDebug,
+    }
+  }
+
+  private warnIfCaptureModeSet(): void {
+    const captureMode = typeof process !== 'undefined' ? process.env?.POSTHOG_CAPTURE_MODE : undefined
+    if (captureMode !== undefined) {
+      // console.warn, not this._logger: the logger only prints in debug mode, which cannot be on yet.
+      console.warn('[PostHog] POSTHOG_CAPTURE_MODE is no longer read. Capture always uses capture v1.')
     }
-    return this._v1Sender
   }
 
   /**
diff --git a/packages/node/src/exports.ts b/packages/node/src/exports.ts
index b30dd1de21..c633931daf 100644
--- a/packages/node/src/exports.ts
+++ b/packages/node/src/exports.ts
@@ -3,6 +3,9 @@ export * from './extensions/express'
 export * from './types'
 
 export { FeatureFlagEvaluations } from './feature-flag-evaluations'
+export { CaptureError } from './capture-v1/errors'
+export type { CaptureDroppedEvent, CaptureErrorParams } from './capture-v1/errors'
+export type { CaptureEndpoint } from './capture-v1/types'
 export type {
   FlagDefinitionCacheData,
   FlagDefinitionCacheInput,

From 763aab55ea97f32ba95db9af005bebf7939a14a7 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Mon, 26 Oct 2026 22:18:11 -0700
Subject: [PATCH 04/20] feat(node): add a self-contained capture lane (#5415)

* feat(node): serialize capture v1 events once for reuse

Add serializeV1Event, which builds an event's wire JSON once and records
its byte size and the size of its properties, and buildV1Body, which joins
already-serialized events into a request body. Nothing calls them yet; the
capture lane uses them to batch by bytes without serializing twice.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): add a self-contained capture lane

A lane owns one endpoint's in-memory queue, flush timer, flushAt trigger,
byte- and count-aware batching and in-flight send, and keeps events that
failed without an HTTP response for the next flush. It takes its sender,
config, callbacks, logger and clock from the caller.

The sender contract it needs is declared here as V1SendOptions (an abort
signal and keepUnsent); the capture sender implements it when the client
switches to lanes. Nothing uses the lane yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/__tests__/capture-lane/lane.spec.ts   | 444 ++++++++++++++++++
 .../__tests__/capture-v1/serialize.spec.ts    |  74 +++
 packages/node/src/capture-lane/lane.ts        | 349 ++++++++++++++
 packages/node/src/capture-lane/limits.ts      |  10 +
 packages/node/src/capture-v1/sender.ts        |  11 +
 packages/node/src/capture-v1/serialize.ts     |  45 ++
 6 files changed, 933 insertions(+)
 create mode 100644 packages/node/src/__tests__/capture-lane/lane.spec.ts
 create mode 100644 packages/node/src/__tests__/capture-v1/serialize.spec.ts
 create mode 100644 packages/node/src/capture-lane/lane.ts
 create mode 100644 packages/node/src/capture-lane/limits.ts
 create mode 100644 packages/node/src/capture-v1/serialize.ts

diff --git a/packages/node/src/__tests__/capture-lane/lane.spec.ts b/packages/node/src/__tests__/capture-lane/lane.spec.ts
new file mode 100644
index 0000000000..c3a129456c
--- /dev/null
+++ b/packages/node/src/__tests__/capture-lane/lane.spec.ts
@@ -0,0 +1,444 @@
+import type { Logger, PostHogEventProperties } from '@posthog/core'
+
+import { CaptureLane, type CaptureLaneConfig } from '@/capture-lane/lane'
+import { AI_MAX_PROPERTIES_BYTES } from '@/capture-lane/limits'
+import { CaptureError } from '@/capture-v1/errors'
+import type { V1SendOptions } from '@/capture-v1/sender'
+import { type SerializedV1Event, serializeV1Event } from '@/capture-v1/serialize'
+
+type SendBehavior = (events: SerializedV1Event[], options: V1SendOptions) => Promise<SerializedV1Event[]>
+
+const accept: SendBehavior = () => Promise.resolve([])
+const keepAll: SendBehavior = (events) => Promise.resolve(events)
+
+function msg(id: string | number, properties: PostHogEventProperties = {}): PostHogEventProperties {
+  return { event: 'e', distinct_id: 'd', uuid: `u${id}`, timestamp: '2024-01-01T00:00:00.000Z', properties }
+}
+
+/** A message whose serialized `properties` object is exactly `bytes` long. */
+function msgWithPropertiesBytes(id: string, bytes: number): PostHogEventProperties {
+  const overhead = serializeV1Event(msg(id, { pad: '' })).propertiesBytes
+  return msg(id, { pad: 'x'.repeat(bytes - overhead) })
+}
+
+function makeLogger(): Logger {
+  const logger: Logger = {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    critical: vi.fn(),
+    createLogger: () => logger,
+  }
+  return logger
+}
+
+function makeLane(config: Partial<CaptureLaneConfig> = {}, behavior: SendBehavior = accept) {
+  const batches: string[][] = []
+  const flushes: string[][] = []
+  const localDrops: CaptureError[] = []
+  const errors: unknown[] = []
+  const backgroundFlushes: Promise<void>[] = []
+  let currentBehavior = behavior
+  const send = vi.fn((events: SerializedV1Event[], options: V1SendOptions = {}) => {
+    batches.push(events.map((event) => event.uuid))
+    return currentBehavior(events, options)
+  })
+  const lane = new CaptureLane(
+    {
+      endpoint: '/i/v1/analytics/events',
+      flushAt: 100,
+      flushIntervalMs: 0,
+      maxBatchSize: 100,
+      maxQueueSize: 1000,
+      targetBatchBytes: 1024 * 1024,
+      maxEventBytes: 1024 * 1024,
+      maxEventBytesOf: 'event',
+      ...config,
+    },
+    {
+      sender: { send: send as any },
+      onLocalDrops: (error) => localDrops.push(error),
+      onError: (error) => errors.push(error),
+      onFlush: (messages) => flushes.push(messages.map((message) => String(message.uuid))),
+      onBackgroundFlush: (flush) => backgroundFlushes.push(flush),
+      logger: makeLogger(),
+    }
+  )
+  const setBehavior = (next: SendBehavior): void => {
+    currentBehavior = next
+  }
+  return { lane, send, batches, flushes, localDrops, errors, backgroundFlushes, setBehavior }
+}
+
+const ids = (count: number, from = 1): string[] => Array.from({ length: count }, (_, i) => `u${from + i}`)
+
+/** A flush cycle starts its first send a microtask after it is requested. */
+const settle = (): Promise<void> => vi.advanceTimersByTimeAsync(0)
+
+describe('CaptureLane', () => {
+  describe('batching', () => {
+    it('cuts batches at maxBatchSize and keeps queue order', async () => {
+      const { lane, batches } = makeLane({ maxBatchSize: 3 })
+      for (let i = 1; i <= 7; i++) {
+        lane.enqueue(msg(i))
+      }
+
+      await lane.flush()
+
+      expect(batches).toEqual([ids(3), ids(3, 4), ids(1, 7)])
+    })
+
+    it('starts a new batch with the event that would pass the byte target', async () => {
+      const eventBytes = serializeV1Event(msg(1)).bytes
+      // Room for two events, not three.
+      const { lane, batches } = makeLane({ targetBatchBytes: eventBytes * 3 - 1 })
+      for (let i = 1; i <= 5; i++) {
+        lane.enqueue(msg(i))
+      }
+
+      await lane.flush()
+
+      expect(batches).toEqual([ids(2), ids(2, 3), ids(1, 5)])
+    })
+
+    it('fills a batch to exactly the byte target', async () => {
+      const eventBytes = serializeV1Event(msg(1)).bytes
+      const { lane, batches } = makeLane({ targetBatchBytes: eventBytes * 2 })
+      for (let i = 1; i <= 4; i++) {
+        lane.enqueue(msg(i))
+      }
+
+      await lane.flush()
+
+      expect(batches).toEqual([ids(2), ids(2, 3)])
+    })
+
+    it('ships an event larger than the byte target on its own', async () => {
+      const { lane, batches } = makeLane({ targetBatchBytes: 500 })
+      lane.enqueue(msg(1))
+      lane.enqueue(msg(2, { pad: 'x'.repeat(600) }))
+      lane.enqueue(msg(3))
+      lane.enqueue(msg(4))
+
+      await lane.flush()
+
+      expect(batches).toEqual([['u1'], ['u2'], ['u3', 'u4']])
+    })
+  })
+
+  describe('per-event size limit', () => {
+    it('accepts AI properties of exactly the limit and drops one byte more, measuring properties only', async () => {
+      const { lane, batches, localDrops } = makeLane({
+        endpoint: '/i/v1/ai/events',
+        maxEventBytes: AI_MAX_PROPERTIES_BYTES,
+        maxEventBytesOf: 'properties',
+        targetBatchBytes: 5 * 1024 * 1024,
+      })
+      const atLimit = msgWithPropertiesBytes('at-limit', AI_MAX_PROPERTIES_BYTES)
+      const overLimit = msgWithPropertiesBytes('over-limit', AI_MAX_PROPERTIES_BYTES + 1)
+      // The whole event is larger than the limit, which must not matter.
+      expect(serializeV1Event(atLimit).bytes).toBeGreaterThan(AI_MAX_PROPERTIES_BYTES)
+
+      lane.enqueue(atLimit)
+      lane.enqueue(overLimit)
+      await lane.flush()
+
+      expect(batches).toEqual([['uat-limit']])
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0]).toBeInstanceOf(CaptureError)
+      expect(localDrops[0]).toMatchObject({
+        endpoint: '/i/v1/ai/events',
+        drops: [{ uuid: 'uover-limit', details: 'event too large' }],
+        message: `Dropped 1 event(s) for /i/v1/ai/events before sending: 1 with properties larger than ${AI_MAX_PROPERTIES_BYTES} bytes`,
+      })
+    })
+
+    it('measures the whole serialized event when configured to', async () => {
+      const limit = serializeV1Event(msg('fits', { pad: 'x'.repeat(100) })).bytes
+      const { lane, batches, localDrops } = makeLane({ maxEventBytes: limit, maxEventBytesOf: 'event' })
+
+      lane.enqueue(msg('fits', { pad: 'x'.repeat(100) }))
+      lane.enqueue(msg('over', { pad: 'x'.repeat(101) }))
+      await lane.flush()
+
+      expect(batches).toEqual([['ufits']])
+      expect(localDrops.map((error) => error.drops)).toEqual([[{ uuid: 'uover', details: 'event too large' }]])
+    })
+
+    it('drops an oversized immediate event and reports it without sending', async () => {
+      const { lane, send, localDrops } = makeLane({ maxEventBytes: 100 })
+
+      await lane.sendImmediate(msg(1, { pad: 'x'.repeat(200) }))
+
+      expect(send).not.toHaveBeenCalled()
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0].drops).toEqual([{ uuid: 'u1', details: 'event too large' }])
+    })
+
+    it('sends an immediate event straight through the sender without queueing it', async () => {
+      const { lane, send, batches } = makeLane()
+
+      await lane.sendImmediate(msg(1))
+
+      expect(batches).toEqual([['u1']])
+      expect(send.mock.calls[0][1]).toEqual({ signal: expect.any(AbortSignal) })
+      expect(lane.length).toBe(0)
+    })
+  })
+
+  describe('queue cap', () => {
+    it('drops the oldest events and reports them once per flush cycle', async () => {
+      const { lane, batches, localDrops } = makeLane({ maxQueueSize: 3 })
+      for (let i = 1; i <= 6; i++) {
+        lane.enqueue(msg(i))
+      }
+
+      await lane.flush()
+
+      expect(batches).toEqual([['u4', 'u5', 'u6']])
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0].drops.map((drop) => drop.uuid)).toEqual(['u1', 'u2', 'u3'])
+      expect(localDrops[0].message).toBe(
+        'Dropped 3 event(s) for /i/v1/analytics/events before sending: 3 because the queue was full (3 events)'
+      )
+
+      await lane.flush()
+      expect(localDrops).toHaveLength(1)
+    })
+
+    it('lists at most 100 uuids per report but counts every drop', async () => {
+      const { lane, localDrops } = makeLane({ maxQueueSize: 1 })
+      for (let i = 0; i <= 150; i++) {
+        lane.enqueue(msg(i))
+      }
+
+      await lane.flush()
+
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0].drops).toHaveLength(100)
+      expect(localDrops[0].message).toContain('Dropped 150 event(s)')
+    })
+  })
+
+  describe('flush triggers', () => {
+    it('flushes when the queue reaches flushAt and hands the flush to onBackgroundFlush', async () => {
+      const { lane, batches, backgroundFlushes } = makeLane({ flushAt: 2 })
+
+      lane.enqueue(msg(1))
+      expect(batches).toEqual([])
+      lane.enqueue(msg(2))
+      await Promise.all(backgroundFlushes)
+
+      expect(batches).toEqual([['u1', 'u2']])
+      expect(backgroundFlushes).toHaveLength(1)
+    })
+
+    it('lets events enqueued in the same burst as the flushAt trigger join its batch', async () => {
+      const { lane, batches, backgroundFlushes } = makeLane({ flushAt: 2 })
+
+      for (let i = 1; i <= 5; i++) {
+        lane.enqueue(msg(i))
+      }
+      await Promise.all(backgroundFlushes)
+
+      expect(batches).toEqual([ids(5)])
+    })
+
+    it('flushes once flushIntervalMs passes after the first queued event', async () => {
+      const { lane, batches, backgroundFlushes } = makeLane({ flushIntervalMs: 1000 })
+
+      lane.enqueue(msg(1))
+      await vi.advanceTimersByTimeAsync(500)
+      lane.enqueue(msg(2))
+      await vi.advanceTimersByTimeAsync(499)
+      expect(batches).toEqual([])
+
+      await vi.advanceTimersByTimeAsync(1)
+      await Promise.all(backgroundFlushes)
+      expect(batches).toEqual([['u1', 'u2']])
+      expect(vi.getTimerCount()).toBe(0)
+    })
+
+    it('arms no timer when flushIntervalMs is 0', () => {
+      const { lane } = makeLane({ flushIntervalMs: 0 })
+
+      lane.enqueue(msg(1))
+
+      expect(vi.getTimerCount()).toBe(0)
+    })
+
+    it('arms the timer for an oversized event so its drop report goes out', async () => {
+      const { lane, localDrops } = makeLane({ flushIntervalMs: 1000, maxEventBytes: 100 })
+
+      lane.enqueue(msg(1, { pad: 'x'.repeat(200) }))
+      await vi.advanceTimersByTimeAsync(1000)
+
+      expect(localDrops).toHaveLength(1)
+    })
+
+    it('coalesces flush requests made while a flush is in flight into one follow-up', async () => {
+      let release!: () => void
+      const { lane, batches, setBehavior } = makeLane()
+      setBehavior(() => new Promise((resolve) => (release = () => resolve([]))))
+      lane.enqueue(msg(1))
+      const first = lane.flush()
+      await settle()
+      lane.enqueue(msg(2))
+      const second = lane.flush()
+      const third = lane.flush()
+
+      expect(third).toBe(second)
+      setBehavior(accept)
+      release()
+      await Promise.all([first, second])
+
+      expect(batches).toEqual([['u1'], ['u2']])
+    })
+  })
+
+  describe('network failure requeue', () => {
+    it('puts unsent events back at the head of the queue for the next flush, without reporting', async () => {
+      const { lane, batches, localDrops, errors, flushes, setBehavior } = makeLane({ maxBatchSize: 2 })
+      setBehavior(keepAll)
+      lane.enqueue(msg(1))
+      lane.enqueue(msg(2))
+      lane.enqueue(msg(3))
+
+      await lane.flush()
+      // The first failed batch stops the cycle, so u3 is not tried against a down network.
+      expect(batches).toEqual([['u1', 'u2']])
+      expect(lane.length).toBe(3)
+
+      lane.enqueue(msg(4))
+      setBehavior(accept)
+      await lane.flush()
+
+      expect(batches.slice(1)).toEqual([
+        ['u1', 'u2'],
+        ['u3', 'u4'],
+      ])
+      expect(flushes).toEqual([['u1', 'u2', 'u3', 'u4']])
+      expect(localDrops).toEqual([])
+      expect(errors).toEqual([])
+    })
+
+    it('requeues only the unsent events of a batch and reports the rest as flushed', async () => {
+      const { lane, flushes, setBehavior, batches } = makeLane()
+      setBehavior((events) => Promise.resolve(events.filter((event) => event.uuid === 'u2')))
+      lane.enqueue(msg(1))
+      lane.enqueue(msg(2))
+
+      await lane.flush()
+      setBehavior(accept)
+      await lane.flush()
+
+      expect(batches).toEqual([['u1', 'u2'], ['u2']])
+      expect(flushes).toEqual([['u1'], ['u2']])
+    })
+
+    it('keeps the queue cap when requeueing, dropping the oldest first', async () => {
+      let release!: () => void
+      const { lane, localDrops, setBehavior, batches } = makeLane({ maxQueueSize: 3 })
+      setBehavior((events) => new Promise((resolve) => (release = () => resolve(events))))
+      lane.enqueue(msg(1))
+      lane.enqueue(msg(2))
+      const flush = lane.flush()
+      await settle()
+      for (let i = 3; i <= 5; i++) {
+        lane.enqueue(msg(i))
+      }
+      release()
+      await flush
+
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0].drops.map((drop) => drop.uuid)).toEqual(['u1', 'u2'])
+
+      setBehavior(accept)
+      await lane.flush()
+      expect(batches.at(-1)).toEqual(['u3', 'u4', 'u5'])
+    })
+
+    it('reports an unexpected sender failure and drops that batch instead of requeueing it', async () => {
+      const { lane, errors, flushes, setBehavior } = makeLane()
+      setBehavior(() => Promise.reject(new Error('bug')))
+      lane.enqueue(msg(1))
+
+      await expect(lane.flush()).resolves.toBeUndefined()
+
+      expect(errors).toEqual([new Error('bug')])
+      expect(flushes).toEqual([])
+      expect(lane.length).toBe(0)
+    })
+  })
+
+  describe('shutdown', () => {
+    const abortable: SendBehavior = (events, { signal }) =>
+      new Promise((resolve) => signal?.addEventListener('abort', () => resolve(events), { once: true }))
+
+    it('aborts sends at the deadline and reports what is still queued', async () => {
+      const { lane, send, localDrops } = makeLane({}, abortable)
+      lane.enqueue(msg(1))
+      lane.enqueue(msg(2))
+
+      let drained = false
+      const drain = lane.drain(Date.now() + 1000).then(() => (drained = true))
+      await vi.advanceTimersByTimeAsync(999)
+      expect(drained).toBe(false)
+      await vi.advanceTimersByTimeAsync(1)
+      await drain
+      expect(send.mock.calls[0][1].signal.aborted).toBe(true)
+
+      lane.finishShutdown()
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0]).toMatchObject({ retryExhausted: ['u1', 'u2'], drops: [] })
+      expect(localDrops[0].message).toBe(
+        '2 event(s) for /i/v1/analytics/events were still queued when shutdown ended and were not sent'
+      )
+      expect(lane.length).toBe(0)
+    })
+
+    it('drains events enqueued while an earlier flush was in flight', async () => {
+      let release!: () => void
+      const { lane, batches, setBehavior } = makeLane()
+      setBehavior(() => new Promise((resolve) => (release = () => resolve([]))))
+      lane.enqueue(msg(1))
+      void lane.flush()
+      await settle()
+      lane.enqueue(msg(2))
+
+      const drain = lane.drain(Date.now() + 1000)
+      setBehavior(accept)
+      release()
+      await drain
+
+      expect(batches).toEqual([['u1'], ['u2']])
+    })
+
+    it('stops draining when a cycle sends nothing', async () => {
+      const { lane, send } = makeLane({}, keepAll)
+      lane.enqueue(msg(1))
+
+      await lane.drain(Date.now() + 1000)
+
+      expect(send).toHaveBeenCalledTimes(1)
+      expect(lane.length).toBe(1)
+    })
+
+    it('sends again after shutdown finishes', async () => {
+      const { lane, batches, setBehavior } = makeLane({}, abortable)
+      lane.enqueue(msg(1))
+      const drain = lane.drain(Date.now() + 10)
+      await vi.advanceTimersByTimeAsync(10)
+      await drain
+      lane.finishShutdown()
+
+      setBehavior((_events, { signal }) => Promise.resolve(signal?.aborted ? _events : []))
+      lane.enqueue(msg(2))
+      await lane.flush()
+
+      expect(batches.at(-1)).toEqual(['u2'])
+      expect(lane.length).toBe(0)
+    })
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/serialize.spec.ts b/packages/node/src/__tests__/capture-v1/serialize.spec.ts
new file mode 100644
index 0000000000..d06e5610e7
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/serialize.spec.ts
@@ -0,0 +1,74 @@
+import { type PostHogEventProperties, safeJsonStringify } from '@posthog/core'
+
+import { buildV1Body, serializeV1Event } from '@/capture-v1/serialize'
+import { buildV1Event } from '@/capture-v1/transform'
+
+const utf8Bytes = (value: string): number => Buffer.byteLength(value, 'utf8')
+
+function message(overrides: PostHogEventProperties = {}): PostHogEventProperties {
+  return {
+    event: 'test-event',
+    distinct_id: 'user-123',
+    uuid: '0189dcd5-5311-7d40-8db0-9496a2eef37b',
+    timestamp: '2024-01-15T10:30:00.000Z',
+    properties: {},
+    ...overrides,
+  }
+}
+
+const MESSAGES: [string, PostHogEventProperties][] = [
+  ['empty properties', message()],
+  [
+    'promoted fields and options',
+    message({
+      $set: { plan: 'pro' },
+      properties: { $session_id: 's1', $window_id: 'w1', $cookieless_mode: true, nested: { a: [1, 2] } },
+    }),
+  ],
+  ['multibyte characters', message({ event: 'café ☕', properties: { emoji: '🦔🦔', euro: '€', lone: '\ud800' } })],
+]
+
+describe('serializeV1Event', () => {
+  it.each(MESSAGES)('produces the JSON of the whole wire event (%s)', (_name, input) => {
+    expect(serializeV1Event(input).json).toBe(safeJsonStringify(buildV1Event(input)))
+  })
+
+  it.each(MESSAGES)('measures UTF-8 bytes of the event and of its properties (%s)', (_name, input) => {
+    const serialized = serializeV1Event(input)
+
+    expect(serialized.uuid).toBe(input.uuid)
+    expect(serialized.bytes).toBe(utf8Bytes(serialized.json))
+    expect(serialized.propertiesBytes).toBe(utf8Bytes(safeJsonStringify(buildV1Event(input).properties)))
+  })
+
+  it('counts bytes, not UTF-16 code units', () => {
+    const serialized = serializeV1Event(message({ properties: { emoji: '🦔'.repeat(10) } }))
+
+    expect(serialized.bytes).toBeGreaterThan(serialized.json.length)
+  })
+})
+
+describe('buildV1Body', () => {
+  const events = MESSAGES.map(([, input]) => serializeV1Event(input))
+  const wireEvents = MESSAGES.map(([, input]) => buildV1Event(input))
+
+  it('matches the serialized envelope byte for byte and omits historical_migration by default', () => {
+    const body = buildV1Body(events, { createdAt: '2024-01-15T10:30:01.000Z', historicalMigration: false })
+
+    expect(body).toBe(safeJsonStringify({ created_at: '2024-01-15T10:30:01.000Z', batch: wireEvents }))
+    expect(JSON.parse(body)).not.toHaveProperty('historical_migration')
+  })
+
+  it('includes historical_migration only when true', () => {
+    const body = buildV1Body(events, { createdAt: 'now', historicalMigration: true })
+
+    expect(body).toBe(safeJsonStringify({ created_at: 'now', historical_migration: true, batch: wireEvents }))
+  })
+
+  it('produces an empty batch array for no events', () => {
+    expect(JSON.parse(buildV1Body([], { createdAt: 'now', historicalMigration: false }))).toEqual({
+      created_at: 'now',
+      batch: [],
+    })
+  })
+})
diff --git a/packages/node/src/capture-lane/lane.ts b/packages/node/src/capture-lane/lane.ts
new file mode 100644
index 0000000000..adbf1be816
--- /dev/null
+++ b/packages/node/src/capture-lane/lane.ts
@@ -0,0 +1,349 @@
+import { type Logger, type PostHogEventProperties, safeSetTimeout } from '@posthog/core'
+
+import { CaptureError, type CaptureDroppedEvent } from '../capture-v1/errors'
+import type { V1SendOptions } from '../capture-v1/sender'
+import { type SerializedV1Event, serializeV1Event } from '../capture-v1/serialize'
+import type { CaptureEndpoint } from '../capture-v1/types'
+
+/** Upper bound on the uuids one local-drop report lists; the message still carries the full count. */
+const MAX_REPORTED_LOCAL_DROPS = 100
+
+/** What a lane needs from its sender. `V1CaptureSender` implements it. */
+export interface CaptureLaneSender {
+  send<T extends SerializedV1Event>(events: T[], options?: V1SendOptions): Promise<T[]>
+}
+
+export interface CaptureLaneConfig {
+  endpoint: CaptureEndpoint
+  /** Queue length that starts a flush. */
+  flushAt: number
+  /** Delay before a flush of queued events; 0 turns the timer off. */
+  flushIntervalMs: number
+  maxBatchSize: number
+  /** When the queue holds this many events, a new event drops the oldest. */
+  maxQueueSize: number
+  /** A batch stops before an event that would take its serialized bytes past this. */
+  targetBatchBytes: number
+  /** Events larger than this are dropped before sending. */
+  maxEventBytes: number
+  /** Whether `maxEventBytes` applies to the whole serialized event or to its `properties` only. */
+  maxEventBytesOf: 'event' | 'properties'
+}
+
+export interface CaptureLaneHooks {
+  sender: CaptureLaneSender
+  /** Events this lane dropped without sending, at most one report per flush cycle. */
+  onLocalDrops: (error: CaptureError) => void
+  /** Failures the sender did not handle itself. */
+  onError: (error: unknown) => void
+  /** The messages one flush cycle sent. */
+  onFlush: (messages: PostHogEventProperties[]) => void
+  /** Each flush the lane starts on its own, from its timer or `flushAt`. */
+  onBackgroundFlush?: (flush: Promise<void>) => void
+  logger: Logger
+  now?: () => number
+}
+
+interface QueuedEvent extends SerializedV1Event {
+  message: PostHogEventProperties
+}
+
+interface LocalDropTally {
+  queueFull: number
+  tooLarge: number
+  sample: CaptureDroppedEvent[]
+}
+
+const emptyTally = (): LocalDropTally => ({ queueFull: 0, tooLarge: 0, sample: [] })
+
+/**
+ * One capture endpoint's in-memory queue, flush timer, `flushAt` trigger, batching and
+ * in-flight send. Lanes share nothing, so a slow or failing lane never delays, drops
+ * or resends another lane's events.
+ *
+ * Every event is serialized once, on enqueue. Batches are cut by count and by
+ * serialized bytes, keeping queue order. An event whose last attempt got no HTTP
+ * response goes back to the head of the queue for the next flush; every other
+ * failure is final and reported by the sender.
+ */
+export class CaptureLane {
+  private readonly config: CaptureLaneConfig
+  private readonly hooks: CaptureLaneHooks
+  private readonly now: () => number
+  private queue: QueuedEvent[] = []
+  private flushTimer?: ReturnType<typeof safeSetTimeout>
+  private activeFlush: Promise<void> | null = null
+  // A flush requested while another is in flight; later requests share it.
+  private queuedFlush: Promise<void> | null = null
+  private abortController = new AbortController()
+  private abortTimer?: ReturnType<typeof safeSetTimeout>
+  private localDrops = emptyTally()
+  // Events that reached a final outcome, so a drain can tell whether a cycle moved anything.
+  private settledCount = 0
+
+  constructor(config: CaptureLaneConfig, hooks: CaptureLaneHooks) {
+    this.config = config
+    this.hooks = hooks
+    this.now = hooks.now ?? Date.now
+  }
+
+  get length(): number {
+    return this.queue.length
+  }
+
+  enqueue(message: PostHogEventProperties): void {
+    const event: QueuedEvent = { ...serializeV1Event(message), message }
+    if (this.isTooLarge(event)) {
+      this.recordLocalDrop(event, 'tooLarge')
+      // Nothing may follow to flush, and the flush cycle is what reports the drop.
+      this.armFlushTimer()
+      return
+    }
+    if (this.queue.length >= this.config.maxQueueSize) {
+      this.recordLocalDrop(this.queue.shift()!, 'queueFull')
+    }
+    this.queue.push(event)
+
+    if (this.queue.length >= this.config.flushAt) {
+      this.flushInBackground()
+    } else {
+      this.armFlushTimer()
+    }
+  }
+
+  /** Sends one event now, without queueing. Delivery failures are reported, not thrown. */
+  async sendImmediate(message: PostHogEventProperties): Promise<void> {
+    const event = serializeV1Event(message)
+    if (this.isTooLarge(event)) {
+      const tally = emptyTally()
+      this.addToTally(tally, event, 'tooLarge')
+      this.reportTally(tally)
+      return
+    }
+    await this.hooks.sender.send([event], { signal: this.abortController.signal })
+  }
+
+  /** Sends everything queued when the returned flush starts. Never rejects. */
+  flush(): Promise<void> {
+    if (this.queuedFlush) {
+      return this.queuedFlush
+    }
+    if (!this.activeFlush) {
+      return this.startFlush()
+    }
+    const queued = this.activeFlush.then(() => {
+      this.queuedFlush = null
+      return this.startFlush()
+    })
+    this.queuedFlush = queued
+    return queued
+  }
+
+  /**
+   * Flushes until the queue is empty, a cycle settles nothing (every send was requeued),
+   * or `deadlineMs` passes. At the deadline, in-flight and later sends are aborted.
+   */
+  async drain(deadlineMs: number): Promise<void> {
+    this.abortAt(deadlineMs)
+    let settledBefore: number
+    do {
+      settledBefore = this.settledCount
+      await this.flush()
+    } while (this.queue.length > 0 && this.settledCount !== settledBefore && !this.abortController.signal.aborted)
+  }
+
+  /**
+   * Ends a shutdown: reports and discards what is still queued, and re-arms the lane so
+   * calls made after shutdown still send.
+   */
+  finishShutdown(): void {
+    clearTimeout(this.abortTimer)
+    this.abortTimer = undefined
+    this.clearFlushTimer()
+    const leftovers = this.queue.splice(0)
+    if (leftovers.length > 0) {
+      const error = new CaptureError({
+        endpoint: this.config.endpoint,
+        requestId: '',
+        drops: [],
+        retryExhausted: leftovers.map((event) => event.uuid),
+      })
+      error.message = `${leftovers.length} event(s) for ${this.config.endpoint} were still queued when shutdown ended and were not sent`
+      this.safely(() => this.hooks.onLocalDrops(error))
+    }
+    this.reportLocalDrops()
+    if (this.abortController.signal.aborted) {
+      this.abortController = new AbortController()
+    }
+  }
+
+  private startFlush(): Promise<void> {
+    const flush = this.runFlushCycle().finally(() => {
+      if (this.activeFlush === flush) {
+        this.activeFlush = null
+      }
+    })
+    this.activeFlush = flush
+    return flush
+  }
+
+  private flushInBackground(): void {
+    if (this.queuedFlush) {
+      return
+    }
+    const flush = this.flush()
+    this.safely(() => this.hooks.onBackgroundFlush?.(flush))
+  }
+
+  private async runFlushCycle(): Promise<void> {
+    this.clearFlushTimer()
+    // Lets events enqueued in the same burst join this cycle's first batch.
+    await Promise.resolve()
+    // Events enqueued during this cycle wait for the next one, so a steady stream cannot hold a flush open.
+    const budget = this.queue.length
+    const sent: PostHogEventProperties[] = []
+    let taken = 0
+    try {
+      while (taken < budget && this.queue.length > 0) {
+        const batch = this.takeBatch()
+        taken += batch.length
+        let unsent: QueuedEvent[]
+        try {
+          unsent = await this.hooks.sender.send(batch, { signal: this.abortController.signal, keepUnsent: true })
+        } catch (error) {
+          // An unexpected sender failure is final for the batch, like any other non-network failure.
+          this.settledCount += batch.length
+          this.safely(() => this.hooks.onError(error))
+          continue
+        }
+        this.settledCount += batch.length - unsent.length
+        const requeued = new Set(unsent)
+        for (const event of batch) {
+          if (!requeued.has(event)) {
+            sent.push(event.message)
+          }
+        }
+        if (unsent.length > 0) {
+          this.requeue(unsent)
+          // The network is likely down, so the rest of the queue waits for the next flush too.
+          break
+        }
+      }
+    } catch (error) {
+      this.safely(() => this.hooks.onError(error))
+    } finally {
+      if (sent.length > 0) {
+        this.safely(() => this.hooks.onFlush(sent))
+      }
+      this.reportLocalDrops()
+      if (this.queue.length > 0) {
+        this.armFlushTimer()
+      }
+    }
+  }
+
+  private takeBatch(): QueuedEvent[] {
+    let count = 0
+    let bytes = 0
+    while (count < this.queue.length && count < this.config.maxBatchSize) {
+      const next = this.queue[count]
+      // Check before appending: the event that would overflow starts the next batch, and an oversized one ships alone.
+      if (count > 0 && bytes + next.bytes > this.config.targetBatchBytes) {
+        break
+      }
+      bytes += next.bytes
+      count++
+    }
+    return this.queue.splice(0, count)
+  }
+
+  private requeue(events: QueuedEvent[]): void {
+    this.queue.unshift(...events)
+    while (this.queue.length > this.config.maxQueueSize) {
+      this.recordLocalDrop(this.queue.shift()!, 'queueFull')
+    }
+    this.hooks.logger.debug(
+      `Kept ${events.length} event(s) for ${this.config.endpoint} after a network failure; the next flush sends them`
+    )
+  }
+
+  private isTooLarge(event: SerializedV1Event): boolean {
+    const bytes = this.config.maxEventBytesOf === 'properties' ? event.propertiesBytes : event.bytes
+    return bytes > this.config.maxEventBytes
+  }
+
+  private recordLocalDrop(event: SerializedV1Event, reason: 'queueFull' | 'tooLarge'): void {
+    this.addToTally(this.localDrops, event, reason)
+  }
+
+  private addToTally(tally: LocalDropTally, event: SerializedV1Event, reason: 'queueFull' | 'tooLarge'): void {
+    tally[reason]++
+    if (tally.sample.length < MAX_REPORTED_LOCAL_DROPS) {
+      tally.sample.push({ uuid: event.uuid, details: reason === 'queueFull' ? 'queue full' : 'event too large' })
+    }
+  }
+
+  private reportLocalDrops(): void {
+    const tally = this.localDrops
+    this.localDrops = emptyTally()
+    this.reportTally(tally)
+  }
+
+  private reportTally(tally: LocalDropTally): void {
+    const total = tally.queueFull + tally.tooLarge
+    if (total === 0) {
+      return
+    }
+    const reasons: string[] = []
+    if (tally.queueFull > 0) {
+      reasons.push(`${tally.queueFull} because the queue was full (${this.config.maxQueueSize} events)`)
+    }
+    if (tally.tooLarge > 0) {
+      const measured = this.config.maxEventBytesOf === 'properties' ? 'properties larger' : 'larger'
+      reasons.push(`${tally.tooLarge} with ${measured} than ${this.config.maxEventBytes} bytes`)
+    }
+    const error = new CaptureError({
+      endpoint: this.config.endpoint,
+      requestId: '',
+      drops: tally.sample,
+      retryExhausted: [],
+    })
+    error.message = `Dropped ${total} event(s) for ${this.config.endpoint} before sending: ${reasons.join(', ')}`
+    this.safely(() => this.hooks.onLocalDrops(error))
+  }
+
+  private armFlushTimer(): void {
+    if (this.flushTimer || !this.config.flushIntervalMs) {
+      return
+    }
+    this.flushTimer = safeSetTimeout(() => {
+      this.flushTimer = undefined
+      this.flushInBackground()
+    }, this.config.flushIntervalMs)
+  }
+
+  private clearFlushTimer(): void {
+    clearTimeout(this.flushTimer)
+    this.flushTimer = undefined
+  }
+
+  private abortAt(deadlineMs: number): void {
+    clearTimeout(this.abortTimer)
+    const abort = (): void => this.abortController.abort(new Error('PostHog shutdown deadline reached'))
+    const delayMs = deadlineMs - this.now()
+    if (delayMs <= 0) {
+      abort()
+      return
+    }
+    this.abortTimer = safeSetTimeout(abort, delayMs)
+  }
+
+  // Hooks run user listeners, which must not break the lane's own bookkeeping.
+  private safely(fn: () => void): void {
+    try {
+      fn()
+    } catch (error) {
+      this.hooks.logger.error('Capture lane hook failed:', error)
+    }
+  }
+}
diff --git a/packages/node/src/capture-lane/limits.ts b/packages/node/src/capture-lane/limits.ts
new file mode 100644
index 0000000000..c9408b71c2
--- /dev/null
+++ b/packages/node/src/capture-lane/limits.ts
@@ -0,0 +1,10 @@
+/** Serialized event bytes a lane aims to fit in one request. */
+export const CAPTURE_BATCH_TARGET_BYTES = 5 * 1024 * 1024
+
+/** Capture's request body limit: a larger analytics event can never be accepted. */
+export const ANALYTICS_MAX_EVENT_BYTES = 10 * 1024 * 1024
+
+/** The AI endpoint rejects an event whose serialized `properties` are larger than this. */
+export const AI_MAX_PROPERTIES_BYTES = 8 * 1024 * 1024
+
+export const AI_MAX_QUEUE_SIZE = 1000
diff --git a/packages/node/src/capture-v1/sender.ts b/packages/node/src/capture-v1/sender.ts
index 094ad1a699..0ec5611271 100644
--- a/packages/node/src/capture-v1/sender.ts
+++ b/packages/node/src/capture-v1/sender.ts
@@ -51,6 +51,17 @@ export interface V1CaptureSenderHooks {
   compress?: (payload: string, isDebug?: boolean) => Promise<Blob | PostHogFetchBodyBytes | null>
 }
 
+export interface V1SendOptions {
+  /** Aborting stops the current attempt and every later one; the pending events come back as unsent. */
+  signal?: AbortSignal
+  /**
+   * When true, events whose last attempt got no HTTP response (or were cut off by `signal`) are
+   * returned to the caller unreported, so it can queue them again. When false they are reported
+   * as undelivered.
+   */
+  keepUnsent?: boolean
+}
+
 interface V1CaptureAttempt {
   response: PostHogFetchResponse
   signal: AbortSignal
diff --git a/packages/node/src/capture-v1/serialize.ts b/packages/node/src/capture-v1/serialize.ts
new file mode 100644
index 0000000000..1ac2fae6ff
--- /dev/null
+++ b/packages/node/src/capture-v1/serialize.ts
@@ -0,0 +1,45 @@
+import { type PostHogEventProperties, safeJsonStringify } from '@posthog/core'
+
+import { buildV1Event } from './transform'
+
+const encoder = new TextEncoder()
+
+// `buildV1Event` puts `properties` last, so the event JSON is the rest of the event with this key and the properties appended.
+const PROPERTIES_KEY = ',"properties":'
+const PROPERTIES_KEY_BYTES = encoder.encode(PROPERTIES_KEY).length
+
+/** One wire event, serialized once and reused verbatim in every request body that carries it. */
+export interface SerializedV1Event {
+  uuid: string
+  json: string
+  /** UTF-8 size of `json`. */
+  bytes: number
+  /** UTF-8 size of the serialized `properties` object alone, which is what the AI endpoint limits. */
+  propertiesBytes: number
+}
+
+export function serializeV1Event(message: PostHogEventProperties): SerializedV1Event {
+  const { properties, ...rest } = buildV1Event(message)
+  const restJson = safeJsonStringify(rest)
+  const propertiesJson = safeJsonStringify(properties)
+  const propertiesBytes = encoder.encode(propertiesJson).length
+  return {
+    uuid: rest.uuid,
+    json: `${restJson.slice(0, -1)}${PROPERTIES_KEY}${propertiesJson}}`,
+    // The closing brace moves from the end of `restJson` to the end of the event, so it is counted once.
+    bytes: encoder.encode(restJson).length + PROPERTIES_KEY_BYTES + propertiesBytes,
+    propertiesBytes,
+  }
+}
+
+/**
+ * The Capture V1 batch envelope, built from already-serialized events. Unlike v0 there is no
+ * `api_key` (Bearer auth) and no `sent_at`. `historical_migration` is omitted when false.
+ */
+export function buildV1Body(
+  events: readonly { json: string }[],
+  { createdAt, historicalMigration }: { createdAt: string; historicalMigration: boolean }
+): string {
+  const migration = historicalMigration ? ',"historical_migration":true' : ''
+  return `{"created_at":${JSON.stringify(createdAt)}${migration},"batch":[${events.map((event) => event.json).join(',')}]}`
+}

From 86fd5a19797f967c26542037e4cd7c1f8b73aabc Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Tue, 27 Oct 2026 13:00:01 -0700
Subject: [PATCH 05/20] fix(nextjs): restore accurate integration fixtures and
 cooldown compliance (#5423) (#5451)

Generated-By: PostHog Desktop
Task-Id: eac276ac-44b1-4fc2-9666-d5463c7b28c4


(cherry picked from commit bd41fe41901be3251f033e9853d01a5cc2ad8f7b)

Co-authored-by: posthog[bot] <206114724+posthog[bot]@users.noreply.github.com>
---
 .../nextjs-config/tests/integration/README.md |   6 +-
 .../{next14 => next15-react18}/package.json   |   2 +-
 .../integration/fixtures/next16/package.json  |   2 +-
 .../tests/integration/fixtures/pnpm-lock.yaml | 184 ++++++++++++++++--
 .../integration/fixtures/pnpm-workspace.yaml  |   5 +-
 .../nextjs-config/tests/integration/run.mjs   |   8 +-
 6 files changed, 179 insertions(+), 28 deletions(-)
 rename packages/nextjs-config/tests/integration/fixtures/{next14 => next15-react18}/package.json (71%)

diff --git a/packages/nextjs-config/tests/integration/README.md b/packages/nextjs-config/tests/integration/README.md
index 7d3fea9382..3560a8dee9 100644
--- a/packages/nextjs-config/tests/integration/README.md
+++ b/packages/nextjs-config/tests/integration/README.md
@@ -1,6 +1,6 @@
 # Next.js release and cache regressions
 
-These tests run real Next.js 14, 15 and 16 webpack builds and Chromium. They are separate from unit/built-output tests because they install framework dependencies and need a browser. No PostHog credentials are needed.
+These tests run real Next.js 15 and 16 webpack builds and Chromium. Next.js 15 is tested with both React 18 and React 19. Next.js 14 is not run because current security advisories have no patched 14.x release. These tests are separate from unit/built-output tests because they install framework dependencies and need a browser. No PostHog credentials are needed.
 
 From the repository root:
 
@@ -15,12 +15,12 @@ The root command builds the current browser SDK, Node SDK and Next.js integratio
 
 - The framework/third-party workspace in `fixtures/` has pinned versions, a committed lockfile and the repository's seven-day dependency cooldown. It is copied into a fresh temporary directory and installed with `--frozen-lockfile --ignore-scripts`. The CLI pin matches the shipped minimum, with an exact-version cooldown exception for `@posthog/cli@0.18.11`; the downstream PostHog workspace already permits `@posthog/*` releases.
 - Current PostHog packages and their workspace runtime dependencies are packed and unpacked into each consumer's `node_modules`. They are not linked back to the checkout. Framework peers and third-party dependencies resolve from the isolated fixture install. New external SDK dependencies require updating the fixture pins/lockfile.
-- All three framework versions use webpack build workers. Each app is built twice with different mock release IDs and a fixed Next build ID. The second build starts without the first build's output or `.next/cache`.
+- All three fixtures use webpack build workers. Each app is built twice with different mock release IDs and a fixed Next build ID. The second build starts without the first build's output or `.next/cache`.
 - Shared immutable JavaScript URLs must retain identical bytes; the runtime URL must change. Chromium serves shared assets from the previous build while loading the new deployment and exercising a lazy chunk.
 - Browser captures cover the minimum supported `posthog-js@1.438.5` CDN bundle, the current CDN bundle, and the current bundled SDK. CDN scripts are served locally, outside Next's compilation. Deleting the release global is a negative control for the CDN SDKs.
 - A Pages Router API actually externalizes the current `posthog-node` and captures an exception with runtime `POSTHOG_RELEASE_ID` unset. Both deployments must report their correct release.
 - The mock CLI rejects post-build `process` calls, checks every uploaded JS/map chunk ID, and records asset hashes. The harness checks files remain unchanged after upload and uploaded maps are deleted. A mock CLI error fails the test even though the plugin itself is fail-soft.
-- Next 15.5 covers the intermediate bundler-selection path: the production compiler hook is available (since 15.4.1), but webpack remains the default. Like Next 14, it builds without `--webpack`; Next 16 explicitly selects webpack. Webpack workers must not install the Turbopack upload hook.
+- Next 15.5 covers the intermediate bundler-selection path: the production compiler hook is available (since 15.4.1), but webpack remains the default. Both React variants build without `--webpack`; Next 16 explicitly selects webpack. Webpack workers must not install the Turbopack upload hook.
 - Next 16 also runs `next dev --webpack`. Actual dev/build workers must install the plugin without inherited CLI flags, artificial `WEBPACK`/`TURBOPACK` overrides, or the Turbopack upload hook.
 - Browser bot filtering is disabled for controlled Playwright captures. Events are inspected in `before_send` and dropped. Browser analytics requests are intercepted; unexpected external requests fail the test. Node analytics transport throws if called.
 
diff --git a/packages/nextjs-config/tests/integration/fixtures/next14/package.json b/packages/nextjs-config/tests/integration/fixtures/next15-react18/package.json
similarity index 71%
rename from packages/nextjs-config/tests/integration/fixtures/next14/package.json
rename to packages/nextjs-config/tests/integration/fixtures/next15-react18/package.json
index 31bbae41ac..ba026126a0 100644
--- a/packages/nextjs-config/tests/integration/fixtures/next14/package.json
+++ b/packages/nextjs-config/tests/integration/fixtures/next15-react18/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "posthog-next14-integration",
+  "name": "posthog-next15-react18-integration",
   "private": true,
   "dependencies": {
     "next": "15.5.28",
diff --git a/packages/nextjs-config/tests/integration/fixtures/next16/package.json b/packages/nextjs-config/tests/integration/fixtures/next16/package.json
index 253bdf9473..ceb7d40086 100644
--- a/packages/nextjs-config/tests/integration/fixtures/next16/package.json
+++ b/packages/nextjs-config/tests/integration/fixtures/next16/package.json
@@ -2,7 +2,7 @@
   "name": "posthog-next16-integration",
   "private": true,
   "dependencies": {
-    "next": "15.5.28",
+    "next": "16.4.2",
     "react": "19.2.8",
     "react-dom": "19.2.8"
   }
diff --git a/packages/nextjs-config/tests/integration/fixtures/pnpm-lock.yaml b/packages/nextjs-config/tests/integration/fixtures/pnpm-lock.yaml
index aeed33d590..875e9a93b5 100644
--- a/packages/nextjs-config/tests/integration/fixtures/pnpm-lock.yaml
+++ b/packages/nextjs-config/tests/integration/fixtures/pnpm-lock.yaml
@@ -4,6 +4,9 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
+overrides:
+  caniuse-lite: 1.0.30001816
+
 importers:
 
   .:
@@ -45,18 +48,6 @@ importers:
         specifier: 5.108.1
         version: 5.108.1
 
-  next14:
-    dependencies:
-      next:
-        specifier: 15.5.28
-        version: 15.5.28(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
-      react:
-        specifier: 18.3.1
-        version: 18.3.1
-      react-dom:
-        specifier: 18.3.1
-        version: 18.3.1(react@18.3.1)
-
   next15:
     dependencies:
       next:
@@ -69,11 +60,23 @@ importers:
         specifier: 19.2.8
         version: 19.2.8(react@19.2.8)
 
-  next16:
+  next15-react18:
     dependencies:
       next:
         specifier: 15.5.28
-        version: 15.5.28(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+        version: 15.5.28(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react:
+        specifier: 18.3.1
+        version: 18.3.1
+      react-dom:
+        specifier: 18.3.1
+        version: 18.3.1(react@18.3.1)
+
+  next16:
+    dependencies:
+      next:
+        specifier: 16.4.2
+        version: 16.4.2(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       react:
         specifier: 19.2.8
         version: 19.2.8
@@ -267,18 +270,33 @@ packages:
   '@next/env@15.5.28':
     resolution: {integrity: sha512-xxW5EBI8fMPuVTPBW7LL980IRbuDXlbkUAwp9DDhtb4Lnich3nJ13uYpvrX4VE74hWPf6AvHHAMmGCidcHjbfg==}
 
+  '@next/env@16.4.2':
+    resolution: {integrity: sha512-nTUTFH7G5/J/fmpkjVLegOkqyKOP0CEsJcMsyO4UCYeN1su+YMW/MfaSErnJskL7XM+UDK6aTvslxsRCyya/sA==}
+
   '@next/swc-darwin-arm64@15.5.28':
     resolution: {integrity: sha512-dPoQYXcfSIqx5o+TOXVXO7kONK5qbtNRDeiTfII0bT3puGIT6VF5e0QwmxNZfEZ5Zety5f3m9P/p4xqwfiLlPg==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [darwin]
 
+  '@next/swc-darwin-arm64@16.4.2':
+    resolution: {integrity: sha512-ONkhFvZNFWlsEHOM/81AtxdyuJP2KRYKYR0JxPwvcu1AuPMMMgcL+wW2luldJvMtZwKtUxoSkCychW5wIeoYSw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
   '@next/swc-darwin-x64@15.5.28':
     resolution: {integrity: sha512-RgCJ7buBivTH+6sddqaVm+/v8kwMHlFkobvdt3DfETutws5HrxnToMIWSN9X3MZ3aAi7BbKrGZZWUDQLEycXqw==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [darwin]
 
+  '@next/swc-darwin-x64@16.4.2':
+    resolution: {integrity: sha512-luPCMbOsCoaF+kXJEUjmjmOZg1lC3BflhmUu+ZmW4tBu2vW/4AXak8JBFvePizGkxVmNiAw/r9ra+6UviCWtWQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
   '@next/swc-linux-arm64-gnu@15.5.28':
     resolution: {integrity: sha512-OHXQe13olE59aKe++zHavGcJPh5SLHXi6Anret3BBeq1+qhSuOJDNAli/EDDfxs6UTqA4Qddo4uyYry2slyjiQ==}
     engines: {node: '>= 10'}
@@ -286,6 +304,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@next/swc-linux-arm64-gnu@16.4.2':
+    resolution: {integrity: sha512-xhwFTAncJyaCNy5KqKKuKaIIdCy1/1ZV1s5S1G0hhT7wGMkDTlfJ6aQbfRFnIG/s3/kDrxQ8aycVe+c5QnP8ow==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [glibc]
+
   '@next/swc-linux-arm64-musl@15.5.28':
     resolution: {integrity: sha512-nTB7bB6vfn4ezCJNYP43ukt2o8L3+WxKF/sTcTxepdXsJh3SM9RhlU7wrZYbH7L4HO5M87dqDTwm8587vAkCiw==}
     engines: {node: '>= 10'}
@@ -293,6 +318,13 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@next/swc-linux-arm64-musl@16.4.2':
+    resolution: {integrity: sha512-T1PNmfbPcxr5ndtWUL/3wQtLXsz808lq6sc2GrNT5k2oquF7UyqZddHSuAewHVsWsGXe6nsl9HoN1YNriVjuSg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+    libc: [musl]
+
   '@next/swc-linux-x64-gnu@15.5.28':
     resolution: {integrity: sha512-WXCfVI32rW3xCusoUX1RpZKtyChWU2Zwe27JUDmM3KrXwcDNc9vV4zEq0GKFAURnuQ/Ouo/XqPvB0yh445XZCg==}
     engines: {node: '>= 10'}
@@ -300,6 +332,13 @@ packages:
     os: [linux]
     libc: [glibc]
 
+  '@next/swc-linux-x64-gnu@16.4.2':
+    resolution: {integrity: sha512-N9cDUOCGtkJG5PNKDFZUF3xXndrJJcpLp121uAGjIGvO/U2p9tfdNOM9htj7+5f72l0m8rMw/cvYacUJBQoudg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [glibc]
+
   '@next/swc-linux-x64-musl@15.5.28':
     resolution: {integrity: sha512-Miq+NDb/HWsXuxseYxMM6fuEOQXgTziarkKIRpVKCn8W69cEfhQaQr+90pO+u4q2CbJR2wzXmUuCFyZaJs/Nng==}
     engines: {node: '>= 10'}
@@ -307,18 +346,37 @@ packages:
     os: [linux]
     libc: [musl]
 
+  '@next/swc-linux-x64-musl@16.4.2':
+    resolution: {integrity: sha512-yY2uh1YhX6ufuYy2FCbw1dqblbhI57GLYAJfCkqD9auTv6pLrH67Uccjc3QMKBeCYAG6lkgu08ExmX1bbjejjQ==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+    libc: [musl]
+
   '@next/swc-win32-arm64-msvc@15.5.28':
     resolution: {integrity: sha512-5LR79lemgDlgxvG7MQJ+zHCkVcrUoQuO7CiIvq3I58vNW4goSOE2b+19Z6FujRWMouvni4gvudYFuFuNxolGWA==}
     engines: {node: '>= 10'}
     cpu: [arm64]
     os: [win32]
 
+  '@next/swc-win32-arm64-msvc@16.4.2':
+    resolution: {integrity: sha512-j/ArWRIHpMMB6wYLMhr2puTguBt70lNU/Cmjl9p6dTDE8DGknYJMP9PdwPk2dqpCNL/KIX9yfngDvIesxJPmsg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
   '@next/swc-win32-x64-msvc@15.5.28':
     resolution: {integrity: sha512-GNipvXUYROSTf4PXEyH95FrWImIB5zdaK6uEOg0RP1/X2drnvoMwiBkJ0VWdzX7w3iiBm3y5g2TxkKDGVTOQcg==}
     engines: {node: '>= 10'}
     cpu: [x64]
     os: [win32]
 
+  '@next/swc-win32-x64-msvc@16.4.2':
+    resolution: {integrity: sha512-AA4edyWHDko3NCSo0x6GomsdgFb0oR1J3MXU1b5xt6FRFg4AucrMPW3S0hCe/9onU0O1BbpGQBsqo1r0Gneu1g==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
   '@posthog/browser-common@0.9.4':
     resolution: {integrity: sha512-QlG0WZFG9iTp9cmXTypB4cgnxBAD3GImrj9AwmA84uh8uy5vIVgVLjoTTdOAW29XL+kh/eLn/5ZtBQt2JQfR+w==}
 
@@ -336,6 +394,9 @@ packages:
   '@swc/helpers@0.5.15':
     resolution: {integrity: sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g==}
 
+  '@swc/helpers@0.5.23':
+    resolution: {integrity: sha512-5lSsMOTXURePglDfvuAQUqkGek9Hg2kksOYay2m0+XR++b2NWYL/4sWyuvVBIs8oKnJaxkdi9whaL/sqN13afw==}
+
   '@types/estree@1.0.9':
     resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
 
@@ -442,9 +503,6 @@ packages:
   caniuse-lite@1.0.30001816:
     resolution: {integrity: sha512-+8Yx7BXCoqk6IF8yTicjfUR6D/ldJzdlsodlEOiOSPmhK844WIgk67/zIQaGAOxNkZyyvBlrRFnLvqKIoqbAFw==}
 
-  caniuse-lite@1.0.30001819:
-    resolution: {integrity: sha512-LFUqIIAwpzsIuevnKnsR9qnStBcgzPShTX61lBwN9uFkkf8o8zLiebEjbW8AYtZiF+1YKDWfdt/pWDtMuG8Xwg==}
-
   chrome-trace-event@1.0.4:
     resolution: {integrity: sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==}
     engines: {node: '>=6.0'}
@@ -631,6 +689,27 @@ packages:
       sass:
         optional: true
 
+  next@16.4.2:
+    resolution: {integrity: sha512-r+oBJojfefUjOiWkBhXgLS+igxX/7BWyK59uHnyOyplMSLtBZ+QLP3okrdYTbrfrbrmNTVWLBPaHDX9KRaIt3w==}
+    engines: {node: '>=20.9.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.51.1
+      babel-plugin-react-compiler: '*'
+      react: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      react-dom: ^18.2.0 || 19.0.0-rc-de68d2f4-20241204 || ^19.0.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      babel-plugin-react-compiler:
+        optional: true
+      sass:
+        optional: true
+
   node-releases@2.0.58:
     resolution: {integrity: sha512-BdiKAgbfRlvfMq/XzO/AF9NPmaA8a+YpLAyAFTVFBj3gARrAIfWvNq7Q7NE4se3KgFu0KkrvQMxTS0XVnsGzHg==}
     engines: {node: '>=18'}
@@ -646,6 +725,10 @@ packages:
     resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
     engines: {node: ^10 || ^12 || >=14}
 
+  postcss@8.5.23:
+    resolution: {integrity: sha512-g50586zr4bZmwFiTlflMu8E0bDTb5I5gertgwAKmsdUlTQIhZtunzUlD1WSzwcVWPoAVpsrA6vlfCD7oXvRwgg==}
+    engines: {node: ^10 || ^12 || >=14}
+
   posthog-js@1.438.5:
     resolution: {integrity: sha512-biGOT/IqaehEcJ+1c+gmlgl2ZQCMGJX/k2K5P0nIQ9fJsaTGYRVYVPKuoPkoQNYS+Jzb1NIfcV702CQr2UrDKQ==}
     peerDependencies:
@@ -927,30 +1010,56 @@ snapshots:
 
   '@next/env@15.5.28': {}
 
+  '@next/env@16.4.2': {}
+
   '@next/swc-darwin-arm64@15.5.28':
     optional: true
 
+  '@next/swc-darwin-arm64@16.4.2':
+    optional: true
+
   '@next/swc-darwin-x64@15.5.28':
     optional: true
 
+  '@next/swc-darwin-x64@16.4.2':
+    optional: true
+
   '@next/swc-linux-arm64-gnu@15.5.28':
     optional: true
 
+  '@next/swc-linux-arm64-gnu@16.4.2':
+    optional: true
+
   '@next/swc-linux-arm64-musl@15.5.28':
     optional: true
 
+  '@next/swc-linux-arm64-musl@16.4.2':
+    optional: true
+
   '@next/swc-linux-x64-gnu@15.5.28':
     optional: true
 
+  '@next/swc-linux-x64-gnu@16.4.2':
+    optional: true
+
   '@next/swc-linux-x64-musl@15.5.28':
     optional: true
 
+  '@next/swc-linux-x64-musl@16.4.2':
+    optional: true
+
   '@next/swc-win32-arm64-msvc@15.5.28':
     optional: true
 
+  '@next/swc-win32-arm64-msvc@16.4.2':
+    optional: true
+
   '@next/swc-win32-x64-msvc@15.5.28':
     optional: true
 
+  '@next/swc-win32-x64-msvc@16.4.2':
+    optional: true
+
   '@posthog/browser-common@0.9.4':
     dependencies:
       '@posthog/core': 1.59.0
@@ -970,6 +1079,10 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  '@swc/helpers@0.5.23':
+    dependencies:
+      tslib: 2.8.1
+
   '@types/estree@1.0.9': {}
 
   '@types/json-schema@7.0.15': {}
@@ -1097,8 +1210,6 @@ snapshots:
 
   caniuse-lite@1.0.30001816: {}
 
-  caniuse-lite@1.0.30001819: {}
-
   chrome-trace-event@1.0.4: {}
 
   client-only@0.0.1: {}
@@ -1193,7 +1304,7 @@ snapshots:
     dependencies:
       '@next/env': 15.5.28
       '@swc/helpers': 0.5.15
-      caniuse-lite: 1.0.30001819
+      caniuse-lite: 1.0.30001816
       postcss: 8.4.31
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
@@ -1217,7 +1328,7 @@ snapshots:
     dependencies:
       '@next/env': 15.5.28
       '@swc/helpers': 0.5.15
-      caniuse-lite: 1.0.30001819
+      caniuse-lite: 1.0.30001816
       postcss: 8.4.31
       react: 19.2.8
       react-dom: 19.2.8(react@19.2.8)
@@ -1237,6 +1348,31 @@ snapshots:
       - '@types/node'
       - babel-plugin-macros
 
+  next@16.4.2(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      '@next/env': 16.4.2
+      '@swc/helpers': 0.5.23
+      baseline-browser-mapping: 2.11.28
+      caniuse-lite: 1.0.30001816
+      postcss: 8.5.23
+      react: 19.2.8
+      react-dom: 19.2.8(react@19.2.8)
+      styled-jsx: 5.1.6(react@19.2.8)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 16.4.2
+      '@next/swc-darwin-x64': 16.4.2
+      '@next/swc-linux-arm64-gnu': 16.4.2
+      '@next/swc-linux-arm64-musl': 16.4.2
+      '@next/swc-linux-x64-gnu': 16.4.2
+      '@next/swc-linux-x64-musl': 16.4.2
+      '@next/swc-win32-arm64-msvc': 16.4.2
+      '@next/swc-win32-x64-msvc': 16.4.2
+      sharp: 0.35.5
+    transitivePeerDependencies:
+      - '@babel/core'
+      - '@types/node'
+      - babel-plugin-macros
+
   node-releases@2.0.58: {}
 
   path-key@3.1.1: {}
@@ -1249,6 +1385,12 @@ snapshots:
       picocolors: 1.1.1
       source-map-js: 1.2.2
 
+  postcss@8.5.23:
+    dependencies:
+      nanoid: 3.3.20
+      picocolors: 1.1.1
+      source-map-js: 1.2.2
+
   posthog-js@1.438.5(react@19.2.8):
     dependencies:
       '@posthog/browser-common': 0.9.4
diff --git a/packages/nextjs-config/tests/integration/fixtures/pnpm-workspace.yaml b/packages/nextjs-config/tests/integration/fixtures/pnpm-workspace.yaml
index e35c7fb497..b0d56dfc11 100644
--- a/packages/nextjs-config/tests/integration/fixtures/pnpm-workspace.yaml
+++ b/packages/nextjs-config/tests/integration/fixtures/pnpm-workspace.yaml
@@ -1,8 +1,11 @@
 packages:
-  - next14
+  - next15-react18
   - next15
   - next16
 minimumReleaseAge: 10080
+overrides:
+  # Keep Next's browser data on a release that passes the fixture cooldown.
+  caniuse-lite: 1.0.30001816
 # Match the shipped CLI minimum; the downstream PostHog workspace also allows @posthog/* releases.
 minimumReleaseAgeExclude:
   - '@posthog/cli@0.18.11'
diff --git a/packages/nextjs-config/tests/integration/run.mjs b/packages/nextjs-config/tests/integration/run.mjs
index 7339bf49a3..e389e97efd 100644
--- a/packages/nextjs-config/tests/integration/run.mjs
+++ b/packages/nextjs-config/tests/integration/run.mjs
@@ -22,7 +22,7 @@ import path from 'node:path'
 import { setTimeout as sleep } from 'node:timers/promises'
 import { compareAssets, digest, validateUploads, validateWorkers } from './assertions.mjs'
 
-const fixtures = ['next14', 'next15', 'next16']
+const fixtures = ['next15-react18', 'next15', 'next16']
 const directory = import.meta.dirname
 const repository = path.resolve(directory, '../../../..')
 const artifactRoot = path.join(repository, 'test-results/nextjs-integration')
@@ -123,6 +123,12 @@ async function prepare() {
     recursive: true,
     filter: (source) => path.basename(source) !== 'node_modules',
   })
+  for (const name of fixtures) {
+    const { next, react } = json(path.join(workspace, name, 'package.json')).dependencies
+    assert.equal(next.split('.')[0], name.match(/^next(\d+)/)[1], `${name} must use its named Next.js major`)
+    const reactMajor = name.match(/react(\d+)/)?.[1]
+    if (reactMajor) assert.equal(react.split('.')[0], reactMajor, `${name} must use its named React major`)
+  }
   const store = process.env.NEXTJS_INTEGRATION_STORE_DIR
   await run('pnpm', ['install', '--frozen-lockfile', '--ignore-scripts', ...(store ? ['--store-dir', store] : [])], {
     cwd: workspace,

From c4bdc81bc3682c427d481ca15e7ce501ac8e9dfa Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Wed, 28 Oct 2026 13:10:49 -0700
Subject: [PATCH 06/20] feat(node)!: send analytics and AI events on separate
 capture lanes (#5410)

* refactor(core): let subclasses call normalizeMessage

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(node): send pre-serialized events and let callers keep unsent ones

The capture sender now takes events serialized once, builds the body from
those JSON strings, accepts an abort signal that stops attempts and backoff
waits, and can hand back events whose last attempt got no HTTP response.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): cancel capture backoff waits cleanly on abort

The default backoff wait now clears its timer when the send is aborted and
removes its abort listener when it finishes, so a signal shared by every
send of a lane does not collect listeners.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: send analytics and AI events on separate capture lanes

Each lane has its own queue, timer, flushAt trigger, batching and in-flight
send, so a slow or failing lane no longer delays or drops the other's
events. flush() waits for both lanes and no longer rejects on delivery
failures, maxQueueSize applies to analytics events only, batches stop at
about 5 MiB, and events that fail with a network error are kept for the
next flush. Shutdown drains both lanes against one deadline and aborts
sends still running when it passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for separate capture lanes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): keep the shutdown deadline while a capture body is compressing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-node-capture-lanes.md      |   5 +
 packages/core/src/posthog-core-stateless.ts   |   2 +-
 .../posthog-node-references-latest.json       |   3 +-
 .../src/__tests__/ai-capture/batching.spec.ts |  70 -----
 .../src/__tests__/ai-capture/wiring.spec.ts   |  59 ++--
 .../__tests__/capture-lane/isolation.spec.ts  | 242 +++++++++++++++
 .../capture-v1/route-isolation.spec.ts        |  76 -----
 .../src/__tests__/capture-v1/sender.spec.ts   | 280 ++++++++++++++----
 .../__tests__/capture-v1/transform.spec.ts    |  25 +-
 .../src/__tests__/immediate-delivery.spec.ts  |   3 +-
 .../node/src/__tests__/posthog-node.spec.ts   |  88 ++++--
 .../__tests__/server-wire-snapshots.spec.ts   |   6 +-
 .../src/__tests__/waituntil-flush.spec.ts     |  56 +++-
 packages/node/src/ai-capture/batching.ts      |  47 ---
 packages/node/src/ai-capture/routing.ts       |   4 -
 packages/node/src/capture-v1/sender.ts        | 203 ++++++++++---
 packages/node/src/capture-v1/transform.ts     |  17 +-
 packages/node/src/capture-v1/types.ts         |  10 -
 packages/node/src/client.ts                   | 205 ++++++++-----
 packages/node/src/types.ts                    |   4 +-
 20 files changed, 926 insertions(+), 479 deletions(-)
 create mode 100644 .changeset/posthog-node-capture-lanes.md
 delete mode 100644 packages/node/src/__tests__/ai-capture/batching.spec.ts
 create mode 100644 packages/node/src/__tests__/capture-lane/isolation.spec.ts
 delete mode 100644 packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
 delete mode 100644 packages/node/src/ai-capture/batching.ts

diff --git a/.changeset/posthog-node-capture-lanes.md b/.changeset/posthog-node-capture-lanes.md
new file mode 100644
index 0000000000..fdc9e021f6
--- /dev/null
+++ b/.changeset/posthog-node-capture-lanes.md
@@ -0,0 +1,5 @@
+---
+'posthog-node': major
+---
+
+Analytics and AI events are batched and sent on separate lanes, in batches of about 5 MiB at most, and events that fail with a network error are kept and retried on the next flush. `flush()` no longer rejects on delivery failures (they arrive through the `'error'` event), and `maxQueueSize` now applies to analytics events only.
diff --git a/packages/core/src/posthog-core-stateless.ts b/packages/core/src/posthog-core-stateless.ts
index 4a2d09968e..3f27677a03 100644
--- a/packages/core/src/posthog-core-stateless.ts
+++ b/packages/core/src/posthog-core-stateless.ts
@@ -1347,7 +1347,7 @@ export abstract class PostHogCoreStateless {
     }
   }
 
-  private normalizeMessage(message: PostHogEventProperties): PostHogEventProperties {
+  protected normalizeMessage(message: PostHogEventProperties): PostHogEventProperties {
     // Top-level `type` is deprecated and a no-op for batch ingestion.
     // Top-level `library` and `library_version` are deprecated; `$lib` and
     // `$lib_version` in properties are the canonical SDK metadata fields.
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index 371131ff1c..3076dfcc77 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -528,6 +528,7 @@
         },
         {
           "category": "",
+          "description": "Sends all queued events and spans, and resolves when every send has finished. It does not reject when delivery fails: those failures arrive on the `'error'` event.",
           "details": null,
           "id": "flush",
           "showDocs": true,
@@ -3754,7 +3755,7 @@
           "name": "flushInterval"
         },
         {
-          "description": "The maximum number of cached messages either in memory or on the local storage (must be higher than `flushAt`)",
+          "description": "The maximum number of analytics events held in memory waiting to be sent (must be higher than `flushAt`).\nWhen the queue is full, the oldest event is dropped and reported through the `'error'` event.\n`captureAi` events have their own queue and do not count toward this limit.",
           "type": "number",
           "name": "maxQueueSize"
         },
diff --git a/packages/node/src/__tests__/ai-capture/batching.spec.ts b/packages/node/src/__tests__/ai-capture/batching.spec.ts
deleted file mode 100644
index 4ee0116aa0..0000000000
--- a/packages/node/src/__tests__/ai-capture/batching.spec.ts
+++ /dev/null
@@ -1,70 +0,0 @@
-import { Buffer } from 'node:buffer'
-
-import { partitionAiBatch } from '@/ai-capture/batching'
-
-const eventOfBytes = (name: string, bytes: number): any => {
-  return { event: name, properties: { pad: 'x'.repeat(bytes) } }
-}
-
-describe('partitionAiBatch', () => {
-  it('passes small events through as a single batch and skips undefined entries', () => {
-    const { batches, dropped } = partitionAiBatch([eventOfBytes('a', 10), undefined, eventOfBytes('b', 10)])
-    expect(batches).toHaveLength(1)
-    expect(batches[0].map((event) => event.event)).toEqual(['a', 'b'])
-    expect(dropped).toEqual([])
-  })
-
-  it('drops events over the per-event cap, reporting name and size only', () => {
-    const { batches, dropped } = partitionAiBatch([eventOfBytes('huge', 300), eventOfBytes('ok', 10)], 200, 1000)
-    expect(batches).toHaveLength(1)
-    expect(batches[0].map((event) => event.event)).toEqual(['ok'])
-    expect(dropped).toHaveLength(1)
-    expect(dropped[0].event).toBe('huge')
-    expect(dropped[0].bytes).toBeGreaterThan(200)
-    expect(Object.keys(dropped[0]).sort()).toEqual(['bytes', 'event'])
-  })
-
-  it('applies the per-event cap to UTF-8 bytes, not string length', () => {
-    const huge = { event: 'huge', properties: { pad: '界'.repeat(100) } }
-    const small = eventOfBytes('ok', 10)
-    const bytes = Buffer.byteLength(JSON.stringify(huge), 'utf8')
-    expect(JSON.stringify(huge).length).toBeLessThan(200)
-    expect(bytes).toBeGreaterThan(200)
-
-    expect(partitionAiBatch([huge, small], 200, 1000)).toEqual({
-      batches: [[small]],
-      dropped: [{ event: 'huge', bytes }],
-    })
-  })
-
-  it('packs greedily under the target batch size', () => {
-    const events = [eventOfBytes('a', 400), eventOfBytes('b', 400), eventOfBytes('c', 400)]
-    const { batches, dropped } = partitionAiBatch(events, 2000, 1000)
-    expect(batches.map((batch) => batch.map((event) => event.event))).toEqual([['a', 'b'], ['c']])
-    expect(dropped).toEqual([])
-  })
-
-  it('packs multibyte events according to their aggregate UTF-8 bytes', () => {
-    const events = ['a', 'b', 'c'].map((event) => ({ event, properties: { pad: '界'.repeat(100) } }))
-    const sizes = events.map((event) => Buffer.byteLength(JSON.stringify(event), 'utf8'))
-    const target = sizes[0] + sizes[1]
-    expect(events.reduce((sum, event) => sum + JSON.stringify(event).length, 0)).toBeLessThan(target)
-    expect(sizes.reduce((sum, bytes) => sum + bytes, 0)).toBeGreaterThan(target)
-
-    expect(partitionAiBatch(events, 2000, target)).toEqual({
-      batches: [[events[0], events[1]], [events[2]]],
-      dropped: [],
-    })
-  })
-
-  it('allows a single event above the target (but under the cap) alone in its batch', () => {
-    const { batches, dropped } = partitionAiBatch([eventOfBytes('big', 1500)], 2000, 1000)
-    expect(batches.map((batch) => batch.map((event) => event.event))).toEqual([['big']])
-    expect(dropped).toEqual([])
-  })
-
-  it('reports a non-string event name as unknown', () => {
-    const { dropped } = partitionAiBatch([{ properties: { pad: 'x'.repeat(300) } } as any], 200, 1000)
-    expect(dropped[0].event).toBe('unknown')
-  })
-})
diff --git a/packages/node/src/__tests__/ai-capture/wiring.spec.ts b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
index 355be1a6fe..4c410c1724 100644
--- a/packages/node/src/__tests__/ai-capture/wiring.spec.ts
+++ b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
@@ -1,5 +1,3 @@
-import { PostHogPersistedProperty } from '@posthog/core'
-
 import { CaptureError, PostHog } from '@/entrypoints/index.node'
 
 import { AI_CAPTURE_PATH, AI_CAPTURE_URL, ANALYTICS_CAPTURE_PATH, v1Response, v413Response } from '../utils'
@@ -10,9 +8,6 @@ vi.mock('../../version', () => ({ version: '1.2.3' }))
 describe('AI capture lane wiring (Node SDK)', () => {
   const harness = new V1WiringHarness()
 
-  const aiCaptureQueueEvents = (posthog: PostHog): string[] =>
-    (posthog.getPersistedProperty(PostHogPersistedProperty.AiCaptureQueue) || []).map((item: any) => item.message.event)
-
   const deliveredEventsIn = async (fragment: string): Promise<string[]> => {
     const events: string[] = []
     for (const [call, result] of harness.fetch.mock.calls.map(
@@ -96,28 +91,57 @@ describe('AI capture lane wiring (Node SDK)', () => {
     expect(harness.fetch).toHaveBeenCalledTimes(1)
   })
 
-  it('drops events over 8MiB with a name-and-size-only error log, delivering the rest', async () => {
+  it('drops events whose properties pass 8MiB with one aggregate error, delivering the rest', async () => {
     const posthog = harness.makeClient()
-    posthog.debug(true)
     const onError = vi.fn()
     posthog.on('error', onError)
     const pad = 'x'.repeat(9 * 1024 * 1024)
-    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { pad } })
+    const dropped = [1, 2].map(() =>
+      posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { pad } })
+    )
     posthog.captureAi({ distinctId: 'u', event: '$ai_span', properties: {} })
     await posthog.flush()
 
     expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_span'])
-    const errorLog = (console.error as vi.Mock).mock.calls.flat().join(' ')
-    expect(errorLog).toContain('$ai_generation')
-    expect(errorLog).toMatch(/\d+ bytes/)
-    expect(errorLog).not.toContain('xxxx')
+    expect(onError).toHaveBeenCalledTimes(1)
+    const error = onError.mock.calls[0][0] as CaptureError
+    expect(error).toBeInstanceOf(CaptureError)
+    expect(error.endpoint).toBe(AI_CAPTURE_PATH)
+    expect(error.drops).toEqual(dropped.map((uuid) => ({ uuid, details: 'event too large' })))
+    expect(error.message).toBe(
+      `Dropped 2 event(s) for ${AI_CAPTURE_PATH} before sending: 2 with properties larger than 8388608 bytes`
+    )
+    // With a listener, the listener owns reporting.
+    expect(console.warn).not.toHaveBeenCalled()
+  })
+
+  it('warns once on the console for local drops when nothing listens for errors', async () => {
+    const posthog = harness.makeClient()
+    const pad = 'x'.repeat(9 * 1024 * 1024)
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { pad } })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { pad } })
+    await posthog.flush()
+
+    expect(console.warn).toHaveBeenCalledTimes(1)
+    expect(console.warn).toHaveBeenCalledWith(
+      `[PostHog] Dropped 2 event(s) for ${AI_CAPTURE_PATH} before sending: 2 with properties larger than 8388608 bytes`
+    )
+  })
+
+  it('drops an oversized captureAiImmediate event without sending it', async () => {
+    const posthog = harness.makeClient()
+    const onError = vi.fn()
+    posthog.on('error', onError)
 
+    const uuid = await posthog.captureAiImmediate({
+      distinctId: 'u',
+      event: '$ai_generation',
+      properties: { pad: 'x'.repeat(9 * 1024 * 1024) },
+    })
+
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(0)
     expect(onError).toHaveBeenCalledTimes(1)
-    const emittedError = onError.mock.calls[0][0]
-    expect(emittedError).toBeInstanceOf(Error)
-    expect(emittedError.message).toContain('$ai_generation')
-    expect(emittedError.message).toMatch(/\d+ bytes/)
-    expect(emittedError.message).not.toContain('xxxx')
+    expect((onError.mock.calls[0][0] as CaptureError).drops).toEqual([{ uuid, details: 'event too large' }])
   })
 
   it('splits multi-MB batches into byte-bounded requests', async () => {
@@ -172,7 +196,6 @@ describe('AI capture lane wiring (Node SDK)', () => {
     posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
     await posthog.shutdown()
     expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_generation'])
-    expect(aiCaptureQueueEvents(posthog)).toEqual([])
   })
 
   it('routes non-$ai_ events through the lane anyway, with a debug log', async () => {
diff --git a/packages/node/src/__tests__/capture-lane/isolation.spec.ts b/packages/node/src/__tests__/capture-lane/isolation.spec.ts
new file mode 100644
index 0000000000..4bf5ca9033
--- /dev/null
+++ b/packages/node/src/__tests__/capture-lane/isolation.spec.ts
@@ -0,0 +1,242 @@
+import { CaptureError, PostHog } from '@/entrypoints/index.node'
+
+import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, captureEvents, v1Response } from '../utils'
+import { V1WiringHarness, routeByUrl, waitForFlushTimer } from '../utils/v1-wiring'
+
+vi.mock('../../version', () => ({ version: '1.2.3' }))
+
+const ANALYTICS_UUID = '0198c0de-0000-7000-8000-000000000001'
+
+const errorResponse = (status: number): any => ({
+  status,
+  text: () => Promise.resolve(''),
+  headers: { get: () => null },
+  body: null,
+})
+
+/** Holds every request to `path` open until `release()`, which also lets later ones through; other URLs answer normally. */
+function holdLane(harness: V1WiringHarness, path: string): { release: () => void } {
+  const pending: (() => void)[] = []
+  let held = true
+  harness.fetch.mockImplementation((url: any) =>
+    held && String(url).includes(path)
+      ? new Promise((resolve) => pending.push(() => resolve(v1Response())))
+      : Promise.resolve(routeByUrl(url))
+  )
+  return {
+    release: () => {
+      held = false
+      pending.splice(0).forEach((resolve) => resolve())
+    },
+  }
+}
+
+// Analytics and AI events have separate lanes: a slow or failing lane must never delay,
+// drop or resend the other lane's events.
+describe('capture lane isolation (Node SDK)', () => {
+  const harness = new V1WiringHarness()
+
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(console, 'info').mockImplementation(() => {})
+    harness.useDefaultRouting()
+  })
+
+  afterEach(async () => {
+    harness.useDefaultRouting()
+    await harness.cleanup()
+    vi.clearAllMocks()
+  })
+
+  it('flushes each lane as its own homogeneous request (no mixed batch)', async () => {
+    const posthog = harness.makeClient()
+    posthog.capture({ distinctId: 'u', event: 'a', properties: {} })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_span', properties: {} })
+    posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    await waitForFlushTimer()
+    await posthog.flush()
+
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['a', '$ai_generation'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_span'])
+    expect(harness.callsTo('/batch/')).toHaveLength(0)
+  })
+
+  it('keeps sending analytics events on their own timer while an AI send is stuck', async () => {
+    const ai = holdLane(harness, AI_CAPTURE_PATH)
+    const posthog = harness.makeClient({ flushInterval: 1000, flushAt: 100, requestTimeout: 60_000 })
+
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    posthog.capture({ distinctId: 'u', event: 'first', properties: {} })
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['first'])
+
+    posthog.capture({ distinctId: 'u', event: 'second', properties: {} })
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['first', 'second'])
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
+
+    ai.release()
+  })
+
+  it('resolves flush() only after both lanes settle, without rejecting on a delivery failure', async () => {
+    const ai = holdLane(harness, AI_CAPTURE_PATH)
+    const holdAi = harness.fetch.getMockImplementation()!
+    harness.fetch.mockImplementation((url: any, options: any) =>
+      String(url).includes(ANALYTICS_CAPTURE_PATH) ? Promise.resolve(errorResponse(400)) : holdAi(url, options)
+    )
+    const posthog = harness.makeClient()
+    const errors: CaptureError[] = []
+    posthog.on('error', (error) => errors.push(error))
+
+    posthog.capture({ distinctId: 'u', event: 'rejected', properties: {} })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    let settled = false
+    const flush = posthog.flush().then(() => (settled = true))
+    await vi.advanceTimersByTimeAsync(0)
+
+    expect(harness.callsTo(ANALYTICS_CAPTURE_PATH)).toHaveLength(1)
+    expect(errors.map((error) => error.endpoint)).toEqual([ANALYTICS_CAPTURE_PATH])
+    expect(settled).toBe(false)
+
+    ai.release()
+    await expect(flush).resolves.toBe(true)
+  })
+
+  it('never drops analytics events when the AI queue is full', async () => {
+    const ai = holdLane(harness, AI_CAPTURE_PATH)
+    const posthog = harness.makeClient({ flushAt: 1, requestTimeout: 60_000 })
+    const errors: CaptureError[] = []
+    posthog.on('error', (error) => errors.push(error))
+
+    // One AI event goes in flight; the AI queue then holds 1000 and drops the 5 oldest.
+    posthog.captureAi({ distinctId: 'u', event: '$ai_0', properties: {} })
+    await vi.advanceTimersByTimeAsync(0)
+    for (let i = 1; i <= 1005; i++) {
+      posthog.captureAi({ distinctId: 'u', event: `$ai_${i}`, properties: {} })
+    }
+    const analytics = ['a1', 'a2', 'a3']
+    analytics.forEach((event) => posthog.capture({ distinctId: 'u', event, properties: {} }))
+    await vi.advanceTimersByTimeAsync(0)
+    ai.release()
+    await posthog.flush()
+
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(analytics)
+    const aiEvents = harness.eventsIn(AI_CAPTURE_PATH)
+    expect(aiEvents).toHaveLength(1001)
+    expect(aiEvents.slice(0, 2)).toEqual(['$ai_0', '$ai_6'])
+    expect(errors).toHaveLength(1)
+    expect(errors[0].endpoint).toBe(AI_CAPTURE_PATH)
+    expect(errors[0].message).toContain('5 because the queue was full (1000 events)')
+  })
+
+  it('drains both lanes concurrently on shutdown and stops retrying at the deadline', async () => {
+    harness.fetch.mockImplementation(() => Promise.resolve(errorResponse(503)))
+    const posthog = harness.makeClient({ fetchRetryCount: 5, fetchRetryDelay: 1000, flushAt: 100 })
+    const errors: CaptureError[] = []
+    posthog.on('error', (error) => errors.push(error))
+    posthog.capture({ distinctId: 'u', event: 'custom', properties: {}, uuid: ANALYTICS_UUID })
+    const aiUuid = posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    await vi.advanceTimersByTimeAsync(0)
+
+    let finished = false
+    const shutdown = posthog.shutdown(1500).then(() => (finished = true))
+    await vi.advanceTimersByTimeAsync(0)
+    // Both first attempts go out before either lane's backoff elapses.
+    expect(harness.callsTo(ANALYTICS_CAPTURE_PATH)).toHaveLength(1)
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
+
+    await vi.advanceTimersByTimeAsync(1499)
+    expect(finished).toBe(false)
+    await vi.advanceTimersByTimeAsync(1)
+    await shutdown
+
+    expect(harness.callsTo(ANALYTICS_CAPTURE_PATH)).toHaveLength(2)
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(2)
+    await vi.advanceTimersByTimeAsync(60_000)
+    expect(harness.fetch).toHaveBeenCalledTimes(4)
+    expect(errors).toHaveLength(2)
+    expect(errors.map((error) => [error.endpoint, error.retryExhausted])).toEqual(
+      expect.arrayContaining([
+        [ANALYTICS_CAPTURE_PATH, [ANALYTICS_UUID]],
+        [AI_CAPTURE_PATH, [aiUuid]],
+      ])
+    )
+  })
+
+  it('keeps events after a network failure and resends them, same uuid, on the next flush', async () => {
+    harness.fetch.mockImplementation((url: any) =>
+      String(url).includes(AI_CAPTURE_PATH) ? Promise.reject(new Error('network down')) : Promise.resolve(v1Response())
+    )
+    const posthog = harness.makeClient()
+    const errors: Error[] = []
+    posthog.on('error', (error) => errors.push(error))
+    posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
+    const uuid = posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    await posthog.flush()
+
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
+    expect(errors).toEqual([])
+
+    harness.useDefaultRouting()
+    await posthog.flush()
+
+    const [failed, resent] = captureEvents(harness.fetch, AI_CAPTURE_PATH)
+    expect(resent).toEqual(failed)
+    expect(resent.uuid).toBe(uuid)
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
+    expect(errors).toEqual([])
+  })
+
+  it('drops and reports a batch whose retries end on HTTP 500, without resending it', async () => {
+    harness.fetch.mockImplementation((url: any) =>
+      Promise.resolve(String(url).includes(AI_CAPTURE_PATH) ? errorResponse(500) : routeByUrl(url))
+    )
+    const posthog = harness.makeClient({ fetchRetryCount: 1, fetchRetryDelay: 1 })
+    const errors: CaptureError[] = []
+    posthog.on('error', (error) => errors.push(error))
+    const uuid = posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    const flush = posthog.flush()
+    await vi.advanceTimersByTimeAsync(1)
+    await flush
+
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(2)
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toMatchObject({ endpoint: AI_CAPTURE_PATH, retryExhausted: [uuid] })
+
+    harness.useDefaultRouting()
+    await posthog.flush()
+    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(2)
+  })
+
+  it("emits 'flush' once per lane with that lane's messages", async () => {
+    const posthog = harness.makeClient()
+    const flushed: string[][] = []
+    posthog.on('flush', (messages: any[]) => flushed.push(messages.map((message) => message.event)))
+    posthog.capture({ distinctId: 'u', event: 'custom', properties: {} })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    await posthog.flush()
+
+    expect(flushed).toHaveLength(2)
+    expect(flushed).toEqual(expect.arrayContaining([['custom'], ['$ai_generation']]))
+  })
+
+  it('still sends events captured after a shutdown that hit its deadline', async () => {
+    const analytics = holdLane(harness, ANALYTICS_CAPTURE_PATH)
+    const posthog: PostHog = harness.makeClient({ requestTimeout: 60_000 })
+    posthog.capture({ distinctId: 'u', event: 'before-shutdown', properties: {} })
+    const shutdown = posthog.shutdown(100)
+    await vi.advanceTimersByTimeAsync(100)
+    await shutdown
+    analytics.release()
+
+    posthog.capture({ distinctId: 'u', event: 'after-shutdown', properties: {} })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_after_shutdown', properties: {} })
+    await posthog.flush()
+
+    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['before-shutdown', 'after-shutdown'])
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_after_shutdown'])
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts b/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
deleted file mode 100644
index 000d34c236..0000000000
--- a/packages/node/src/__tests__/capture-v1/route-isolation.spec.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import { PostHogPersistedProperty } from '@posthog/core'
-
-import { CaptureError, PostHog } from '@/entrypoints/index.node'
-
-import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, v1Response } from '../utils'
-import { V1WiringHarness, waitForFlushTimer } from '../utils/v1-wiring'
-
-vi.mock('../../version', () => ({ version: '1.2.3' }))
-
-// With analytics and captureAi events sharing a flush cycle, a failure on one lane must not roll
-// back or re-send the events already accepted on the other. Each lane has its own queue.
-describe('capture lane isolation (Node SDK)', () => {
-  vi.useFakeTimers()
-
-  const harness = new V1WiringHarness()
-
-  const queuedEvents = (posthog: PostHog, key: PostHogPersistedProperty): string[] =>
-    (posthog.getPersistedProperty(key) || []).map((item: any) => item.message.event)
-
-  beforeEach(() => {
-    vi.spyOn(console, 'warn').mockImplementation(() => {})
-    vi.spyOn(console, 'error').mockImplementation(() => {})
-    vi.spyOn(console, 'info').mockImplementation(() => {})
-    harness.useDefaultRouting()
-  })
-
-  afterEach(async () => {
-    await harness.cleanup()
-    vi.clearAllMocks()
-  })
-
-  it('keeps analytics events from being re-sent when the AI lane fails', async () => {
-    harness.fetch.mockImplementation((url: any) =>
-      (url as string).includes(ANALYTICS_CAPTURE_PATH)
-        ? Promise.resolve(v1Response())
-        : Promise.reject(new Error('network down'))
-    )
-
-    const posthog = harness.makeClient()
-    const errors: Error[] = []
-    posthog.on('error', (error) => errors.push(error))
-    posthog.capture({ distinctId: 'u', event: 'custom', properties: { x: 1 } })
-    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt-4o-mini' } })
-    await waitForFlushTimer()
-    await posthog.flush()
-
-    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
-    expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
-    expect(errors).toHaveLength(1)
-    expect(errors[0]).toBeInstanceOf(CaptureError)
-    expect((errors[0] as CaptureError).endpoint).toBe(AI_CAPTURE_PATH)
-
-    // The sender owns retries, so the failed AI batch is reported and consumed rather than requeued.
-    expect(queuedEvents(posthog, PostHogPersistedProperty.AiCaptureQueue)).toEqual([])
-    expect(queuedEvents(posthog, PostHogPersistedProperty.Queue)).toEqual([])
-
-    harness.useDefaultRouting()
-    const callsBeforeRecovery = harness.fetch.mock.calls.length
-    await posthog.flush()
-    expect(harness.fetch.mock.calls.length).toBe(callsBeforeRecovery)
-    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['custom'])
-  })
-
-  it('flushes each lane as its own homogeneous request (no mixed batch)', async () => {
-    const posthog = harness.makeClient()
-    posthog.capture({ distinctId: 'u', event: 'a', properties: {} })
-    posthog.captureAi({ distinctId: 'u', event: '$ai_span', properties: {} })
-    posthog.capture({ distinctId: 'u', event: '$ai_generation', properties: {} })
-    await waitForFlushTimer()
-    await posthog.flush()
-
-    expect(harness.eventsIn(ANALYTICS_CAPTURE_PATH)).toEqual(['a', '$ai_generation'])
-    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_span'])
-    expect(harness.callsTo('/batch/')).toHaveLength(0)
-  })
-})
diff --git a/packages/node/src/__tests__/capture-v1/sender.spec.ts b/packages/node/src/__tests__/capture-v1/sender.spec.ts
index 4fc46caba4..de3296b60e 100644
--- a/packages/node/src/__tests__/capture-v1/sender.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/sender.spec.ts
@@ -2,6 +2,7 @@ import { type PostHogEventProperties, type PostHogFetchResponse, isGzipSupported
 
 import { CaptureError } from '@/capture-v1/errors'
 import { V1CaptureSender, type V1CaptureSenderConfig, type V1CaptureSenderHooks } from '@/capture-v1/sender'
+import { type SerializedV1Event, serializeV1Event } from '@/capture-v1/serialize'
 
 const CLOCK_START = Date.parse('2024-01-01T00:00:00.000Z')
 
@@ -32,6 +33,8 @@ function msg(uuid: string, overrides: PostHogEventProperties = {}): PostHogEvent
   return { event: 'test', distinct_id: 'user', uuid, properties: {}, ...overrides }
 }
 
+const v1Events = (messages: PostHogEventProperties[]): SerializedV1Event[] => messages.map(serializeV1Event)
+
 interface Harness {
   sender: V1CaptureSender
   fetch: vi.Mock<Promise<PostHogFetchResponse>, [string, any]>
@@ -99,7 +102,7 @@ describe('V1CaptureSender', () => {
         const { sender, fetch, errors } = makeSender({ path })
         fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-        await sender.sendV1Batch([msg('u1')])
+        await sender.send(v1Events([msg('u1')]))
 
         expect(fetch).toHaveBeenCalledTimes(1)
         const [url, options] = fetch.mock.calls[0]
@@ -121,7 +124,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       const headers = headersOf(fetch, 0)
       expect(headers['Content-Type']).toBe('application/json')
@@ -137,7 +140,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch } = makeSender({ userAgent: undefined })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(headersOf(fetch, 0)).not.toHaveProperty('User-Agent')
     })
@@ -146,7 +149,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch } = makeSender({ historicalMigration: true })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(bodyOf(fetch, 0).historical_migration).toBe(true)
     })
@@ -159,7 +162,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'retry' } } }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       const h0 = headersOf(fetch, 0)
       const h1 = headersOf(fetch, 1)
@@ -175,7 +178,7 @@ describe('V1CaptureSender', () => {
 
     it('does not send when there are no messages', async () => {
       const { sender, fetch, errors } = makeSender()
-      await sender.sendV1Batch([])
+      await sender.send(v1Events([]))
       expect(fetch).not.toHaveBeenCalled()
       expect(errors).toEqual([])
     })
@@ -184,7 +187,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender({ maxAttempts: 0 })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toEqual([])
@@ -194,7 +197,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender({ maxAttempts: 0 })
       fetch.mockResolvedValueOnce(makeResponse(400))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
@@ -210,7 +213,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch } = makeSender({ compressionEnabled: true }, { compress })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(compress).toHaveBeenCalledTimes(1)
       expect(headersOf(fetch, 0)['Content-Encoding']).toBe('gzip')
@@ -222,18 +225,32 @@ describe('V1CaptureSender', () => {
       const { sender, fetch } = makeSender({ compressionEnabled: true }, { compress })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(headersOf(fetch, 0)).not.toHaveProperty('Content-Encoding')
       expect(typeof fetch.mock.calls[0][1].body).toBe('string')
     })
 
+    it('stops waiting for compression when the external signal aborts, and returns the batch as unsent', async () => {
+      const compress = vi.fn(() => new Promise<null>(() => {}))
+      const { sender, fetch } = makeSender({ compressionEnabled: true }, { compress })
+      const controller = new AbortController()
+      const events = v1Events([msg('u1')])
+
+      const sending = sender.send(events, { signal: controller.signal, keepUnsent: true })
+      await vi.waitFor(() => expect(compress).toHaveBeenCalledTimes(1))
+      controller.abort(new Error('shutdown deadline'))
+
+      expect((await sending).map((event) => event.uuid)).toEqual(['u1'])
+      expect(fetch).not.toHaveBeenCalled()
+    })
+
     it('does not compress when disabled', async () => {
       const compress = vi.fn()
       const { sender, fetch } = makeSender({ compressionEnabled: false }, { compress })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(compress).not.toHaveBeenCalled()
       expect(headersOf(fetch, 0)).not.toHaveProperty('Content-Encoding')
@@ -249,7 +266,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, { results: { u1: result } }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toEqual([])
@@ -259,7 +276,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toEqual([])
@@ -269,7 +286,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, { status: 1 }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(errors).toEqual([])
     })
@@ -280,7 +297,7 @@ describe('V1CaptureSender', () => {
         const { sender, fetch, errors } = makeSender({ path })
         fetch.mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'drop', details: 'billing' } } }))
 
-        await sender.sendV1Batch([msg('u1', { properties: { $ai_input: 'private prompt text' } })])
+        await sender.send(v1Events([msg('u1', { properties: { $ai_input: 'private prompt text' } })]))
 
         expect(fetch).toHaveBeenCalledTimes(1)
         expect(errors).toHaveLength(1)
@@ -298,7 +315,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'drop' } } }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect((errors[0] as CaptureError).drops).toEqual([{ uuid: 'u1', details: undefined }])
     })
@@ -309,7 +326,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'ok' }, u2: { result: 'retry' } } }))
         .mockResolvedValueOnce(makeResponse(200, { results: { u2: { result: 'ok' } } }))
 
-      await sender.sendV1Batch([msg('u1'), msg('u2')])
+      await sender.send(v1Events([msg('u1'), msg('u2')]))
 
       expect(fetch).toHaveBeenCalledTimes(2)
       expect(bodyOf(fetch, 0).batch.map((e: any) => e.uuid)).toEqual(['u1', 'u2'])
@@ -325,7 +342,7 @@ describe('V1CaptureSender', () => {
         )
         .mockResolvedValueOnce(makeResponse(200, { results: { u2: { result: 'ok' } } }))
 
-      await sender.sendV1Batch([msg('u1'), msg('u2')])
+      await sender.send(v1Events([msg('u1'), msg('u2')]))
 
       expect(errors).toHaveLength(1)
       const error = errors[0] as CaptureError
@@ -337,7 +354,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender({ maxAttempts: 3 })
       fetch.mockResolvedValue(makeResponse(200, { results: { u1: { result: 'retry' } } }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(3)
       const error = errors[0] as CaptureError
@@ -351,7 +368,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, 'not-json{'))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
@@ -367,7 +384,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, body))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
@@ -379,7 +396,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(status)).mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(2)
       expect(errors).toEqual([])
@@ -389,7 +406,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(429, '', { 'Retry-After': '1' }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       const error = errors[0] as CaptureError
@@ -401,7 +418,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(status))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(errors).toHaveLength(1)
@@ -412,7 +429,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender({ maxAttempts: 4 })
       fetch.mockResolvedValue(makeResponse(503))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(4)
       expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
@@ -425,7 +442,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeStallingResponse(503, cancel))
         .mockResolvedValueOnce(makeResponse(503, 'still unavailable'))
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(999)
       expect(fetch).toHaveBeenCalledTimes(1)
       expect(sleeps).toEqual([])
@@ -449,7 +466,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockRejectedValueOnce(new Error('ECONNRESET')).mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(fetch).toHaveBeenCalledTimes(2)
       expect(errors).toEqual([])
@@ -459,7 +476,7 @@ describe('V1CaptureSender', () => {
       const { sender, fetch, errors } = makeSender({ maxAttempts: 3 })
       fetch.mockRejectedValue(new Error('timeout'))
 
-      await sender.sendV1Batch([msg('u1'), msg('u2')])
+      await sender.send(v1Events([msg('u1'), msg('u2')]))
 
       expect(fetch).toHaveBeenCalledTimes(3)
       const error = errors[0] as CaptureError
@@ -472,11 +489,13 @@ describe('V1CaptureSender', () => {
       fetch.mockImplementation(
         (_url, options) =>
           new Promise<PostHogFetchResponse>((_resolve, reject) => {
-            options.signal.addEventListener('abort', () => reject(new Error('custom fetch abort')), { once: true })
+            options.signal.addEventListener('abort', () => reject(new Error('custom fetch abort')), {
+              once: true,
+            })
           })
       )
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(1000)
       await sendPromise
 
@@ -499,7 +518,7 @@ describe('V1CaptureSender', () => {
           })
       )
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(1000)
       await sendPromise
 
@@ -519,7 +538,7 @@ describe('V1CaptureSender', () => {
         .mockImplementationOnce(() => Promise.resolve(makeStallingResponse(200, cancel)))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(1000)
       await sendPromise
 
@@ -537,12 +556,14 @@ describe('V1CaptureSender', () => {
         const response = makeStallingResponse(200, cancel)
         response.text = () =>
           new Promise<string>((_resolve, reject) => {
-            options.signal.addEventListener('abort', () => reject(new Error('custom body abort')), { once: true })
+            options.signal.addEventListener('abort', () => reject(new Error('custom body abort')), {
+              once: true,
+            })
           })
         return Promise.resolve(response)
       })
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(1000)
       await sendPromise
 
@@ -565,7 +586,7 @@ describe('V1CaptureSender', () => {
         return Promise.resolve(makeStallingResponse(200, cancel))
       })
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(1000)
       await vi.advanceTimersByTimeAsync(1000)
       await sendPromise
@@ -589,7 +610,7 @@ describe('V1CaptureSender', () => {
       const cancel = vi.fn<[], Promise<void>>().mockResolvedValue(undefined)
       fetch.mockResolvedValue(makeStallingResponse(400, cancel))
 
-      const sendPromise = sender.sendV1Batch([msg('u1')])
+      const sendPromise = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(1000)
       await sendPromise
 
@@ -603,12 +624,128 @@ describe('V1CaptureSender', () => {
     })
   })
 
+  describe('unsent events (keepUnsent)', () => {
+    it('returns events whose last attempt got no response, without reporting them', async () => {
+      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      fetch.mockRejectedValue(new Error('ECONNREFUSED'))
+      const events = v1Events([msg('u1'), msg('u2')])
+
+      const unsent = await sender.send(events, { keepUnsent: true })
+
+      expect(fetch).toHaveBeenCalledTimes(2)
+      expect(unsent).toEqual(events)
+      expect(errors).toEqual([])
+    })
+
+    it('reports server drops and returns only the retry events a later transport failure left unsent', async () => {
+      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      fetch
+        .mockResolvedValueOnce(
+          makeResponse(200, {
+            results: { u1: { result: 'drop', details: 'billing' }, u2: { result: 'retry' } },
+          })
+        )
+        .mockRejectedValueOnce(new Error('ECONNRESET'))
+      const events = v1Events([msg('u1'), msg('u2'), msg('u3')])
+
+      const unsent = await sender.send(events, { keepUnsent: true })
+
+      expect(unsent).toEqual([events[1]])
+      expect(errors).toHaveLength(1)
+      expect(errors[0]).toMatchObject({ drops: [{ uuid: 'u1', details: 'billing' }], retryExhausted: [] })
+    })
+
+    it.each<[string, () => PostHogFetchResponse]>([
+      ['an exhausted retryable status', () => makeResponse(500)],
+      ['a terminal status', () => makeResponse(400)],
+      ['an unparseable 2xx', () => makeResponse(200, 'not json')],
+    ])('reports and does not return events after %s', async (_name, response) => {
+      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      fetch.mockImplementation(() => Promise.resolve(response()))
+
+      const unsent = await sender.send(v1Events([msg('u1')]), { keepUnsent: true })
+
+      expect(unsent).toEqual([])
+      expect(errors).toHaveLength(1)
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
+    })
+
+    it('reports and does not return retry events still pending when the budget runs out on a 2xx', async () => {
+      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      fetch.mockResolvedValue(makeResponse(200, { results: { u1: { result: 'retry' } } }))
+
+      const unsent = await sender.send(v1Events([msg('u1')]), { keepUnsent: true })
+
+      expect(unsent).toEqual([])
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
+    })
+  })
+
+  describe('abort signal', () => {
+    it('makes no request once the signal is aborted', async () => {
+      const { sender, fetch, errors } = makeSender()
+      const controller = new AbortController()
+      controller.abort(new Error('shutdown deadline'))
+      const events = v1Events([msg('u1')])
+
+      expect(await sender.send(events, { signal: controller.signal, keepUnsent: true })).toEqual(events)
+      expect(fetch).not.toHaveBeenCalled()
+      expect(errors).toEqual([])
+    })
+
+    it('stops waiting for the next attempt when aborted during backoff', async () => {
+      const controller = new AbortController()
+      const { sender, fetch, errors } = makeSender({ maxAttempts: 4 }, { sleep: () => new Promise(() => {}) })
+      fetch.mockResolvedValue(makeResponse(503))
+
+      const sendPromise = sender.send(v1Events([msg('u1')]), { signal: controller.signal })
+      await vi.advanceTimersByTimeAsync(0)
+      controller.abort(new Error('shutdown deadline'))
+      await sendPromise
+
+      expect(fetch).toHaveBeenCalledTimes(1)
+      expect(errors).toHaveLength(1)
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
+    })
+
+    it('aborts a request still waiting for response headers', async () => {
+      const controller = new AbortController()
+      const { sender, fetch } = makeSender({ maxAttempts: 4, requestTimeoutMs: 60_000 })
+      fetch.mockImplementation(() => new Promise(() => {}))
+      const events = v1Events([msg('u1')])
+
+      const sendPromise = sender.send(events, { signal: controller.signal, keepUnsent: true })
+      await vi.advanceTimersByTimeAsync(100)
+      controller.abort(new Error('shutdown deadline'))
+
+      expect(await sendPromise).toEqual(events)
+      expect(fetch).toHaveBeenCalledTimes(1)
+      expect(fetch.mock.calls[0][1].signal.aborted).toBe(true)
+      expect(vi.getTimerCount()).toBe(0)
+    })
+
+    it('stops reading a stalled HTTP error body and still reports the status', async () => {
+      const controller = new AbortController()
+      const { sender, fetch, errors } = makeSender({ maxAttempts: 1, requestTimeoutMs: 60_000 })
+      fetch.mockResolvedValue(makeStallingResponse(503, vi.fn().mockResolvedValue(undefined)))
+
+      const sendPromise = sender.send(v1Events([msg('u1')]), { signal: controller.signal })
+      await vi.advanceTimersByTimeAsync(100)
+      controller.abort(new Error('shutdown deadline'))
+      await sendPromise
+
+      expect(errors).toHaveLength(1)
+      expect(((errors[0] as CaptureError).cause as Error).message).toBe('Capture V1 request failed with HTTP 503')
+      expect(vi.getTimerCount()).toBe(0)
+    })
+  })
+
   describe('backoff and Retry-After', () => {
     it('uses exponential backoff between attempts', async () => {
       const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 4 })
       fetch.mockResolvedValue(makeResponse(503))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([100, 200, 400])
     })
@@ -621,7 +758,7 @@ describe('V1CaptureSender', () => {
       })
       fetch.mockResolvedValue(makeResponse(503))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([10_000, 15_000, 15_000])
     })
@@ -632,7 +769,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '5' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([5000])
     })
@@ -643,30 +780,38 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '1' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([10_000])
     })
 
     it('clamps a huge Retry-After to maxBackoffMs', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxBackoffMs: 30_000, maxAttempts: 2 })
+      const { sender, fetch, sleeps } = makeSender({
+        initialRetryDelayMs: 100,
+        maxBackoffMs: 30_000,
+        maxAttempts: 2,
+      })
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '9999' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([30_000])
     })
 
     it('parses an HTTP-date Retry-After as a delay from now', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxBackoffMs: 60_000, maxAttempts: 2 })
+      const { sender, fetch, sleeps } = makeSender({
+        initialRetryDelayMs: 100,
+        maxBackoffMs: 60_000,
+        maxAttempts: 2,
+      })
       // 20s after the fixed clock start.
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': 'Mon, 01 Jan 2024 00:00:20 GMT' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([20_000])
     })
@@ -677,7 +822,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': 'Mon, 01 Jan 2020 00:00:00 GMT' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([100])
     })
@@ -688,7 +833,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': retryAfter }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([100])
     })
@@ -699,7 +844,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '9'.repeat(400) }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([100])
     })
@@ -710,7 +855,7 @@ describe('V1CaptureSender', () => {
         .mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'retry' } } }, { 'Retry-After': '3' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       expect(sleeps).toEqual([3000])
     })
@@ -740,7 +885,7 @@ describe('V1CaptureSender', () => {
 
       const sender = new V1CaptureSender(baseConfig, { fetch, onError: (e) => errors.push(e) })
       // No injected sleep: the retry backoff schedules a real (fake-timer) setTimeout we must advance.
-      const done = sender.sendV1Batch([msg('u1')])
+      const done = sender.send(v1Events([msg('u1')]))
       await vi.advanceTimersByTimeAsync(baseConfig.initialRetryDelayMs)
       await done
 
@@ -751,13 +896,48 @@ describe('V1CaptureSender', () => {
       expect(headers['PostHog-Request-Timestamp']).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/)
     })
 
+    it('cancels the backoff timer when aborted', async () => {
+      const fetch = vi.fn<[string, any], Promise<PostHogFetchResponse>>().mockResolvedValue(makeResponse(503))
+      const controller = new AbortController()
+      const sender = new V1CaptureSender({ ...baseConfig, initialRetryDelayMs: 10_000 }, { fetch, onError: () => {} })
+
+      const done = sender.send(v1Events([msg('u1')]), { signal: controller.signal })
+      await vi.advanceTimersByTimeAsync(0)
+      controller.abort()
+      await done
+
+      expect(fetch).toHaveBeenCalledTimes(1)
+      expect(vi.getTimerCount()).toBe(0)
+    })
+
+    it('removes every abort listener it adds to a long-lived signal', async () => {
+      const fetch = vi
+        .fn<[string, any], Promise<PostHogFetchResponse>>()
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(200, { results: {} }))
+      const { signal } = new AbortController()
+      const added = vi.spyOn(signal, 'addEventListener')
+      const removed = vi.spyOn(signal, 'removeEventListener')
+      const sender = new V1CaptureSender(baseConfig, { fetch, onError: () => {} })
+
+      const done = sender.send(v1Events([msg('u1')]), { signal })
+      await vi.advanceTimersByTimeAsync(baseConfig.initialRetryDelayMs)
+      await done
+
+      expect(fetch).toHaveBeenCalledTimes(2)
+      const removedListeners = new Set(removed.mock.calls.map(([, listener]) => listener))
+      const leaked = added.mock.calls.filter(([, listener]) => !removedListeners.has(listener))
+      expect(added.mock.calls.length).toBeGreaterThan(0)
+      expect(leaked).toEqual([])
+    })
+
     it('uses the real gzip compressor when not injected', async () => {
       const fetch = vi
         .fn<[string, any], Promise<PostHogFetchResponse>>()
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       const sender = new V1CaptureSender({ ...baseConfig, compressionEnabled: true }, { fetch, onError: () => {} })
-      await sender.sendV1Batch([msg('u1')])
+      await sender.send(v1Events([msg('u1')]))
 
       // The default compressor is the platform gzip codec: it compresses where
       // supported and transparently falls back to an uncompressed string where it
diff --git a/packages/node/src/__tests__/capture-v1/transform.spec.ts b/packages/node/src/__tests__/capture-v1/transform.spec.ts
index edf4cb7908..9698d03776 100644
--- a/packages/node/src/__tests__/capture-v1/transform.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/transform.spec.ts
@@ -1,6 +1,6 @@
 import type { JsonType, PostHogEventProperties } from '@posthog/core'
 
-import { buildV1Batch, buildV1Event, coerceBool, coerceString } from '@/capture-v1/transform'
+import { buildV1Event, coerceBool, coerceString } from '@/capture-v1/transform'
 
 function baseMessage(overrides: PostHogEventProperties = {}): PostHogEventProperties {
   return {
@@ -263,27 +263,4 @@ describe('capture v1 transform', () => {
       expect(message).toEqual(snapshot)
     })
   })
-
-  describe('buildV1Batch', () => {
-    it('wraps events with created_at and omits historical_migration by default', () => {
-      const batch = buildV1Batch([baseMessage(), baseMessage({ event: 'second' })], {
-        createdAt: '2024-01-15T10:30:01.000Z',
-      })
-
-      expect(batch.created_at).toBe('2024-01-15T10:30:01.000Z')
-      expect(batch.batch).toHaveLength(2)
-      expect(batch.batch[1].event).toBe('second')
-      expect(batch).not.toHaveProperty('historical_migration')
-    })
-
-    it('includes historical_migration only when true', () => {
-      const batch = buildV1Batch([baseMessage()], { createdAt: 'now', historicalMigration: true })
-      expect(batch.historical_migration).toBe(true)
-    })
-
-    it('produces an empty batch array for no messages', () => {
-      const batch = buildV1Batch([], { createdAt: 'now' })
-      expect(batch.batch).toEqual([])
-    })
-  })
 })
diff --git a/packages/node/src/__tests__/immediate-delivery.spec.ts b/packages/node/src/__tests__/immediate-delivery.spec.ts
index 9a97dcf66b..9bcf8834a3 100644
--- a/packages/node/src/__tests__/immediate-delivery.spec.ts
+++ b/packages/node/src/__tests__/immediate-delivery.spec.ts
@@ -52,8 +52,7 @@ describe('immediate write responses', () => {
     expect(fetch).toHaveBeenCalledTimes(1)
   })
 
-  // Skipped: the capture sender reads a terminal error body for up to requestTimeout, which outlasts this shutdown budget.
-  it.skip('drains queued events within the shutdown budget when an immediate error body stalls', async () => {
+  it('drains queued events within the shutdown budget when an immediate error body stalls', async () => {
     let respond!: (response: Response) => void
     fetch.mockImplementationOnce(
       () =>
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index 85972cc57b..530ea011f4 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -645,31 +645,58 @@ describe('PostHog Node.js', () => {
   })
 
   describe('maxQueueSize', () => {
-    it('defaults to 10000, higher than the shared core default of 1000', () => {
-      const ph = new PostHog('TEST_API_KEY', {
-        host: 'http://example.com',
-      })
+    const queueCaps = (options: PostHogOptions): { analytics: number; ai: number } => {
+      const ph = new PostHog('TEST_API_KEY', { host: 'http://example.com', ...options }) as any
+      return {
+        analytics: ph._captureLaneConfig('/i/v1/analytics/events').maxQueueSize,
+        ai: ph._captureLaneConfig('/i/v1/ai/events').maxQueueSize,
+      }
+    }
 
-      expect((ph as any).maxQueueSize).toBe(10000)
+    it('defaults to 10000, higher than the shared core default of 1000', () => {
+      expect(queueCaps({})).toEqual({ analytics: 10000, ai: 1000 })
     })
 
-    it('still honors an explicit override', () => {
-      const ph = new PostHog('TEST_API_KEY', {
-        host: 'http://example.com',
-        maxQueueSize: 42,
-        flushAt: 1,
-      })
-
-      expect((ph as any).maxQueueSize).toBe(42)
+    it('still honors an explicit override, for analytics events only', () => {
+      expect(queueCaps({ maxQueueSize: 42, flushAt: 1 })).toEqual({ analytics: 42, ai: 1000 })
     })
 
     it('keeps the Node default when a wrapper forwards maxQueueSize: undefined', () => {
+      expect(queueCaps({ maxQueueSize: undefined })).toEqual({ analytics: 10000, ai: 1000 })
+    })
+
+    it('drops the oldest analytics events beyond the cap and reports them once', async () => {
+      let release!: () => void
+      mockedFetch.mockImplementationOnce(
+        () => new Promise((resolve) => (release = () => resolve(new Response('{"results":{}}', { status: 200 }))))
+      )
+      mockedFetch.mockResolvedValue(new Response('{"results":{}}', { status: 200 }))
       const ph = new PostHog('TEST_API_KEY', {
         host: 'http://example.com',
-        maxQueueSize: undefined,
+        maxQueueSize: 2,
+        flushAt: 1,
+        fetchRetryCount: 0,
+        disableCompression: true,
       })
+      const errors: CaptureError[] = []
+      ph.on('error', (error) => errors.push(error))
+      try {
+        ph.capture({ distinctId: 'u', event: 'in-flight' })
+        await vi.advanceTimersByTimeAsync(0)
+        for (const event of ['dropped-1', 'dropped-2', 'kept-1', 'kept-2']) {
+          ph.capture({ distinctId: 'u', event })
+        }
+        await vi.advanceTimersByTimeAsync(0)
+        release()
+        await ph.flush()
 
-      expect((ph as any).maxQueueSize).toBe(10000)
+        expect(sentEvents(mockedFetch).map((event) => event.event)).toEqual(['in-flight', 'kept-1', 'kept-2'])
+        expect(errors).toHaveLength(1)
+        expect(errors[0].drops).toHaveLength(2)
+        expect(errors[0].message).toContain('2 because the queue was full (2 events)')
+      } finally {
+        await ph.shutdown()
+      }
     })
   })
 
@@ -1045,17 +1072,27 @@ describe('PostHog Node.js', () => {
 
         await vi.advanceTimersByTimeAsync(0)
         expect(mockedFetch).toHaveBeenCalledTimes(1)
+        const firstBatch = sentEvents(mockedFetch).map((event) => event.uuid)
+        expect(firstBatch).toHaveLength(20)
+
+        // A network failure keeps the batch, so the one coalesced follow-up flush resends it.
         rejectFetch.shift()!(new Error('network down'))
         await vi.advanceTimersByTimeAsync(0)
-        expect(mockedFetch).toHaveBeenCalledTimes(1)
+        expect(mockedFetch).toHaveBeenCalledTimes(2)
+        expect(
+          sentEvents(mockedFetch)
+            .slice(20)
+            .map((event) => event.uuid)
+        ).toEqual(firstBatch)
 
-        // The failed batch is reported and consumed, so two new events are needed to reach flushAt again.
+        // More captures while that resend is in flight still coalesce into a single follow-up.
         ph.capture({ event: 'offline-event-20', distinctId: '123' })
         ph.capture({ event: 'offline-event-21', distinctId: '123' })
         await vi.advanceTimersByTimeAsync(0)
         expect(mockedFetch).toHaveBeenCalledTimes(2)
         rejectFetch.shift()!(new Error('network down'))
         await vi.advanceTimersByTimeAsync(0)
+        expect(mockedFetch).toHaveBeenCalledTimes(3)
       } finally {
         mockedFetch.mockResolvedValue(new Response('{}', { status: 200 }))
         for (const reject of rejectFetch) {
@@ -1152,10 +1189,10 @@ describe('PostHog Node.js', () => {
       }
 
       await ph.shutdown()
-      // flush waits for all pending capture preparation before sending the batch
-      const batchEvents = getLastBatchEvents()
-      expect(batchEvents?.length).toEqual(10)
-      expect(batchEvents?.[batchEvents?.length - 1]).toMatchObject({
+      // shutdown waits for all pending capture preparation, so every event is sent
+      const batchEvents = sentEvents(mockedFetch)
+      expect(batchEvents.map((event) => event.distinct_id)).toEqual(['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'])
+      expect(batchEvents[batchEvents.length - 1]).toMatchObject({
         // last event in batch
         distinct_id: '9',
         event: 'test-event',
@@ -1167,8 +1204,6 @@ describe('PostHog Node.js', () => {
         timestamp: expect.any(String),
       })
       expect(10).toEqual(logSpy.mock.calls.filter((call) => call[1].includes('capture')).length)
-      // all pending capture preparation is joined before the first flush, so one batch sends all events
-      expect(1).toEqual(logSpy.mock.calls.filter((call) => call[1].includes('flush')).length)
     })
   })
 
@@ -1213,14 +1248,17 @@ describe('PostHog Node.js', () => {
       ph.capture({ event: 'test-event', distinctId: '123' })
 
       // shutdown() waits for capture preparation, then flushes. The capture sender aborts the
-      // hanging request after requestTimeout and reports the batch on the error channel.
+      // hanging request after requestTimeout; with no HTTP response the event stays queued, and
+      // shutdown reports it as unsent when it ends.
       await ph.shutdown()
 
       expect(hangingFetch).toHaveBeenCalledTimes(1)
+      expect(hangingFetch.mock.calls[0][1]?.signal?.aborted).toBe(true)
       expect(errors).toHaveLength(1)
       expect(errors[0]).toBeInstanceOf(CaptureError)
       expect(errors[0].endpoint).toBe('/i/v1/analytics/events')
-      expect(errors[0].cause.name).toBe('AbortError')
+      expect(errors[0].retryExhausted).toHaveLength(1)
+      expect(errors[0].message).toContain('still queued when shutdown ended')
     }, 10000)
   })
 
diff --git a/packages/node/src/__tests__/server-wire-snapshots.spec.ts b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
index 025f17762e..3e4294f814 100644
--- a/packages/node/src/__tests__/server-wire-snapshots.spec.ts
+++ b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
@@ -3,6 +3,7 @@
 import type { PostHogFetchOptions } from '@posthog/core'
 
 import { V1CaptureSender } from '@/capture-v1/sender'
+import { serializeV1Event } from '@/capture-v1/serialize'
 import { PostHog } from '@/entrypoints/index.node'
 import { captureCalls, v1Response } from './utils'
 import { okResponse } from './utils/v1-wiring'
@@ -96,7 +97,7 @@ describe('server wire snapshots', () => {
       }
     )
 
-    await sender.sendV1Batch([
+    const messages = [
       {
         event: 'all-valid-sentinels',
         distinct_id: 'person-1',
@@ -131,7 +132,8 @@ describe('server wire snapshots', () => {
           ordinary: true,
         },
       },
-    ])
+    ]
+    await sender.send(messages.map(serializeV1Event))
 
     expect(mockedFetch).toHaveBeenCalledTimes(1)
     expect(snapshotRequest(mockedFetch.mock.calls[0] as FetchCall)).toMatchSnapshot()
diff --git a/packages/node/src/__tests__/waituntil-flush.spec.ts b/packages/node/src/__tests__/waituntil-flush.spec.ts
index e41c33f50d..5daa98d88a 100644
--- a/packages/node/src/__tests__/waituntil-flush.spec.ts
+++ b/packages/node/src/__tests__/waituntil-flush.spec.ts
@@ -1,6 +1,6 @@
 import { PostHog } from '@/entrypoints/index.node'
 
-import { captureRequests, sentEventsOf, v1Response } from './utils'
+import { captureCalls, captureRequests, sentEventsOf, v1Response } from './utils'
 
 vi.mock('../version', () => ({ version: '1.2.3' }))
 
@@ -13,7 +13,7 @@ function getFlushedBatches(): any[][] {
 }
 
 describe('flush combines events and spans', () => {
-  it('waits for the span export even when the event flush rejects', async () => {
+  it('waits for the span export even when the event delivery fails', async () => {
     // `Promise.all` settled on the event rejection, so a serverless host could
     // freeze the invocation with the span request still open.
     vi.useRealTimers()
@@ -25,7 +25,7 @@ describe('flush combines events and spans', () => {
         order.push('traces-done')
         return { status: 200, text: () => Promise.resolve('{}'), json: () => Promise.resolve({}) } as any
       }
-      return v1Response()
+      return new Response('events endpoint down', { status: 400 })
     })
     const posthog = new PostHog('key', {
       host: 'http://example.com',
@@ -34,19 +34,23 @@ describe('flush combines events and spans', () => {
       traces: { serviceName: 'svc' },
       disableCompression: true,
     })
-    // Fail the send seam itself: only the legacy sender throws when the events request fails.
-    vi.spyOn(posthog as any, 'sendBatch').mockRejectedValue(new Error('events endpoint down'))
-    posthog.capture({ distinctId: 'u', event: 'e' })
-    posthog.startSpan('s').end()
+    const errors: unknown[] = []
+    posthog.on('error', (error) => errors.push(error))
+    try {
+      posthog.capture({ distinctId: 'u', event: 'e' })
+      posthog.startSpan('s').end()
 
-    await expect(posthog.flush()).rejects.toThrow()
-    order.push('flush-returned')
+      await expect(posthog.flush()).resolves.toBeUndefined()
+      order.push('flush-returned')
 
-    // Exact, not an index comparison: before the fix `traces-done` is absent
-    // when flush returns, and `indexOf` gives -1, which passes any `lessThan`.
-    expect(order).toEqual(['traces-start', 'traces-done', 'flush-returned'])
-    await posthog.shutdown()
-    vi.useFakeTimers()
+      // Exact, not an index comparison: before the fix `traces-done` is absent
+      // when flush returns, and `indexOf` gives -1, which passes any `lessThan`.
+      expect(order).toEqual(['traces-start', 'traces-done', 'flush-returned'])
+      expect(errors).toEqual([expect.objectContaining({ name: 'CaptureError', retryExhausted: [expect.any(String)] })])
+    } finally {
+      await posthog.shutdown()
+      vi.useFakeTimers()
+    }
   })
 })
 
@@ -164,6 +168,30 @@ describe('waitUntil debounced flush', () => {
       }
     })
 
+    it('drains both capture lanes before resolving the waitUntil promise', async () => {
+      let releaseAi!: () => void
+      mockedFetch.mockImplementation((url: any) =>
+        String(url).includes('/i/v1/ai/events')
+          ? new Promise((resolve) => (releaseAi = () => resolve(v1Response())))
+          : Promise.resolve(v1Response())
+      )
+      const settled = vi.fn()
+
+      posthog.capture({ distinctId: 'user-1', event: 'analytics_event' })
+      posthog.captureAi({ distinctId: 'user-1', event: '$ai_generation' })
+      await vi.advanceTimersByTimeAsync(0)
+      const waitUntilPromise = mockWaitUntil.mock.calls[0][0] as Promise<unknown>
+      void waitUntilPromise.then(settled)
+      await vi.advanceTimersByTimeAsync(DEBOUNCE_MS)
+
+      expect(getFlushedBatches().map((batch) => batch.map(({ event }) => event))).toEqual([['analytics_event']])
+      expect(captureCalls(mockedFetch, '/i/v1/ai/events')).toHaveLength(1)
+      expect(settled).not.toHaveBeenCalled()
+
+      releaseAi()
+      await expect(waitUntilPromise).resolves.toBeUndefined()
+    })
+
     it('does not activate debounced flush when no waitUntil in options', async () => {
       const posthogNoWaitUntil = new PostHog('TEST_API_KEY', {
         host: 'http://example.com',
diff --git a/packages/node/src/ai-capture/batching.ts b/packages/node/src/ai-capture/batching.ts
deleted file mode 100644
index c1955b17cc..0000000000
--- a/packages/node/src/ai-capture/batching.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { PostHogEventProperties, safeJsonStringify } from '@posthog/core'
-
-import { AI_BATCH_TARGET_BYTES, AI_MAX_EVENT_BYTES } from './routing'
-
-const encoder = new TextEncoder()
-
-export type AiBatchPartition = {
-  batches: PostHogEventProperties[][]
-  dropped: { event: string; bytes: number }[]
-}
-
-export function eventByteSize(message: PostHogEventProperties): number {
-  return encoder.encode(safeJsonStringify(message)).length
-}
-
-export function partitionAiBatch(
-  messages: (PostHogEventProperties | undefined)[],
-  maxEventBytes: number = AI_MAX_EVENT_BYTES,
-  targetBatchBytes: number = AI_BATCH_TARGET_BYTES
-): AiBatchPartition {
-  const batches: PostHogEventProperties[][] = []
-  const dropped: { event: string; bytes: number }[] = []
-  let current: PostHogEventProperties[] = []
-  let currentBytes = 0
-
-  for (const message of messages) {
-    if (message === undefined) {
-      continue
-    }
-    const bytes = eventByteSize(message)
-    if (bytes > maxEventBytes) {
-      dropped.push({ event: typeof message.event === 'string' ? message.event : 'unknown', bytes })
-      continue
-    }
-    if (current.length > 0 && currentBytes + bytes > targetBatchBytes) {
-      batches.push(current)
-      current = []
-      currentBytes = 0
-    }
-    current.push(message)
-    currentBytes += bytes
-  }
-  if (current.length > 0) {
-    batches.push(current)
-  }
-  return { batches, dropped }
-}
diff --git a/packages/node/src/ai-capture/routing.ts b/packages/node/src/ai-capture/routing.ts
index 3a4afc3263..535defb840 100644
--- a/packages/node/src/ai-capture/routing.ts
+++ b/packages/node/src/ai-capture/routing.ts
@@ -1,5 +1 @@
 export const AI_CAPTURE_ROUTE = 'ai-capture'
-
-export const AI_MAX_EVENT_BYTES = 8 * 1024 * 1024
-
-export const AI_BATCH_TARGET_BYTES = 5 * 1024 * 1024
diff --git a/packages/node/src/capture-v1/sender.ts b/packages/node/src/capture-v1/sender.ts
index 0ec5611271..8fdb5cf71d 100644
--- a/packages/node/src/capture-v1/sender.ts
+++ b/packages/node/src/capture-v1/sender.ts
@@ -1,20 +1,61 @@
 import {
   type FetchLike,
-  type PostHogEventProperties,
   type PostHogFetchBodyBytes,
   type PostHogFetchOptions,
   type PostHogFetchResponse,
   gzipCompress,
-  safeJsonStringify,
   uuidv7,
 } from '@posthog/core'
 
 import { CaptureError, type CaptureDroppedEvent, type CaptureErrorParams } from './errors'
-import { buildV1Batch } from './transform'
-import type { CaptureEndpoint, V1BatchResponse, V1Event } from './types'
+import { type SerializedV1Event, buildV1Body } from './serialize'
+import type { CaptureEndpoint, V1BatchResponse } from './types'
 
 const DEFAULT_MAX_BACKOFF_MS = 30_000
 
+// Retry waits and request deadlines use ref'd timers, unlike safeSetTimeout, so an
+// awaited flush or shutdown keeps the process alive until the send finishes.
+/** Settles with `work`, or rejects with an `AbortError` as soon as `signal` aborts. */
+async function raceAbort<T>(work: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (!signal) {
+    return work
+  }
+  let onAbort!: () => void
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => {
+      const abortError = new Error('Capture V1 request aborted while compressing the body')
+      abortError.name = 'AbortError'
+      abortError.cause = signal.reason
+      reject(abortError)
+    }
+    if (signal.aborted) {
+      onAbort()
+    } else {
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+  })
+  try {
+    return await Promise.race([work, aborted])
+  } finally {
+    signal.removeEventListener('abort', onAbort)
+  }
+}
+
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve()
+    }
+    // A lane reuses one signal for every send, so a finished wait must not leave its listener behind.
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
 /** HTTP statuses the v1 backend wants retried. 429 is intentionally terminal in v1. */
 const RETRYABLE_STATUSES = new Set([408, 500, 502, 503, 504])
 
@@ -46,7 +87,8 @@ export interface V1CaptureSenderHooks {
   /** Surfaces partial/terminal delivery failures on the client error channel. */
   onError: (error: Error) => void
   now?: () => number
-  sleep?: (ms: number) => Promise<void>
+  /** Waits between attempts. The sender stops waiting when `signal` aborts, even if this does not. */
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>
   generateRequestId?: () => string
   compress?: (payload: string, isDebug?: boolean) => Promise<Blob | PostHogFetchBodyBytes | null>
 }
@@ -71,15 +113,15 @@ interface V1CaptureAttempt {
 }
 
 /**
- * Sends already-normalized events to one Capture V1 lane (`config.path`),
+ * Sends already-serialized events to one Capture V1 lane (`config.path`),
  * owning the full attempt loop: per-event partial retry, exponential backoff
  * clamped against `Retry-After`, v1 status classification, and surfacing drops
  * / undelivered events on the error channel. Used by both the batched and
  * immediate send paths.
  *
  * Never throws for a handled outcome: after exhausting its own attempt budget it
- * reports the failure via `onError` and resolves, so the caller's queue treats
- * the batch as consumed (the internal budget replaces the core queue-level retry).
+ * reports the failure via `onError` and resolves. Only events that never got an
+ * HTTP response can come back to the caller, and only with `keepUnsent`.
  */
 export class V1CaptureSender {
   private readonly config: V1CaptureSenderConfig
@@ -87,7 +129,7 @@ export class V1CaptureSender {
   private readonly fetchFn: FetchLike
   private readonly onError: (error: Error) => void
   private readonly now: () => number
-  private readonly sleep: (ms: number) => Promise<void>
+  private readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>
   private readonly generateRequestId: () => string
   private readonly compress: (payload: string, isDebug?: boolean) => Promise<Blob | PostHogFetchBodyBytes | null>
 
@@ -97,47 +139,50 @@ export class V1CaptureSender {
     this.fetchFn = hooks.fetch
     this.onError = hooks.onError
     this.now = hooks.now ?? Date.now
-    // Retry waits and request deadlines use ref'd timers, unlike safeSetTimeout, so an
-    // awaited flush or shutdown keeps the process alive until the send finishes.
-    this.sleep = hooks.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)))
+    this.sleep = hooks.sleep ?? abortableSleep
     this.generateRequestId = hooks.generateRequestId ?? uuidv7
     this.compress = hooks.compress ?? gzipCompress
   }
 
-  async sendV1Batch(messages: PostHogEventProperties[]): Promise<void> {
-    if (messages.length === 0) {
-      return
+  /** Sends `events` and resolves with the ones to queue again (always empty unless `keepUnsent`). */
+  async send<T extends SerializedV1Event>(events: T[], options: V1SendOptions = {}): Promise<T[]> {
+    if (events.length === 0) {
+      return []
     }
 
+    const { signal, keepUnsent = false } = options
     const requestId = this.generateRequestId()
     // created_at is generated once and stays stable across every retry.
     const createdAt = new Date(this.now()).toISOString()
-    const { batch } = buildV1Batch(messages, {
-      createdAt,
-      historicalMigration: this.config.historicalMigration,
-    })
-
     const url = `${this.config.host}${this.config.path}`
     const drops: CaptureDroppedEvent[] = []
-    let pending = batch
+    let pending = events
+
+    const unsent = (cause: unknown): T[] => {
+      if (keepUnsent) {
+        this.surfacePartialDrops(requestId, drops)
+        return pending
+      }
+      this.surfaceBatchFailure(requestId, drops, pending, cause)
+      return []
+    }
 
     // Guard against a misconfigured budget (e.g. fetchRetryCount: -1): always make
     // at least one attempt so a bad config surfaces a delivery error instead of
     // silently dropping the batch without ever sending or calling onError.
     const maxAttempts = Math.max(1, this.config.maxAttempts)
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      if (signal?.aborted) {
+        return unsent(signal.reason)
+      }
       const isLastAttempt = attempt === maxAttempts
-      const payload = safeJsonStringify({
-        created_at: createdAt,
-        ...(this.config.historicalMigration ? { historical_migration: true } : {}),
-        batch: pending,
-      })
+      const payload = buildV1Body(pending, { createdAt, historicalMigration: this.config.historicalMigration })
 
       let captureAttempt: V1CaptureAttempt | undefined
       let retryDelayMs: number | undefined
       try {
-        captureAttempt = await this.sendOnce(url, payload, attempt, requestId)
-        const { response, signal } = captureAttempt
+        captureAttempt = await this.sendOnce(url, payload, attempt, requestId, signal)
+        const { response, signal: attemptSignal } = captureAttempt
         const { status } = response
         if (status < 200 || status >= 300) {
           if (!isLastAttempt && RETRYABLE_STATUSES.has(status)) {
@@ -146,32 +191,41 @@ export class V1CaptureSender {
             retryDelayMs = this.backoffDelay(attempt, retryAfterMs)
           } else {
             const httpError = await this.buildHttpError(response, status, captureAttempt.waitFor)
-            return this.surfaceBatchFailure(requestId, drops, pending, httpError)
+            this.surfaceBatchFailure(requestId, drops, pending, httpError)
+            return []
           }
         } else {
           let parsed: V1BatchResponse
           try {
             parsed = await captureAttempt.waitFor(this.parseResponse(response))
           } catch (error) {
-            if (signal.aborted) {
+            if (attemptSignal.aborted) {
               throw error
             }
             // A 2xx we cannot parse is terminal — re-sending against a broken success would loop forever.
-            return this.surfaceBatchFailure(
+            this.surfaceBatchFailure(
               requestId,
               drops,
               pending,
               new Error(`Capture V1 returned an unparseable ${status} response body`)
             )
+            return []
           }
 
           const retryable = this.classify(pending, parsed, drops)
           if (retryable.length === 0) {
-            return this.surfacePartialDrops(requestId, drops)
+            this.surfacePartialDrops(requestId, drops)
+            return []
           }
           if (isLastAttempt) {
-            this.onError(this.captureError({ requestId, drops, retryExhausted: retryable.map((event) => event.uuid) }))
-            return
+            this.onError(
+              this.captureError({
+                requestId,
+                drops,
+                retryExhausted: retryable.map((event) => event.uuid),
+              })
+            )
+            return []
           }
           pending = retryable
           // A 200 partial-retry body can also carry Retry-After (e.g. rate-limited
@@ -185,8 +239,8 @@ export class V1CaptureSender {
         }
         // Connection/timeouts, including a timeout while consuming the response body,
         // are retried until the budget runs out.
-        if (isLastAttempt) {
-          return this.surfaceBatchFailure(requestId, drops, pending, transportError)
+        if (isLastAttempt || signal?.aborted) {
+          return unsent(transportError)
         }
         retryDelayMs = this.backoffDelay(attempt)
       } finally {
@@ -194,16 +248,43 @@ export class V1CaptureSender {
       }
 
       if (retryDelayMs !== undefined) {
-        await this.sleep(retryDelayMs)
+        await this.sleepUnlessAborted(retryDelayMs, signal)
       }
     }
+    return []
   }
 
-  private async sendOnce(url: string, payload: string, attempt: number, requestId: string): Promise<V1CaptureAttempt> {
+  private async sleepUnlessAborted(ms: number, signal: AbortSignal | undefined): Promise<void> {
+    if (!signal) {
+      return this.sleep(ms)
+    }
+    if (signal.aborted) {
+      return
+    }
+    let onAbort!: () => void
+    const aborted = new Promise<void>((resolve) => {
+      onAbort = resolve
+      signal.addEventListener('abort', onAbort, { once: true })
+    })
+    try {
+      await Promise.race([this.sleep(ms, signal), aborted])
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+    }
+  }
+
+  private async sendOnce(
+    url: string,
+    payload: string,
+    attempt: number,
+    requestId: string,
+    externalSignal: AbortSignal | undefined
+  ): Promise<V1CaptureAttempt> {
     const headers = this.buildHeaders(attempt, requestId)
     let body: string | Blob | PostHogFetchBodyBytes = payload
     if (this.config.compressionEnabled) {
-      const compressed = await this.compress(payload, this.config.isDebug)
+      // Compression runs on the libuv pool, so a busy pool must not hold the request past an external deadline.
+      const compressed = await raceAbort(this.compress(payload, this.config.isDebug), externalSignal)
       if (compressed !== null) {
         body = compressed
         headers['Content-Encoding'] = 'gzip'
@@ -214,21 +295,45 @@ export class V1CaptureSender {
     const controller = new AbortController()
     let timeoutPhase = 'waiting for response headers'
     let timer: ReturnType<typeof setTimeout> | undefined
+    let onExternalAbort: (() => void) | undefined
+    const stopListening = (): void => {
+      if (onExternalAbort) {
+        externalSignal?.removeEventListener('abort', onExternalAbort)
+      }
+    }
     // hooks.fetch is user-injectable, so it may ignore an abort signal while
     // resolving headers or reading the body. Race both phases against the same
     // deadline rather than relying only on standards-compliant fetch behavior.
     const deadline = new Promise<never>((_resolve, reject) => {
+      const abortWith = (error: Error): void => {
+        // Reject first so this phase-specific error wins even when an abort-aware
+        // custom fetch rejects synchronously from the abort event.
+        reject(error)
+        controller.abort(error)
+      }
       timer = setTimeout(() => {
         const timeoutError = new Error(
           `Capture V1 request timed out ${timeoutPhase} after ${this.config.requestTimeoutMs}ms`
         )
         timeoutError.name = 'AbortError'
-        // Reject first so this phase-specific error wins even when an abort-aware
-        // custom fetch rejects synchronously from the abort event.
-        reject(timeoutError)
-        controller.abort(timeoutError)
+        abortWith(timeoutError)
       }, this.config.requestTimeoutMs)
+      if (externalSignal) {
+        onExternalAbort = () => {
+          const abortError = new Error(`Capture V1 request aborted ${timeoutPhase}`)
+          abortError.name = 'AbortError'
+          abortError.cause = externalSignal.reason
+          abortWith(abortError)
+        }
+        if (externalSignal.aborted) {
+          onExternalAbort()
+        } else {
+          externalSignal.addEventListener('abort', onExternalAbort, { once: true })
+        }
+      }
     })
+    // Keeps an early abort from surfacing as an unhandled rejection before the race below observes it.
+    deadline.catch(() => {})
     try {
       const fetchPromise = this.fetchFn(url, { method: 'POST', headers, body, signal: controller.signal })
       let responseAccepted = false
@@ -258,6 +363,7 @@ export class V1CaptureSender {
           }
           cleanedUp = true
           clearTimeout(timer)
+          stopListening()
           if (controller.signal.aborted) {
             // The attempt deadline has already elapsed, so cleanup cannot wait
             // for a custom response body's cancellation promise to settle.
@@ -267,6 +373,7 @@ export class V1CaptureSender {
       }
     } catch (error) {
       clearTimeout(timer)
+      stopListening()
       throw error
     }
   }
@@ -293,9 +400,13 @@ export class V1CaptureSender {
    * a terminal failure, `retry` is returned for the next attempt, and
    * `ok`/`warning`/unknown/absent are terminal successes.
    */
-  private classify(pending: V1Event[], parsed: V1BatchResponse, drops: CaptureDroppedEvent[]): V1Event[] {
+  private classify<T extends SerializedV1Event>(
+    pending: T[],
+    parsed: V1BatchResponse,
+    drops: CaptureDroppedEvent[]
+  ): T[] {
     const results = parsed.results ?? {}
-    const retryable: V1Event[] = []
+    const retryable: T[] = []
     for (const event of pending) {
       const result = results[event.uuid]
       if (!result) {
@@ -370,7 +481,7 @@ export class V1CaptureSender {
   private surfaceBatchFailure(
     requestId: string,
     drops: CaptureDroppedEvent[],
-    pending: V1Event[],
+    pending: SerializedV1Event[],
     cause: unknown
   ): void {
     this.onError(this.captureError({ requestId, drops, retryExhausted: pending.map((event) => event.uuid), cause }))
diff --git a/packages/node/src/capture-v1/transform.ts b/packages/node/src/capture-v1/transform.ts
index 9ff4b9e210..d1ebd148ca 100644
--- a/packages/node/src/capture-v1/transform.ts
+++ b/packages/node/src/capture-v1/transform.ts
@@ -1,6 +1,6 @@
 import type { JsonType, PostHogEventProperties } from '@posthog/core'
 
-import type { V1Batch, V1Event, V1EventOptions } from './types'
+import type { V1Event, V1EventOptions } from './types'
 
 /**
  * Coerce a value to a boolean the way the capture server does, or return
@@ -150,18 +150,3 @@ export function buildV1Event(message: PostHogEventProperties): V1Event {
     properties,
   }
 }
-
-/** Build a Capture V1 batch envelope from already-normalized queued messages. */
-export function buildV1Batch(
-  messages: PostHogEventProperties[],
-  { createdAt, historicalMigration }: { createdAt: string; historicalMigration?: boolean }
-): V1Batch {
-  const batch: V1Batch = {
-    created_at: createdAt,
-    batch: messages.map(buildV1Event),
-  }
-  if (historicalMigration) {
-    batch.historical_migration = true
-  }
-  return batch
-}
diff --git a/packages/node/src/capture-v1/types.ts b/packages/node/src/capture-v1/types.ts
index dad3db093f..559e90a20e 100644
--- a/packages/node/src/capture-v1/types.ts
+++ b/packages/node/src/capture-v1/types.ts
@@ -36,16 +36,6 @@ export interface V1Event {
   properties: PostHogEventProperties
 }
 
-/**
- * The Capture V1 batch envelope. Unlike v0 there is no `api_key` (Bearer auth)
- * and no `sent_at`. `historical_migration` is omitted when false.
- */
-export interface V1Batch {
-  created_at: string
-  historical_migration?: boolean
-  batch: V1Event[]
-}
-
 /**
  * Per-event result codes in a v1 2xx response body. Unknown strings are
  * tolerated as terminal success for forward compatibility.
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index 4d10338e4f..413adf67c6 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -23,7 +23,6 @@ import {
   resolveMetricsConfig,
   resolveTracesConfig,
   runWithActiveSpan,
-  RetriableOptions,
   raceWithTimeout,
   safeSetTimeout,
   SyncSpanContextManager,
@@ -73,8 +72,15 @@ import { PostHogMemoryStorage } from './storage-memory'
 import { ContextData, ContextOptions, IPostHogContext } from './extensions/context/types'
 import { V1CaptureSender, type V1CaptureSenderConfig } from './capture-v1/sender'
 import { AI_CAPTURE_ENDPOINT, ANALYTICS_CAPTURE_ENDPOINT, type CaptureEndpoint } from './capture-v1/types'
-import { partitionAiBatch } from './ai-capture/batching'
-import { AI_CAPTURE_ROUTE, AI_MAX_EVENT_BYTES } from './ai-capture/routing'
+import type { CaptureError } from './capture-v1/errors'
+import { CaptureLane, type CaptureLaneConfig } from './capture-lane/lane'
+import {
+  AI_MAX_PROPERTIES_BYTES,
+  AI_MAX_QUEUE_SIZE,
+  ANALYTICS_MAX_EVENT_BYTES,
+  CAPTURE_BATCH_TARGET_BYTES,
+} from './capture-lane/limits'
+import { AI_CAPTURE_ROUTE } from './ai-capture/routing'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
 // so the fastest a poller should ever be set is 100ms.
@@ -86,9 +92,6 @@ const WAITUNTIL_DEBOUNCE_MS = 50
 const WAITUNTIL_MAX_WAIT_MS = 500
 const DEFAULT_NODE_HOST = 'https://us.i.posthog.com'
 
-/** Queue route for `capture()` events; its queue is the historical {@link PostHogPersistedProperty.Queue}. */
-const ANALYTICS_ROUTE = 'analytics'
-
 // Process-wide dedup for deprecation warnings — without this, calling a deprecated
 // method in a loop would spam logs. Matches Python's `warnings.warn` default-dedup behavior.
 const _emittedDeprecations = new Set<string>()
@@ -163,12 +166,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   private _traces?: PostHogTraces
   private _spanContext?: SpanContextManager
 
-  private readonly _captureSenders = new Map<CaptureEndpoint, V1CaptureSender>()
+  // Created on first use, so a client that never calls captureAi has no AI lane.
+  private readonly _captureLanes = new Map<CaptureEndpoint, CaptureLane>()
   /** Whether this client captures full AI content: see `enableFullAiCapture` in `PostHogOptions`. */
   public readonly enableFullAiCapture: boolean
   /** Whether PostHog AI integrations redact content: see `privacyMode` in `PostHogOptions`. */
   public readonly privacyMode: boolean
-  private _aiCaptureRouteActive = false
 
   // Feature flag overrides for local testing/development
   private _flagOverrides?: Record<string, FeatureFlagValue>
@@ -310,24 +313,71 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     this.maxCacheSize = normalizedOptions.maxCacheSize || MAX_CACHE_SIZE
   }
 
+  /** Queues the event on its capture lane instead of the core queue. */
   protected override enqueue(
     type: string,
     message: any,
     options?: PostHogCaptureOptions,
     explicitRoute?: string
   ): void {
-    super.enqueue(type, message, options, explicitRoute)
+    this.wrap(() => {
+      if (this.optedOut) {
+        this._events.emit(type, `Library is disabled. Not sending event. To re-enable, call posthog.optIn()`)
+        return
+      }
+      const prepared = this._prepareLaneMessage(message, options)
+      if (prepared === null) {
+        return
+      }
+      this._captureLane(explicitRoute).enqueue(prepared)
+      this._events.emit(type, prepared)
+    })
     this.scheduleDebouncedFlush()
   }
 
+  /** Sends the event through its capture lane's sender, without queueing it. */
+  protected override async sendImmediate(
+    type: string,
+    message: any,
+    options?: PostHogCaptureOptions,
+    explicitRoute?: string
+  ): Promise<void> {
+    if (this.disabled) {
+      this._logger.warn('The client is disabled')
+      return
+    }
+    if (!this._isInitialized) {
+      await this._initPromise
+    }
+    if (this.optedOut) {
+      this._events.emit(type, `Library is disabled. Not sending event. To re-enable, call posthog.optIn()`)
+      return
+    }
+    const prepared = this._prepareLaneMessage(message, options)
+    if (prepared === null) {
+      return
+    }
+    try {
+      await this._captureLane(explicitRoute).sendImmediate(prepared)
+    } catch (err) {
+      this._events.emit('error', err)
+    }
+  }
+
+  private _prepareLaneMessage(message: any, options?: PostHogCaptureOptions): PostHogEventProperties | null {
+    const prepared = this.processBeforeEnqueue(this.prepareMessage(message, options))
+    return prepared === null ? null : this.normalizeMessage(prepared)
+  }
+
   /**
    * Concurrent so a serverless handler waits for one round trip, not two. A
    * failed span export leaves the spans queued rather than rejecting, since
    * callers already treat `flush()` as safe to leave unwrapped.
    */
-  private _flushEventsAndSpans(skipThrottledSpans = false): Promise<void> {
-    const events = this.flushWithPendingPromises()
-    if (!this._traces || (skipThrottledSpans && this._traces.throttled)) {
+  private _flushEventsAndSpans(): Promise<void> {
+    // Pending captures land on their lanes first, so this flush sends them too.
+    const events = this.flushWithPendingPromises().then(() => this._flushCaptureLanes())
+    if (!this._traces) {
       return events
     }
     // Settled, not `all`: `all` rejects the moment the event flush does, and a
@@ -341,18 +391,30 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     })
   }
 
-  protected override flushAutomatic(): Promise<void> {
-    // The events timer must not drag spans through a `Retry-After` window the
-    // traces queue is honouring; its own timer picks them up when it closes.
-    return this._flushKeepingRuntimeAlive(true)
+  /**
+   * Sends all queued events and spans, and resolves when every send has finished.
+   * It does not reject when delivery fails: those failures arrive on the `'error'` event.
+   */
+  override async flush(): Promise<void> {
+    return this._keepRuntimeAlive(this._flushEventsAndSpans())
   }
 
-  override async flush(): Promise<void> {
-    return this._flushKeepingRuntimeAlive(false)
+  /** Every lane flushes concurrently, so a slow lane only delays this promise, not the other lanes' sends. */
+  private _flushCaptureLanes(): Promise<void> {
+    return Promise.all([...this._captureLanes.values()].map((lane) => lane.flush())).then(() => {})
+  }
+
+  /** A flush a lane started on its own, from its timer or `flushAt`. */
+  private _onLaneBackgroundFlush(laneFlush: Promise<void>): void {
+    // Spans ride along, except while the traces queue is honouring a `Retry-After`
+    // window; its own timer picks them up when the window closes.
+    const traces = this._traces
+    const flush =
+      traces && !traces.throttled ? allSettled([laneFlush, traces.flush().catch(() => {})]).then(() => {}) : laneFlush
+    void this._keepRuntimeAlive(flush)
   }
 
-  private _flushKeepingRuntimeAlive(skipThrottledSpans: boolean): Promise<void> {
-    const flushPromise = this._flushEventsAndSpans(skipThrottledSpans)
+  private _keepRuntimeAlive(flushPromise: Promise<void>): Promise<void> {
     const waitUntil = this.options.waitUntil
     // Only register when no debounce promise is already keeping runtime alive
     if (waitUntil && !this._waitUntilCycle) {
@@ -506,63 +568,50 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return this.options.fetch ? this.options.fetch(url, options) : fetch(url, options)
   }
 
-  /** Every `capture()` event, including `$ai_*`, stays on the analytics route. */
-  protected getQueueRouteKey(_message: PostHogEventProperties): string {
-    return ANALYTICS_ROUTE
-  }
-
-  protected persistedQueueKeyForRoute(route: string): PostHogPersistedProperty {
-    return route === AI_CAPTURE_ROUTE ? PostHogPersistedProperty.AiCaptureQueue : PostHogPersistedProperty.Queue
-  }
-
-  protected getActiveQueueRoutes(): string[] {
-    return this._aiCaptureRouteActive ? [ANALYTICS_ROUTE, AI_CAPTURE_ROUTE] : [ANALYTICS_ROUTE]
-  }
-
-  /**
-   * Capture submission seam shared by the batched (`_flush`) and immediate (`sendImmediate`)
-   * paths. Each route has its own queue and capture lane, so a failure on one lane can never
-   * re-send events already accepted on the other. The sender reports failures on the error
-   * channel and resolves, so `_flush` treats every batch as consumed.
-   */
-  protected async sendBatch(
-    batchMessages: (PostHogEventProperties | undefined)[],
-    _retryOptions?: Partial<RetriableOptions>,
-    route: string = ANALYTICS_ROUTE
-  ): Promise<void> {
-    if (route === AI_CAPTURE_ROUTE) {
-      return this.sendAiCaptureBatch(batchMessages)
+  /** The lane for `route`; `captureAi` events use the AI lane, every other event the analytics lane. */
+  private _captureLane(route?: string): CaptureLane {
+    const endpoint = route === AI_CAPTURE_ROUTE ? AI_CAPTURE_ENDPOINT : ANALYTICS_CAPTURE_ENDPOINT
+    let lane = this._captureLanes.get(endpoint)
+    if (!lane) {
+      lane = new CaptureLane(this._captureLaneConfig(endpoint), {
+        sender: new V1CaptureSender(this.captureSenderConfig(endpoint), {
+          fetch: (url, fetchOptions) => this.fetch(url, fetchOptions),
+          onError: (error) => this._events.emit('error', error),
+          compress: (payload) => this.compressPayload(payload),
+        }),
+        onLocalDrops: (error) => this._reportLocalCaptureDrops(error),
+        onError: (error) => this._events.emit('error', error),
+        onFlush: (messages) => this._events.emit('flush', messages),
+        onBackgroundFlush: (flush) => this._onLaneBackgroundFlush(flush),
+        logger: this._logger,
+      })
+      this._captureLanes.set(endpoint, lane)
     }
-
-    // A freshly-enqueued event is never undefined; drop any legacy undefined queue artifacts.
-    const events = batchMessages.filter((message): message is PostHogEventProperties => message !== undefined)
-    await this.getCaptureSender(ANALYTICS_CAPTURE_ENDPOINT).sendV1Batch(events)
+    return lane
   }
 
-  private async sendAiCaptureBatch(batchMessages: (PostHogEventProperties | undefined)[]): Promise<void> {
-    const { batches, dropped } = partitionAiBatch(batchMessages)
-    for (const { event, bytes } of dropped) {
-      const message = `Event ${event} (${bytes} bytes) exceeds the ${AI_MAX_EVENT_BYTES / (1024 * 1024)}MiB limit for ${AI_CAPTURE_ENDPOINT}, dropping.`
-      this._logger.error(message)
-      this._events.emit('error', new Error(message))
-    }
-    const sender = this.getCaptureSender(AI_CAPTURE_ENDPOINT)
-    for (const batch of batches) {
-      await sender.sendV1Batch(batch)
+  private _captureLaneConfig(endpoint: CaptureEndpoint): CaptureLaneConfig {
+    const isAi = endpoint === AI_CAPTURE_ENDPOINT
+    return {
+      endpoint,
+      flushAt: this.flushAt,
+      flushIntervalMs: this.options.flushInterval ?? 5000,
+      maxBatchSize: Math.max(this.flushAt, this.options.maxBatchSize ?? 100),
+      // Never below flushAt, or the flushAt trigger could never fire.
+      maxQueueSize: Math.max(this.flushAt, isAi ? AI_MAX_QUEUE_SIZE : (this.options.maxQueueSize ?? 10000)),
+      targetBatchBytes: CAPTURE_BATCH_TARGET_BYTES,
+      maxEventBytes: isAi ? AI_MAX_PROPERTIES_BYTES : ANALYTICS_MAX_EVENT_BYTES,
+      maxEventBytesOf: isAi ? 'properties' : 'event',
     }
   }
 
-  private getCaptureSender(path: CaptureEndpoint): V1CaptureSender {
-    let sender = this._captureSenders.get(path)
-    if (!sender) {
-      sender = new V1CaptureSender(this.captureSenderConfig(path), {
-        fetch: (url, fetchOptions) => this.fetch(url, fetchOptions),
-        onError: (error) => this._events.emit('error', error),
-        compress: (payload) => this.compressPayload(payload),
-      })
-      this._captureSenders.set(path, sender)
+  private _reportLocalCaptureDrops(error: CaptureError): void {
+    const errorListeners = this._events.events['error']?.length ?? 0
+    this._events.emit('error', error)
+    if (errorListeners === 0) {
+      // console.warn, not this._logger: the logger only prints in debug mode, and these drops lose data.
+      console.warn(`[PostHog] ${error.message}`)
     }
-    return sender
   }
 
   /** Every lane shares the client's retry, timeout and compression settings. */
@@ -1081,7 +1130,6 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (typeof props?.event === 'string' && !props.event.startsWith('$ai_')) {
       this._logger.debug(`captureAi called with non-AI event ${props.event}; routing it to the AI endpoint anyway.`)
     }
-    this._aiCaptureRouteActive = true
     return this._sendPreparedEvent('capture', props, immediate, undefined, AI_CAPTURE_ROUTE)
   }
 
@@ -2902,13 +2950,26 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       this._traces.reset()
     }
     try {
-      return await super._shutdown(Math.max(0, shutdownDeadlineMs - Date.now()))
+      // The core shutdown waits for pending captures to land on their lanes; the lanes drain meanwhile,
+      // then once more for whatever those captures added.
+      await Promise.all([
+        super._shutdown(Math.max(0, shutdownDeadlineMs - Date.now())),
+        this._drainCaptureLanes(shutdownDeadlineMs),
+      ])
+      await this._drainCaptureLanes(shutdownDeadlineMs)
     } finally {
+      for (const lane of this._captureLanes.values()) {
+        lane.finishShutdown()
+      }
       this._distinctIdHasSentFlagCalls.clear()
       resolve?.()
     }
   }
 
+  private _drainCaptureLanes(deadlineMs: number): Promise<void> {
+    return Promise.all([...this._captureLanes.values()].map((lane) => lane.drain(deadlineMs))).then(() => {})
+  }
+
   private async _requestRemoteConfigPayload(flagKey: string): Promise<PostHogFetchResponse | undefined> {
     if (this.disabled || !this.apiKey || !this.options.personalApiKey) {
       return undefined
diff --git a/packages/node/src/types.ts b/packages/node/src/types.ts
index 27fe90ba27..fa2c9cc7bc 100644
--- a/packages/node/src/types.ts
+++ b/packages/node/src/types.ts
@@ -175,7 +175,9 @@ export type PostHogOptions = Omit<PostHogCoreOptions, 'before_send' | 'flushInte
    */
   flushInterval?: number
   /**
-   * The maximum number of cached messages either in memory or on the local storage (must be higher than `flushAt`)
+   * The maximum number of analytics events held in memory waiting to be sent (must be higher than `flushAt`).
+   * When the queue is full, the oldest event is dropped and reported through the `'error'` event.
+   * `captureAi` events have their own queue and do not count toward this limit.
    *
    * @default 10000
    */

From ea36374405e1a64215cfa94c3c3bced3b51efc18 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:02:57 -0700
Subject: [PATCH 07/20] feat(node)!: retry and compress capture requests by the
 v1 rules (#5411)

* feat(node)!: retry capture requests on the fleet schedule

Capture waits 100 ms before the first retry and doubles each wait, with
+/-25% jitter, up to 30 seconds; Retry-After raises a wait and jitter never
shortens it. The new captureMaxRetries option (integer 0-9) sets the retry
count and falls back to fetchRetryCount; fetchRetryDelay no longer affects
capture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): choose the capture compression codec per lane

captureCompression ('none' | 'gzip' | 'deflate' | 'zstd', default 'gzip') sets
the analytics lane codec and maps disableCompression: true to 'none' when unset.
captureAiCompression sets the AI lane codec on its own (default 'gzip'). The
Node build compresses with node:zlib, with zstd from Node 22.15; the edge build
uses CompressionStream for gzip and deflate. An unavailable zstd falls back to
gzip with one debug log. Content-Encoding names the codec used, and each request
sends a fresh copy of the compressed body.

The convex example tests now decode capture bodies of any type and codec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): size and time the AI capture lane on its own

captureAiMaxQueueSize (default 1000) replaces the fixed AI queue cap, and
captureAiRequestTimeoutMs (default 30000) sets the AI lane request timeout.
The analytics lane keeps requestTimeout. Invalid values log one error and
use the default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for capture retries and compression

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: retry capture requests that get 404 or 429

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): keep captureAiMaxQueueSize as set when it is below flushAt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): cap capture settings at the timer limit and hide the compressor hook

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-node-capture-sender.md     |   6 +
 .../example-convex/convex/example.test.ts     |  21 +-
 .../posthog-node-references-latest.json       |  87 ++++--
 .../src/__tests__/ai-capture/wiring.spec.ts   |   2 +-
 .../__tests__/capture-lane/isolation.spec.ts  |  87 +++++-
 .../__tests__/capture-lane/settings.spec.ts   | 145 ++++++++++
 .../__tests__/capture-v1/compression.spec.ts  | 204 ++++++++++++++
 .../src/__tests__/capture-v1/sender.spec.ts   | 257 +++++++++++-------
 .../src/__tests__/capture-v1/wiring.spec.ts   |   2 +-
 .../node/src/__tests__/utils/v1-wiring.ts     |   2 +
 .../src/__tests__/waituntil-flush.spec.ts     |   1 +
 packages/node/src/capture-lane/limits.ts      |   2 -
 packages/node/src/capture-lane/settings.ts    | 119 ++++++++
 packages/node/src/capture-v1/compression.ts   |  50 ++++
 packages/node/src/capture-v1/sender.ts        | 100 ++++---
 packages/node/src/client.ts                   |  56 ++--
 packages/node/src/compression.node.ts         |  30 ++
 packages/node/src/entrypoints/index.node.ts   |   6 +
 packages/node/src/types.ts                    |  76 +++++-
 19 files changed, 1053 insertions(+), 200 deletions(-)
 create mode 100644 .changeset/posthog-node-capture-sender.md
 create mode 100644 packages/node/src/__tests__/capture-lane/settings.spec.ts
 create mode 100644 packages/node/src/__tests__/capture-v1/compression.spec.ts
 create mode 100644 packages/node/src/capture-lane/settings.ts
 create mode 100644 packages/node/src/capture-v1/compression.ts
 create mode 100644 packages/node/src/compression.node.ts

diff --git a/.changeset/posthog-node-capture-sender.md b/.changeset/posthog-node-capture-sender.md
new file mode 100644
index 0000000000..13e5a3b77a
--- /dev/null
+++ b/.changeset/posthog-node-capture-sender.md
@@ -0,0 +1,6 @@
+---
+'posthog-node': major
+---
+
+Capture retries only 404, 408, 429, 500, 502, 503, 504 and network errors, waiting 100 ms doubled per retry with jitter (at most 30 s, at least `Retry-After`).
+Adds `captureMaxRetries`, `captureCompression`, `captureAiCompression`, `captureAiMaxQueueSize` and `captureAiRequestTimeoutMs`.
diff --git a/examples/example-convex/convex/example.test.ts b/examples/example-convex/convex/example.test.ts
index a6285bc467..63b448b908 100644
--- a/examples/example-convex/convex/example.test.ts
+++ b/examples/example-convex/convex/example.test.ts
@@ -13,6 +13,15 @@ const CAPTURE_PATHS = ['/i/v1/analytics/events']
 let fetchCalls: Array<{ url: string; headers: Record<string, string>; body: unknown }> = []
 const originalFetch = global.fetch
 
+// Capture bodies may be a string, Blob or byte array, and gzip or deflate compressed.
+async function decodeBody(body: BodyInit, encoding: string | undefined): Promise<string> {
+    const raw = new Response(body)
+    if (encoding === 'gzip' || encoding === 'deflate') {
+        return await new Response(raw.body!.pipeThrough(new DecompressionStream(encoding))).text()
+    }
+    return await raw.text()
+}
+
 function mockFetch(responseByUrl?: Record<string, unknown>, statusByUrl?: Record<string, number>) {
     fetchCalls = []
     return vi.fn(async (url: string | URL, init?: RequestInit) => {
@@ -21,17 +30,7 @@ function mockFetch(responseByUrl?: Record<string, unknown>, statusByUrl?: Record
         const status = Object.entries(statusByUrl ?? {}).find(([pattern]) => urlStr.includes(pattern))?.[1] ?? 200
         let body: unknown
         if (init?.body) {
-            let rawText: string
-            if (init.body instanceof Blob) {
-                if (headers['Content-Encoding'] === 'gzip') {
-                    const ds = new DecompressionStream('gzip')
-                    rawText = await new Response(init.body.stream().pipeThrough(ds)).text()
-                } else {
-                    rawText = await init.body.text()
-                }
-            } else {
-                rawText = init.body as string
-            }
+            const rawText = await decodeBody(init.body, headers['Content-Encoding'])
             try {
                 body = JSON.parse(rawText)
             } catch {
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index 3076dfcc77..9eebd8cc0b 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -1992,6 +1992,26 @@
       "path": "src/types.ts",
       "example": "(event: EventMessage) => EventMessage | null"
     },
+    {
+      "id": "CaptureCodec",
+      "name": "CaptureCodec",
+      "properties": [],
+      "path": "src/capture-v1/compression.ts",
+      "example": "Exclude<CaptureCompression, 'none'>"
+    },
+    {
+      "id": "CaptureCompression",
+      "name": "CaptureCompression",
+      "properties": [],
+      "path": "src/capture-v1/compression.ts",
+      "example": "(typeof CAPTURE_COMPRESSIONS)[number]"
+    },
+    {
+      "id": "CaptureCompressor",
+      "name": "CaptureCompressor",
+      "properties": [],
+      "path": "src/capture-v1/compression.ts"
+    },
     {
       "id": "CaptureDroppedEvent",
       "name": "CaptureDroppedEvent",
@@ -3679,21 +3699,6 @@
           "type": "{ distinctId?: string; isIdentifiedId?: boolean; featureFlags?: Record<string, FeatureFlagValue>; featureFlagPayloads?: Record<string, JsonType>; }",
           "name": "bootstrap"
         },
-        {
-          "description": "How many times we will retry HTTP requests",
-          "type": "number",
-          "name": "fetchRetryCount"
-        },
-        {
-          "description": "The delay between HTTP request retries in milliseconds",
-          "type": "number",
-          "name": "fetchRetryDelay"
-        },
-        {
-          "description": "Timeout in milliseconds for any calls",
-          "type": "number",
-          "name": "requestTimeout"
-        },
         {
           "description": "Timeout in milliseconds for feature flag calls",
           "type": "number",
@@ -3714,11 +3719,6 @@
           "type": "number",
           "name": "sessionExpirationTimeSeconds"
         },
-        {
-          "description": "Whether to disable GZIP compression",
-          "type": "boolean",
-          "name": "disableCompression"
-        },
         {
           "description": "Special flag to indicate ingested data is for a historical migration",
           "type": "boolean",
@@ -3755,10 +3755,55 @@
           "name": "flushInterval"
         },
         {
-          "description": "The maximum number of analytics events held in memory waiting to be sent (must be higher than `flushAt`).\nWhen the queue is full, the oldest event is dropped and reported through the `'error'` event.\n`captureAi` events have their own queue and do not count toward this limit.",
+          "description": "The maximum number of analytics events held in memory waiting to be sent (must be higher than `flushAt`).\nWhen the queue is full, the oldest event is dropped and reported through the `'error'` event.\n`captureAi` events have their own queue, sized by `captureAiMaxQueueSize`, and do not count toward this limit.",
           "type": "number",
           "name": "maxQueueSize"
         },
+        {
+          "description": "How many times a capture request is retried after its first attempt, on both capture lanes.\nWaits start at 100 ms and double each retry, with jitter, up to 30 seconds; a `Retry-After`\nheader can raise a wait. Only HTTP 404, 408, 429, 500, 502, 503 and 504 and network errors are retried.\nWhen not set, `fetchRetryCount` is used.",
+          "type": "number",
+          "name": "captureMaxRetries"
+        },
+        {
+          "description": "How many times HTTP requests are retried. Capture requests use `captureMaxRetries` when it is set.",
+          "type": "number",
+          "name": "fetchRetryCount"
+        },
+        {
+          "description": "The delay between HTTP request retries in milliseconds. Capture requests do not use it:\nsee `captureMaxRetries` for their retry waits.",
+          "type": "number",
+          "name": "fetchRetryDelay"
+        },
+        {
+          "description": "How analytics capture requests compress their body. `'deflate'` is zlib-wrapped. `'zstd'` needs\nNode 22.15 or later and falls back to `'gzip'` elsewhere, including the edge build. When not set,\n`disableCompression: true` means `'none'`.",
+          "type": "\"none\" | \"gzip\" | \"deflate\" | \"zstd\"",
+          "name": "captureCompression"
+        },
+        {
+          "description": "How `captureAi` requests compress their body, with the same values as `captureCompression`.\nIt does not read `captureCompression` or `disableCompression`.",
+          "type": "\"none\" | \"gzip\" | \"deflate\" | \"zstd\"",
+          "name": "captureAiCompression"
+        },
+        {
+          "description": "Timeout in milliseconds for any calls. `captureAi` requests use `captureAiRequestTimeoutMs`.",
+          "type": "number",
+          "name": "requestTimeout"
+        },
+        {
+          "description": "The maximum number of `captureAi` events held in memory waiting to be sent. When the queue is\nfull, the oldest AI event is dropped and reported through the `'error'` event.",
+          "type": "number",
+          "name": "captureAiMaxQueueSize"
+        },
+        {
+          "description": "Timeout in milliseconds for each `captureAi` request. Analytics capture requests use `requestTimeout`.",
+          "type": "number",
+          "name": "captureAiRequestTimeoutMs"
+        },
+        {
+          "description": "Whether to disable GZIP compression. Analytics capture requests use `captureCompression` when it\nis set, and `captureAi` requests use `captureAiCompression`.",
+          "type": "boolean",
+          "name": "disableCompression"
+        },
         {
           "description": "Configuration for the `posthog.metrics` API (count, gauge, histogram).\nSet `serviceName` so series can be filtered per service in the Metrics UI.",
           "type": "MetricsConfig",
diff --git a/packages/node/src/__tests__/ai-capture/wiring.spec.ts b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
index 4c410c1724..ddb8540193 100644
--- a/packages/node/src/__tests__/ai-capture/wiring.spec.ts
+++ b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
@@ -158,7 +158,7 @@ describe('AI capture lane wiring (Node SDK)', () => {
   })
 
   it('treats a 413 as terminal: one request, a CaptureError naming the AI lane, no bisection', async () => {
-    const posthog = harness.makeClient({ fetchRetryCount: 3, fetchRetryDelay: 1 })
+    const posthog = harness.makeClient({ captureMaxRetries: 3 })
     const onError = vi.fn()
     posthog.on('error', onError)
     harness.fetch.mockImplementation((url: any) =>
diff --git a/packages/node/src/__tests__/capture-lane/isolation.spec.ts b/packages/node/src/__tests__/capture-lane/isolation.spec.ts
index 4bf5ca9033..2cd69601d2 100644
--- a/packages/node/src/__tests__/capture-lane/isolation.spec.ts
+++ b/packages/node/src/__tests__/capture-lane/isolation.spec.ts
@@ -64,7 +64,7 @@ describe('capture lane isolation (Node SDK)', () => {
 
   it('keeps sending analytics events on their own timer while an AI send is stuck', async () => {
     const ai = holdLane(harness, AI_CAPTURE_PATH)
-    const posthog = harness.makeClient({ flushInterval: 1000, flushAt: 100, requestTimeout: 60_000 })
+    const posthog = harness.makeClient({ flushInterval: 1000, flushAt: 100, captureAiRequestTimeoutMs: 60_000 })
 
     posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
     posthog.capture({ distinctId: 'u', event: 'first', properties: {} })
@@ -106,7 +106,7 @@ describe('capture lane isolation (Node SDK)', () => {
 
   it('never drops analytics events when the AI queue is full', async () => {
     const ai = holdLane(harness, AI_CAPTURE_PATH)
-    const posthog = harness.makeClient({ flushAt: 1, requestTimeout: 60_000 })
+    const posthog = harness.makeClient({ flushAt: 1, captureAiRequestTimeoutMs: 60_000 })
     const errors: CaptureError[] = []
     posthog.on('error', (error) => errors.push(error))
 
@@ -131,9 +131,80 @@ describe('capture lane isolation (Node SDK)', () => {
     expect(errors[0].message).toContain('5 because the queue was full (1000 events)')
   })
 
+  it('caps the AI queue at captureAiMaxQueueSize', async () => {
+    const ai = holdLane(harness, AI_CAPTURE_PATH)
+    const posthog = harness.makeClient({ flushAt: 1, captureAiMaxQueueSize: 2 })
+    const errors: CaptureError[] = []
+    posthog.on('error', (error) => errors.push(error))
+
+    posthog.captureAi({ distinctId: 'u', event: '$ai_0', properties: {} })
+    await vi.advanceTimersByTimeAsync(0)
+    for (let i = 1; i <= 4; i++) {
+      posthog.captureAi({ distinctId: 'u', event: `$ai_${i}`, properties: {} })
+    }
+    ai.release()
+    await posthog.flush()
+
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_0', '$ai_3', '$ai_4'])
+    expect(errors).toHaveLength(1)
+    expect(errors[0].endpoint).toBe(AI_CAPTURE_PATH)
+    expect(errors[0].message).toContain('2 because the queue was full (2 events)')
+  })
+
+  it('keeps a captureAiMaxQueueSize below flushAt as set', async () => {
+    const ai = holdLane(harness, AI_CAPTURE_PATH)
+    const posthog = harness.makeClient({ flushAt: 20, captureAiMaxQueueSize: 2 })
+    const errors: CaptureError[] = []
+    posthog.on('error', (error) => errors.push(error))
+
+    for (let i = 0; i < 6; i++) {
+      posthog.captureAi({ distinctId: 'u', event: `$ai_${i}`, properties: {} })
+    }
+    ai.release()
+    await posthog.flush()
+
+    // Synchronous captures fill the queue before a flush runs, so it keeps the newest 2 and drops the rest.
+    expect(harness.eventsIn(AI_CAPTURE_PATH)).toEqual(['$ai_4', '$ai_5'])
+    expect(errors.map((error) => error.message).join(' ')).toContain('4 because the queue was full (2 events)')
+  })
+
+  it.each<[string, Record<string, number>, number, number]>([
+    ['the defaults', {}, 10_000, 30_000],
+    ['requestTimeout on the analytics lane only', { requestTimeout: 200 }, 200, 30_000],
+    ['captureAiRequestTimeoutMs on the AI lane only', { captureAiRequestTimeoutMs: 300 }, 10_000, 300],
+  ])('times out each lane on its own deadline with %s', async (_label, options, analyticsMs, aiMs) => {
+    harness.fetch.mockImplementation(() => new Promise(() => {}))
+    const posthog = harness.makeClient(options)
+    posthog.capture({ distinctId: 'u', event: 'custom', properties: {} })
+    posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+    void posthog.flush()
+    await vi.advanceTimersByTimeAsync(0)
+    const aborted = (path: string): boolean => harness.callsTo(path)[0][1].signal.aborted
+    let elapsed = 0
+    const advanceTo = async (ms: number): Promise<void> => {
+      await vi.advanceTimersByTimeAsync(ms - elapsed)
+      elapsed = ms
+    }
+
+    for (const [path, deadline] of [
+      [ANALYTICS_CAPTURE_PATH, analyticsMs],
+      [AI_CAPTURE_PATH, aiMs],
+    ].sort((a, b) => (a[1] as number) - (b[1] as number)) as [string, number][]) {
+      await advanceTo(deadline - 1)
+      expect(aborted(path)).toBe(false)
+      await advanceTo(deadline)
+      expect(aborted(path)).toBe(true)
+    }
+    // Requeued events go out again on later flushes; end those before teardown.
+    harness.useDefaultRouting()
+    const shutdown = posthog.shutdown(1000)
+    await vi.advanceTimersByTimeAsync(1000)
+    await shutdown
+  })
+
   it('drains both lanes concurrently on shutdown and stops retrying at the deadline', async () => {
     harness.fetch.mockImplementation(() => Promise.resolve(errorResponse(503)))
-    const posthog = harness.makeClient({ fetchRetryCount: 5, fetchRetryDelay: 1000, flushAt: 100 })
+    const posthog = harness.makeClient({ captureMaxRetries: 5, flushAt: 100 })
     const errors: CaptureError[] = []
     posthog.on('error', (error) => errors.push(error))
     posthog.capture({ distinctId: 'u', event: 'custom', properties: {}, uuid: ANALYTICS_UUID })
@@ -141,13 +212,14 @@ describe('capture lane isolation (Node SDK)', () => {
     await vi.advanceTimersByTimeAsync(0)
 
     let finished = false
-    const shutdown = posthog.shutdown(1500).then(() => (finished = true))
+    // With jitter the first retry waits 75-125 ms and the second starts 225-375 ms in, so exactly one retry fits.
+    const shutdown = posthog.shutdown(200).then(() => (finished = true))
     await vi.advanceTimersByTimeAsync(0)
     // Both first attempts go out before either lane's backoff elapses.
     expect(harness.callsTo(ANALYTICS_CAPTURE_PATH)).toHaveLength(1)
     expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(1)
 
-    await vi.advanceTimersByTimeAsync(1499)
+    await vi.advanceTimersByTimeAsync(199)
     expect(finished).toBe(false)
     await vi.advanceTimersByTimeAsync(1)
     await shutdown
@@ -194,12 +266,13 @@ describe('capture lane isolation (Node SDK)', () => {
     harness.fetch.mockImplementation((url: any) =>
       Promise.resolve(String(url).includes(AI_CAPTURE_PATH) ? errorResponse(500) : routeByUrl(url))
     )
-    const posthog = harness.makeClient({ fetchRetryCount: 1, fetchRetryDelay: 1 })
+    const posthog = harness.makeClient({ captureMaxRetries: 1 })
     const errors: CaptureError[] = []
     posthog.on('error', (error) => errors.push(error))
     const uuid = posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
     const flush = posthog.flush()
-    await vi.advanceTimersByTimeAsync(1)
+    // The longest first retry wait, with the highest jitter.
+    await vi.advanceTimersByTimeAsync(125)
     await flush
 
     expect(harness.callsTo(AI_CAPTURE_PATH)).toHaveLength(2)
diff --git a/packages/node/src/__tests__/capture-lane/settings.spec.ts b/packages/node/src/__tests__/capture-lane/settings.spec.ts
new file mode 100644
index 0000000000..9018071d74
--- /dev/null
+++ b/packages/node/src/__tests__/capture-lane/settings.spec.ts
@@ -0,0 +1,145 @@
+import { resolveCaptureSettings } from '@/capture-lane/settings'
+import type { PostHogOptions } from '@/entrypoints/index.node'
+
+import { ANALYTICS_CAPTURE_PATH } from '../utils'
+import { V1WiringHarness } from '../utils/v1-wiring'
+
+vi.mock('../../version', () => ({ version: '1.2.3' }))
+
+function resolve(options: PostHogOptions): { settings: ReturnType<typeof resolveCaptureSettings>; logged: string[] } {
+  const logged: string[] = []
+  const settings = resolveCaptureSettings(options, (message) => logged.push(message))
+  return { settings, logged }
+}
+
+describe('resolveCaptureSettings', () => {
+  describe('maxRetries', () => {
+    it.each<[string, PostHogOptions, number]>([
+      ['the default', {}, 3],
+      ['fetchRetryCount when captureMaxRetries is unset', { fetchRetryCount: 5 }, 5],
+      ['fetchRetryCount 0 as no retries', { fetchRetryCount: 0 }, 0],
+      ['fetchRetryCount above 9 clamped to 9', { fetchRetryCount: 20 }, 9],
+      ['fetchRetryCount below 0 clamped to 0', { fetchRetryCount: -1 }, 0],
+      ['captureMaxRetries over fetchRetryCount', { captureMaxRetries: 1, fetchRetryCount: 0 }, 1],
+      ['captureMaxRetries 0 over fetchRetryCount', { captureMaxRetries: 0, fetchRetryCount: 5 }, 0],
+      ['captureMaxRetries at its maximum', { captureMaxRetries: 9 }, 9],
+    ])('uses %s', (_label, options, expected) => {
+      const { settings, logged } = resolve(options)
+
+      expect(settings.maxRetries).toBe(expected)
+      expect(logged).toEqual([])
+    })
+
+    it.each<[unknown]>([[-1], [10], [1.5], ['3'], [Number.NaN]])(
+      'logs one error for captureMaxRetries %s and falls back as if it were unset',
+      (captureMaxRetries) => {
+        const withFallback = resolve({ captureMaxRetries: captureMaxRetries as number, fetchRetryCount: 1 })
+        const withDefault = resolve({ captureMaxRetries: captureMaxRetries as number })
+
+        expect(withFallback.settings.maxRetries).toBe(1)
+        expect(withDefault.settings.maxRetries).toBe(3)
+        expect(withFallback.logged).toEqual(['captureMaxRetries must be an integer from 0 to 9; using the default.'])
+      }
+    )
+  })
+})
+
+describe('resolveCaptureSettings AI lane limits', () => {
+  it('defaults to a 1000 event queue and a 30 second timeout, and keeps requestTimeout for analytics', () => {
+    const { settings, logged } = resolve({ requestTimeout: 5000 })
+
+    expect(settings.ai).toMatchObject({ maxQueueSize: 1000, requestTimeoutMs: 30_000 })
+    expect(settings.analytics.requestTimeoutMs).toBe(5000)
+    expect(resolve({}).settings.analytics.requestTimeoutMs).toBe(10_000)
+    expect(logged).toEqual([])
+  })
+
+  it('uses valid values', () => {
+    const { settings, logged } = resolve({ captureAiMaxQueueSize: 5, captureAiRequestTimeoutMs: 1500.5 })
+
+    expect(settings.ai).toMatchObject({ maxQueueSize: 5, requestTimeoutMs: 1500.5 })
+    expect(logged).toEqual([])
+  })
+
+  it.each<[keyof PostHogOptions, unknown, string]>([
+    [
+      'captureAiMaxQueueSize',
+      0,
+      'captureAiMaxQueueSize must be a positive integer up to 2147483647; using the default.',
+    ],
+    [
+      'captureAiMaxQueueSize',
+      2.5,
+      'captureAiMaxQueueSize must be a positive integer up to 2147483647; using the default.',
+    ],
+    [
+      'captureAiMaxQueueSize',
+      '10',
+      'captureAiMaxQueueSize must be a positive integer up to 2147483647; using the default.',
+    ],
+    [
+      'captureAiRequestTimeoutMs',
+      -1,
+      'captureAiRequestTimeoutMs must be a positive number up to 2147483647; using the default.',
+    ],
+    [
+      'captureAiRequestTimeoutMs',
+      3e9,
+      'captureAiRequestTimeoutMs must be a positive number up to 2147483647; using the default.',
+    ],
+    [
+      'captureAiRequestTimeoutMs',
+      Number.POSITIVE_INFINITY,
+      'captureAiRequestTimeoutMs must be a positive number up to 2147483647; using the default.',
+    ],
+  ])('logs one error for %s %s and uses the default', (name, value, message) => {
+    const { settings, logged } = resolve({ [name]: value } as PostHogOptions)
+
+    expect(settings.ai).toMatchObject({ maxQueueSize: 1000, requestTimeoutMs: 30_000 })
+    expect(logged).toEqual([message])
+  })
+})
+
+describe('capture settings on the client', () => {
+  const harness = new V1WiringHarness()
+  const unavailable = (): any => ({ status: 503, text: () => Promise.resolve(''), headers: { get: () => null } })
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    harness.fetch.mockImplementation(() => Promise.resolve(unavailable()))
+  })
+
+  afterEach(async () => {
+    harness.useDefaultRouting()
+    await harness.cleanup()
+    vi.clearAllMocks()
+  })
+
+  async function attemptsFor(options: PostHogOptions): Promise<number> {
+    const posthog = harness.makeClient(options)
+    posthog.capture({ distinctId: 'u', event: 'e', properties: {} })
+    const flush = posthog.flush()
+    // Longer than the longest three retry waits (125 + 250 + 500 ms).
+    await vi.advanceTimersByTimeAsync(1000)
+    await flush
+    return harness.callsTo(ANALYTICS_CAPTURE_PATH).length
+  }
+
+  it.each<[string, PostHogOptions, number]>([
+    ['3 retries by default', { fetchRetryCount: undefined }, 4],
+    ['no retries with fetchRetryCount 0', { fetchRetryCount: 0 }, 1],
+    ['captureMaxRetries over fetchRetryCount', { fetchRetryCount: 0, captureMaxRetries: 2 }, 3],
+  ])('makes %s', async (_label, options, expected) => {
+    expect(await attemptsFor(options)).toBe(expected)
+  })
+
+  it('logs one error for an invalid captureMaxRetries and does not throw', async () => {
+    expect(await attemptsFor({ fetchRetryCount: undefined, captureMaxRetries: 42 })).toBe(4)
+    expect(console.error).toHaveBeenCalledTimes(1)
+    expect(console.error).toHaveBeenCalledWith(
+      '[PostHog] captureMaxRetries must be an integer from 0 to 9; using the default.'
+    )
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/compression.spec.ts b/packages/node/src/__tests__/capture-v1/compression.spec.ts
new file mode 100644
index 0000000000..0821f53d83
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/compression.spec.ts
@@ -0,0 +1,204 @@
+import * as zlib from 'node:zlib'
+
+import {
+  type CaptureCodec,
+  type CaptureCompression,
+  type CaptureCompressor,
+  resolveCaptureCodec,
+  webCompressor,
+} from '@/capture-v1/compression'
+import { createZlibCompressor } from '@/compression.node'
+import { PostHog as EdgePostHog } from '@/entrypoints/index.edge'
+import { PostHog, type PostHogOptions } from '@/entrypoints/index.node'
+
+import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH } from '../utils'
+import { V1WiringHarness } from '../utils/v1-wiring'
+
+vi.mock('../../version', () => ({ version: '1.2.3' }))
+
+const zstdDecompressSync = (zlib as { zstdDecompressSync?: (input: Uint8Array) => Buffer }).zstdDecompressSync
+const hasZstd = typeof (zlib as { zstdCompress?: unknown }).zstdCompress === 'function'
+
+/** Decodes a request body the way the server would for its `Content-Encoding`. */
+function decode(encoding: string | undefined, body: string | Uint8Array): any {
+  if (encoding === undefined) {
+    return JSON.parse(body as string)
+  }
+  const bytes = body as Uint8Array
+  const decoders: Record<string, (input: Uint8Array) => Buffer> = {
+    gzip: zlib.gunzipSync,
+    // inflateSync rejects a raw deflate stream, so this also proves the body is zlib-wrapped.
+    deflate: zlib.inflateSync,
+    zstd: (input) => zstdDecompressSync!(input),
+  }
+  return JSON.parse(decoders[encoding](bytes).toString())
+}
+
+const fakeCompressor = (supported: CaptureCodec[]): CaptureCompressor => ({
+  supports: (codec) => supported.includes(codec),
+  compress: () => Promise.resolve(null),
+})
+
+describe('capture compression', () => {
+  describe('createZlibCompressor', () => {
+    it.each<CaptureCodec>(['gzip', 'deflate', ...(hasZstd ? (['zstd'] as const) : [])])(
+      'compresses with %s',
+      async (codec) => {
+        const compressor = createZlibCompressor()
+
+        const compressed = await compressor.compress('{"batch":[]}', codec)
+
+        expect(compressor.supports(codec)).toBe(true)
+        expect(decode(codec, compressed!)).toEqual({ batch: [] })
+      }
+    )
+
+    it('has no zstd when zlib has no zstdCompress', async () => {
+      const compressor = createZlibCompressor({ gzip: zlib.gzip, deflate: zlib.deflate })
+
+      expect(compressor.supports('zstd')).toBe(false)
+      expect(compressor.supports('gzip')).toBe(true)
+      expect(await compressor.compress('{}', 'zstd')).toBeNull()
+    })
+  })
+
+  describe('webCompressor', () => {
+    it('has no zstd', () => {
+      expect(webCompressor.supports('zstd')).toBe(false)
+    })
+
+    it.each<CaptureCodec>(['gzip', 'deflate'])('compresses with %s through CompressionStream', async (codec) => {
+      expect(webCompressor.supports(codec)).toBe(true)
+      expect(decode(codec, (await webCompressor.compress('{"batch":[]}', codec))!)).toEqual({ batch: [] })
+    })
+  })
+
+  describe('resolveCaptureCodec', () => {
+    it.each<[CaptureCompression, CaptureCodec[], CaptureCompression, boolean]>([
+      ['none', ['gzip', 'deflate', 'zstd'], 'none', false],
+      ['gzip', ['gzip', 'deflate', 'zstd'], 'gzip', false],
+      ['deflate', ['gzip', 'deflate'], 'deflate', false],
+      ['zstd', ['gzip', 'deflate', 'zstd'], 'zstd', false],
+      ['zstd', ['gzip', 'deflate'], 'gzip', true],
+      ['zstd', [], 'none', true],
+      ['gzip', [], 'none', false],
+      ['deflate', [], 'none', false],
+    ])('resolves %s with %j available to %s', (requested, supported, expected, reportsZstd) => {
+      const onZstdUnavailable = vi.fn()
+
+      expect(resolveCaptureCodec(requested, fakeCompressor(supported), onZstdUnavailable)).toBe(expected)
+      expect(onZstdUnavailable.mock.calls).toEqual(reportsZstd ? [[expected]] : [])
+    })
+  })
+
+  describe('on the client', () => {
+    const harness = new V1WiringHarness()
+
+    beforeEach(() => {
+      vi.useFakeTimers()
+      vi.spyOn(console, 'error').mockImplementation(() => {})
+      harness.useDefaultRouting()
+    })
+
+    afterEach(async () => {
+      await harness.cleanup()
+      vi.clearAllMocks()
+    })
+
+    async function encodings(posthog: PostHog | EdgePostHog): Promise<{ analytics?: string; ai?: string }> {
+      posthog.capture({ distinctId: 'u', event: 'analytics-event', properties: {} })
+      posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {} })
+      await posthog.flush()
+      const encodingOf = (path: string, event: string): string | undefined => {
+        const [, options] = harness.callsTo(path)[0]
+        const encoding = options.headers['Content-Encoding']
+        expect(decode(encoding, options.body).batch[0].event).toBe(event)
+        return encoding
+      }
+      return {
+        analytics: encodingOf(ANALYTICS_CAPTURE_PATH, 'analytics-event'),
+        ai: encodingOf(AI_CAPTURE_PATH, '$ai_generation'),
+      }
+    }
+
+    it.each<[string, PostHogOptions, string | undefined, string | undefined]>([
+      ['the defaults', {}, 'gzip', 'gzip'],
+      ['disableCompression', { disableCompression: true }, undefined, 'gzip'],
+      [
+        'captureCompression over disableCompression',
+        { disableCompression: true, captureCompression: 'deflate' },
+        'deflate',
+        'gzip',
+      ],
+      ['captureCompression none', { captureCompression: 'none' }, undefined, 'gzip'],
+      [
+        'captureAiCompression alone on the AI lane',
+        { disableCompression: true, captureCompression: 'none', captureAiCompression: 'deflate' },
+        undefined,
+        'deflate',
+      ],
+      ['captureAiCompression none', { captureAiCompression: 'none' }, 'gzip', undefined],
+      ...(hasZstd
+        ? ([
+            ['zstd on both lanes', { captureCompression: 'zstd', captureAiCompression: 'zstd' }, 'zstd', 'zstd'],
+          ] as const)
+        : []),
+    ])('uses %s', async (_label, options, analytics, ai) => {
+      // The harness turns compression off on both lanes; these cases set it explicitly.
+      const posthog = harness.makeClient({ disableCompression: undefined, captureAiCompression: undefined, ...options })
+
+      expect(await encodings(posthog)).toEqual({ analytics, ai })
+      expect(console.error).not.toHaveBeenCalled()
+    })
+
+    it.each<[keyof PostHogOptions, PostHogOptions, { analytics?: string; ai?: string }]>([
+      [
+        'captureCompression',
+        { captureCompression: 'br' as 'gzip', disableCompression: true },
+        { analytics: undefined, ai: 'gzip' },
+      ],
+      ['captureAiCompression', { captureAiCompression: 'br' as 'gzip' }, { analytics: 'gzip', ai: 'gzip' }],
+    ])('logs one error for an invalid %s and uses the default', async (name, options, expected) => {
+      const posthog = harness.makeClient({ disableCompression: undefined, captureAiCompression: undefined, ...options })
+
+      expect(await encodings(posthog)).toEqual(expected)
+      expect((console.error as vi.Mock).mock.calls).toEqual([
+        [`[PostHog] ${name} must be one of 'none', 'gzip', 'deflate', 'zstd'; using the default.`],
+      ])
+    })
+
+    it('compresses through CompressionStream on the edge build, with gzip in place of zstd', async () => {
+      const posthog = new EdgePostHog('TEST_API_KEY', {
+        host: 'http://example.com',
+        fetchRetryCount: 0,
+        captureCompression: 'zstd',
+        captureAiCompression: 'deflate',
+      })
+
+      expect(await encodings(posthog)).toEqual({ analytics: 'gzip', ai: 'deflate' })
+      await posthog.shutdown()
+    })
+
+    it('sends gzip, with one debug log per lane, when zstd is not available', async () => {
+      class PostHogWithoutZstd extends PostHog {
+        protected override captureCompressor(): CaptureCompressor {
+          return createZlibCompressor({ gzip: zlib.gzip, deflate: zlib.deflate })
+        }
+      }
+      const posthog = new PostHogWithoutZstd('TEST_API_KEY', {
+        host: 'http://example.com',
+        fetchRetryCount: 0,
+        captureCompression: 'zstd',
+        captureAiCompression: 'zstd',
+      })
+      const debug = vi.spyOn((posthog as any)._logger, 'debug')
+
+      expect(await encodings(posthog)).toEqual({ analytics: 'gzip', ai: 'gzip' })
+      expect(debug.mock.calls.filter(([message]) => String(message).includes('zstd'))).toEqual([
+        [`zstd compression is not available in this runtime; ${ANALYTICS_CAPTURE_PATH} uses gzip instead`],
+        [`zstd compression is not available in this runtime; ${AI_CAPTURE_PATH} uses gzip instead`],
+      ])
+      await posthog.shutdown()
+    })
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/sender.spec.ts b/packages/node/src/__tests__/capture-v1/sender.spec.ts
index de3296b60e..6a503a1f26 100644
--- a/packages/node/src/__tests__/capture-v1/sender.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/sender.spec.ts
@@ -61,11 +61,9 @@ function makeSender(
       libraryVersion: '1.2.3',
       userAgent: 'posthog-node/1.2.3',
       historicalMigration: false,
-      compressionEnabled: false,
+      compression: 'none',
       requestTimeoutMs: 1000,
-      maxAttempts: 4,
-      initialRetryDelayMs: 100,
-      maxBackoffMs: 30_000,
+      maxRetries: 3,
       ...configOverrides,
     },
     {
@@ -79,6 +77,8 @@ function makeSender(
         return Promise.resolve()
       },
       generateRequestId: () => 'req-fixed',
+      // The midpoint of the jitter range, so waits are exactly 100 ms, 200 ms, 400 ms, ...
+      random: () => 0.5,
       ...hookOverrides,
     }
   )
@@ -183,8 +183,8 @@ describe('V1CaptureSender', () => {
       expect(errors).toEqual([])
     })
 
-    it('still makes one attempt when maxAttempts is misconfigured to 0', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 0 })
+    it('still makes one attempt when maxRetries is misconfigured below 0', async () => {
+      const { sender, fetch, errors } = makeSender({ maxRetries: -1 })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       await sender.send(v1Events([msg('u1')]))
@@ -193,8 +193,8 @@ describe('V1CaptureSender', () => {
       expect(errors).toEqual([])
     })
 
-    it('surfaces a delivery error rather than silently dropping when maxAttempts is 0', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 0 })
+    it('surfaces a delivery error rather than silently dropping when maxRetries is below 0', async () => {
+      const { sender, fetch, errors } = makeSender({ maxRetries: -1 })
       fetch.mockResolvedValueOnce(makeResponse(400))
 
       await sender.send(v1Events([msg('u1')]))
@@ -207,33 +207,54 @@ describe('V1CaptureSender', () => {
   })
 
   describe('compression', () => {
-    it('gzips the body and advertises Content-Encoding when compression succeeds', async () => {
-      const blob = new Blob(['compressed'])
-      const compress = vi.fn().mockResolvedValue(blob)
-      const { sender, fetch } = makeSender({ compressionEnabled: true }, { compress })
-      fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
+    const compressed = new Uint8Array([1, 2, 3])
+
+    it.each(['gzip', 'deflate', 'zstd'] as const)(
+      'sends the %s body and advertises that Content-Encoding',
+      async (codec) => {
+        const compress = vi.fn().mockResolvedValue(compressed)
+        const { sender, fetch } = makeSender({ compression: codec }, { compress })
+        fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+        await sender.send(v1Events([msg('u1')]))
+
+        expect(compress).toHaveBeenCalledWith(expect.stringContaining('"batch"'), codec)
+        expect(headersOf(fetch, 0)['Content-Encoding']).toBe(codec)
+        expect(fetch.mock.calls[0][1].body).toEqual(compressed)
+      }
+    )
+
+    it('sends a fresh copy of the compressed body on every attempt', async () => {
+      const compress = vi.fn().mockResolvedValue(compressed)
+      const { sender, fetch } = makeSender({ compression: 'gzip' }, { compress })
+      fetch.mockResolvedValueOnce(makeResponse(503)).mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       await sender.send(v1Events([msg('u1')]))
 
-      expect(compress).toHaveBeenCalledTimes(1)
-      expect(headersOf(fetch, 0)['Content-Encoding']).toBe('gzip')
-      expect(fetch.mock.calls[0][1].body).toBe(blob)
+      const [first, second] = fetch.mock.calls.map((call) => call[1].body)
+      expect(first).toEqual(compressed)
+      expect(second).toEqual(compressed)
+      expect(first).not.toBe(second)
+      expect(first).not.toBe(compressed)
     })
 
-    it('falls back to uncompressed when compression returns null', async () => {
-      const compress = vi.fn().mockResolvedValue(null)
-      const { sender, fetch } = makeSender({ compressionEnabled: true }, { compress })
+    it.each<[string, () => Promise<Uint8Array | null>]>([
+      ['resolves to null', () => Promise.resolve(null)],
+      ['rejects', () => Promise.reject(new Error('codec failed'))],
+    ])('sends uncompressed when the codec %s', async (_label, compress) => {
+      const { sender, fetch, errors } = makeSender({ compression: 'gzip' }, { compress })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       await sender.send(v1Events([msg('u1')]))
 
       expect(headersOf(fetch, 0)).not.toHaveProperty('Content-Encoding')
-      expect(typeof fetch.mock.calls[0][1].body).toBe('string')
+      expect(bodyOf(fetch, 0).batch[0].uuid).toBe('u1')
+      expect(errors).toEqual([])
     })
 
     it('stops waiting for compression when the external signal aborts, and returns the batch as unsent', async () => {
       const compress = vi.fn(() => new Promise<null>(() => {}))
-      const { sender, fetch } = makeSender({ compressionEnabled: true }, { compress })
+      const { sender, fetch } = makeSender({ compression: 'gzip' }, { compress })
       const controller = new AbortController()
       const events = v1Events([msg('u1')])
 
@@ -245,9 +266,9 @@ describe('V1CaptureSender', () => {
       expect(fetch).not.toHaveBeenCalled()
     })
 
-    it('does not compress when disabled', async () => {
+    it('does not compress when compression is none', async () => {
       const compress = vi.fn()
-      const { sender, fetch } = makeSender({ compressionEnabled: false }, { compress })
+      const { sender, fetch } = makeSender({ compression: 'none' }, { compress })
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       await sender.send(v1Events([msg('u1')]))
@@ -351,7 +372,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('reports retry-exhausted uuids after the attempt budget runs out', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 3 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 2 })
       fetch.mockResolvedValue(makeResponse(200, { results: { u1: { result: 'retry' } } }))
 
       await sender.send(v1Events([msg('u1')]))
@@ -392,7 +413,7 @@ describe('V1CaptureSender', () => {
   })
 
   describe('HTTP status classification', () => {
-    it.each([408, 500, 502, 503, 504])('retries retryable status %s then succeeds', async (status) => {
+    it.each([404, 408, 429, 500, 502, 503, 504])('retries retryable status %s then succeeds', async (status) => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(status)).mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
@@ -402,19 +423,32 @@ describe('V1CaptureSender', () => {
       expect(errors).toEqual([])
     })
 
-    it('treats 429 as terminal in v1 (no retry)', async () => {
-      const { sender, fetch, errors } = makeSender()
-      fetch.mockResolvedValueOnce(makeResponse(429, '', { 'Retry-After': '1' }))
+    it('waits for Retry-After on a 429 before retrying', async () => {
+      const { sender, fetch, errors, sleeps } = makeSender({ maxRetries: 1 })
+      fetch
+        .mockResolvedValueOnce(makeResponse(429, '', { 'Retry-After': '2' }))
+        .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       await sender.send(v1Events([msg('u1')]))
 
-      expect(fetch).toHaveBeenCalledTimes(1)
+      expect(fetch).toHaveBeenCalledTimes(2)
+      expect(sleeps).toEqual([2000])
+      expect(errors).toEqual([])
+    })
+
+    it.each([404, 429])('reports %s with its status once the retries run out', async (status) => {
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1 })
+      fetch.mockResolvedValue(makeResponse(status))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(fetch).toHaveBeenCalledTimes(2)
       const error = errors[0] as CaptureError
       expect(error.retryExhausted).toEqual(['u1'])
-      expect((error.cause as Error).message).toContain('429')
+      expect((error.cause as Error).message).toContain(String(status))
     })
 
-    it.each([400, 401, 402, 413, 415])('treats non-retryable status %s as terminal', async (status) => {
+    it.each([400, 401, 402, 413, 415, 501])('treats non-retryable status %s as terminal', async (status) => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(status))
 
@@ -426,7 +460,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('exhausts the budget on a persistently retryable status', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 4 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 3 })
       fetch.mockResolvedValue(makeResponse(503))
 
       await sender.send(v1Events([msg('u1')]))
@@ -436,7 +470,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('bounds response body cancellation by the request deadline before retrying a 5xx', async () => {
-      const { sender, fetch, errors, sleeps } = makeSender({ maxAttempts: 2 })
+      const { sender, fetch, errors, sleeps } = makeSender({ maxRetries: 1 })
       const cancel = vi.fn<[], Promise<void>>(() => new Promise<void>(() => {}))
       fetch
         .mockResolvedValueOnce(makeStallingResponse(503, cancel))
@@ -473,7 +507,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('surfaces a batch failure after transport errors exhaust the budget', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 3 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 2 })
       fetch.mockRejectedValue(new Error('timeout'))
 
       await sender.send(v1Events([msg('u1'), msg('u2')]))
@@ -485,7 +519,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('identifies a timeout before response headers arrive when custom fetch rejects on abort', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 1, requestTimeoutMs: 1000 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 0, requestTimeoutMs: 1000 })
       fetch.mockImplementation(
         (_url, options) =>
           new Promise<PostHogFetchResponse>((_resolve, reject) => {
@@ -509,7 +543,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('cancels a response body when custom fetch resolves after the header deadline', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 1, requestTimeoutMs: 1000 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 0, requestTimeoutMs: 1000 })
       let resolveFetch!: (response: PostHogFetchResponse) => void
       fetch.mockImplementation(
         () =>
@@ -532,7 +566,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('retries a stalled success body without waiting for body cancellation to settle', async () => {
-      const { sender, fetch, errors, sleeps } = makeSender({ maxAttempts: 2, requestTimeoutMs: 1000 })
+      const { sender, fetch, errors, sleeps } = makeSender({ maxRetries: 1, requestTimeoutMs: 1000 })
       const cancel = vi.fn<[], Promise<void>>(() => new Promise<void>(() => {}))
       fetch
         .mockImplementationOnce(() => Promise.resolve(makeStallingResponse(200, cancel)))
@@ -550,7 +584,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('preserves the response-body timeout error when custom body reading rejects on abort', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 1, requestTimeoutMs: 1000 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 0, requestTimeoutMs: 1000 })
       const cancel = vi.fn<[], Promise<void>>().mockResolvedValue(undefined)
       fetch.mockImplementation((_url, options) => {
         const response = makeStallingResponse(200, cancel)
@@ -578,7 +612,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('surfaces CaptureError after stalled success bodies exhaust the timeout retry budget', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 2, requestTimeoutMs: 1000 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1, requestTimeoutMs: 1000 })
       const cancels: vi.Mock<Promise<void>, []>[] = []
       fetch.mockImplementation(() => {
         const cancel = vi.fn<[], Promise<void>>(() => new Promise<void>(() => {}))
@@ -606,7 +640,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('times out a stalled HTTP error body without changing terminal status classification', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 2, requestTimeoutMs: 1000 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1, requestTimeoutMs: 1000 })
       const cancel = vi.fn<[], Promise<void>>().mockResolvedValue(undefined)
       fetch.mockResolvedValue(makeStallingResponse(400, cancel))
 
@@ -626,7 +660,7 @@ describe('V1CaptureSender', () => {
 
   describe('unsent events (keepUnsent)', () => {
     it('returns events whose last attempt got no response, without reporting them', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1 })
       fetch.mockRejectedValue(new Error('ECONNREFUSED'))
       const events = v1Events([msg('u1'), msg('u2')])
 
@@ -638,7 +672,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('reports server drops and returns only the retry events a later transport failure left unsent', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(
           makeResponse(200, {
@@ -660,7 +694,7 @@ describe('V1CaptureSender', () => {
       ['a terminal status', () => makeResponse(400)],
       ['an unparseable 2xx', () => makeResponse(200, 'not json')],
     ])('reports and does not return events after %s', async (_name, response) => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1 })
       fetch.mockImplementation(() => Promise.resolve(response()))
 
       const unsent = await sender.send(v1Events([msg('u1')]), { keepUnsent: true })
@@ -671,7 +705,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('reports and does not return retry events still pending when the budget runs out on a 2xx', async () => {
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 2 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 1 })
       fetch.mockResolvedValue(makeResponse(200, { results: { u1: { result: 'retry' } } }))
 
       const unsent = await sender.send(v1Events([msg('u1')]), { keepUnsent: true })
@@ -695,7 +729,7 @@ describe('V1CaptureSender', () => {
 
     it('stops waiting for the next attempt when aborted during backoff', async () => {
       const controller = new AbortController()
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 4 }, { sleep: () => new Promise(() => {}) })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 3 }, { sleep: () => new Promise(() => {}) })
       fetch.mockResolvedValue(makeResponse(503))
 
       const sendPromise = sender.send(v1Events([msg('u1')]), { signal: controller.signal })
@@ -710,7 +744,7 @@ describe('V1CaptureSender', () => {
 
     it('aborts a request still waiting for response headers', async () => {
       const controller = new AbortController()
-      const { sender, fetch } = makeSender({ maxAttempts: 4, requestTimeoutMs: 60_000 })
+      const { sender, fetch } = makeSender({ maxRetries: 3, requestTimeoutMs: 60_000 })
       fetch.mockImplementation(() => new Promise(() => {}))
       const events = v1Events([msg('u1')])
 
@@ -726,7 +760,7 @@ describe('V1CaptureSender', () => {
 
     it('stops reading a stalled HTTP error body and still reports the status', async () => {
       const controller = new AbortController()
-      const { sender, fetch, errors } = makeSender({ maxAttempts: 1, requestTimeoutMs: 60_000 })
+      const { sender, fetch, errors } = makeSender({ maxRetries: 0, requestTimeoutMs: 60_000 })
       fetch.mockResolvedValue(makeStallingResponse(503, vi.fn().mockResolvedValue(undefined)))
 
       const sendPromise = sender.send(v1Events([msg('u1')]), { signal: controller.signal })
@@ -741,30 +775,41 @@ describe('V1CaptureSender', () => {
   })
 
   describe('backoff and Retry-After', () => {
-    it('uses exponential backoff between attempts', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 4 })
+    it.each<[string, number, number[]]>([
+      ['the lowest jitter', 0, [75, 150, 300]],
+      ['no jitter', 0.5, [100, 200, 400]],
+      ['the highest jitter', 1, [125, 250, 500]],
+    ])('waits 100, 200, 400 ms scaled by %s', async (_label, random, expected) => {
+      const { sender, fetch, sleeps } = makeSender({}, { random: () => random })
       fetch.mockResolvedValue(makeResponse(503))
 
       await sender.send(v1Events([msg('u1')]))
 
-      expect(sleeps).toEqual([100, 200, 400])
+      expect(fetch).toHaveBeenCalledTimes(4)
+      expect(sleeps).toEqual(expected)
     })
 
-    it('caps exponential backoff at maxBackoffMs', async () => {
-      const { sender, fetch, sleeps } = makeSender({
-        initialRetryDelayMs: 10_000,
-        maxBackoffMs: 15_000,
-        maxAttempts: 4,
-      })
+    it('draws a new jitter for each wait', async () => {
+      const draws = [0, 1, 0.5]
+      const { sender, fetch, sleeps } = makeSender({}, { random: () => draws.shift()! })
+      fetch.mockResolvedValue(makeResponse(503))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(sleeps).toEqual([75, 250, 400])
+    })
+
+    it('caps every wait at 30 seconds, after jitter', async () => {
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 9 }, { random: () => 1 })
       fetch.mockResolvedValue(makeResponse(503))
 
       await sender.send(v1Events([msg('u1')]))
 
-      expect(sleeps).toEqual([10_000, 15_000, 15_000])
+      expect(sleeps).toEqual([125, 250, 500, 1000, 2000, 4000, 8000, 16_000, 30_000])
     })
 
-    it('treats Retry-After delta-seconds as a minimum (raises a small backoff)', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 2 })
+    it('raises a shorter wait to a Retry-After in delta-seconds', async () => {
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '5' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -774,23 +819,42 @@ describe('V1CaptureSender', () => {
       expect(sleeps).toEqual([5000])
     })
 
-    it('does not let a small Retry-After shorten a larger backoff', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 10_000, maxAttempts: 2 })
+    it.each<[string, number, number[]]>([
+      ['the lowest jitter', 0, [75, 150, 300, 1000]],
+      ['the highest jitter', 1, [125, 250, 500, 1000]],
+    ])('never lets %s make a wait shorter than Retry-After', async (_label, random, expected) => {
+      // The fourth wait has a base of 800 ms, so jitter alone puts it at 600-1000 ms.
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 4 }, { random: () => random })
       fetch
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(503))
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '1' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
       await sender.send(v1Events([msg('u1')]))
 
-      expect(sleeps).toEqual([10_000])
+      expect(sleeps).toEqual(expected)
     })
 
-    it('clamps a huge Retry-After to maxBackoffMs', async () => {
-      const { sender, fetch, sleeps } = makeSender({
-        initialRetryDelayMs: 100,
-        maxBackoffMs: 30_000,
-        maxAttempts: 2,
-      })
+    it('keeps a jittered backoff that is longer than Retry-After', async () => {
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 5 }, { random: () => 0 })
+      // The fifth wait has a base of 1600 ms; the lowest jitter makes it 1200 ms.
+      fetch
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(503))
+        .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '1' }))
+        .mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(sleeps).toEqual([75, 150, 300, 600, 1200])
+    })
+
+    it('clamps a huge Retry-After to 30 seconds', async () => {
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '9999' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -801,11 +865,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('parses an HTTP-date Retry-After as a delay from now', async () => {
-      const { sender, fetch, sleeps } = makeSender({
-        initialRetryDelayMs: 100,
-        maxBackoffMs: 60_000,
-        maxAttempts: 2,
-      })
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       // 20s after the fixed clock start.
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': 'Mon, 01 Jan 2024 00:00:20 GMT' }))
@@ -816,8 +876,19 @@ describe('V1CaptureSender', () => {
       expect(sleeps).toEqual([20_000])
     })
 
+    it('clamps an HTTP-date Retry-After to 30 seconds', async () => {
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
+      fetch
+        .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': 'Mon, 01 Jan 2024 00:05:00 GMT' }))
+        .mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(sleeps).toEqual([30_000])
+    })
+
     it('ignores a past HTTP-date Retry-After and uses backoff', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 2 })
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': 'Mon, 01 Jan 2020 00:00:00 GMT' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -828,7 +899,7 @@ describe('V1CaptureSender', () => {
     })
 
     it.each(['0', '-5', 'garbage'])('ignores a non-positive/invalid Retry-After (%s)', async (retryAfter) => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 2 })
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': retryAfter }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -839,7 +910,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('ignores a Retry-After so large it parses to a non-finite number of seconds', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 2 })
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(makeResponse(503, '', { 'Retry-After': '9'.repeat(400) }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -850,7 +921,7 @@ describe('V1CaptureSender', () => {
     })
 
     it('honors Retry-After on a 200 partial-retry response', async () => {
-      const { sender, fetch, sleeps } = makeSender({ initialRetryDelayMs: 100, maxAttempts: 2 })
+      const { sender, fetch, sleeps } = makeSender({ maxRetries: 1 })
       fetch
         .mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'retry' } } }, { 'Retry-After': '3' }))
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -869,11 +940,9 @@ describe('V1CaptureSender', () => {
       libraryId: 'posthog-node',
       libraryVersion: '1.2.3',
       historicalMigration: false,
-      compressionEnabled: false,
+      compression: 'none',
       requestTimeoutMs: 1000,
-      maxAttempts: 2,
-      initialRetryDelayMs: 1,
-      maxBackoffMs: 30_000,
+      maxRetries: 1,
     }
 
     it('uses the real clock, request-id generator and sleep when not injected', async () => {
@@ -886,7 +955,8 @@ describe('V1CaptureSender', () => {
       const sender = new V1CaptureSender(baseConfig, { fetch, onError: (e) => errors.push(e) })
       // No injected sleep: the retry backoff schedules a real (fake-timer) setTimeout we must advance.
       const done = sender.send(v1Events([msg('u1')]))
-      await vi.advanceTimersByTimeAsync(baseConfig.initialRetryDelayMs)
+      // The longest first wait, with the highest jitter.
+      await vi.advanceTimersByTimeAsync(125)
       await done
 
       expect(fetch).toHaveBeenCalledTimes(2)
@@ -899,7 +969,7 @@ describe('V1CaptureSender', () => {
     it('cancels the backoff timer when aborted', async () => {
       const fetch = vi.fn<[string, any], Promise<PostHogFetchResponse>>().mockResolvedValue(makeResponse(503))
       const controller = new AbortController()
-      const sender = new V1CaptureSender({ ...baseConfig, initialRetryDelayMs: 10_000 }, { fetch, onError: () => {} })
+      const sender = new V1CaptureSender(baseConfig, { fetch, onError: () => {} })
 
       const done = sender.send(v1Events([msg('u1')]), { signal: controller.signal })
       await vi.advanceTimersByTimeAsync(0)
@@ -921,7 +991,8 @@ describe('V1CaptureSender', () => {
       const sender = new V1CaptureSender(baseConfig, { fetch, onError: () => {} })
 
       const done = sender.send(v1Events([msg('u1')]), { signal })
-      await vi.advanceTimersByTimeAsync(baseConfig.initialRetryDelayMs)
+      // The longest first wait, with the highest jitter.
+      await vi.advanceTimersByTimeAsync(125)
       await done
 
       expect(fetch).toHaveBeenCalledTimes(2)
@@ -931,23 +1002,23 @@ describe('V1CaptureSender', () => {
       expect(leaked).toEqual([])
     })
 
-    it('uses the real gzip compressor when not injected', async () => {
+    it.each(['gzip', 'deflate'] as const)('uses the CompressionStream %s codec when not injected', async (codec) => {
       const fetch = vi
         .fn<[string, any], Promise<PostHogFetchResponse>>()
         .mockResolvedValueOnce(makeResponse(200, { results: {} }))
 
-      const sender = new V1CaptureSender({ ...baseConfig, compressionEnabled: true }, { fetch, onError: () => {} })
+      const sender = new V1CaptureSender({ ...baseConfig, compression: codec }, { fetch, onError: () => {} })
       await sender.send(v1Events([msg('u1')]))
 
-      // The default compressor is the platform gzip codec: it compresses where
-      // supported and transparently falls back to an uncompressed string where it
-      // is not (e.g. the edge runtime has no CompressionStream).
+      // Without CompressionStream (some edge runtimes) the default codec fails and the body goes uncompressed.
+      const [, options] = fetch.mock.calls[0]
       if (isGzipSupported()) {
-        expect(fetch.mock.calls[0][1].headers['Content-Encoding']).toBe('gzip')
-        expect(fetch.mock.calls[0][1].body).toBeInstanceOf(Blob)
+        expect(options.headers['Content-Encoding']).toBe(codec)
+        const decompressed = new Response(new Blob([options.body]).stream().pipeThrough(new DecompressionStream(codec)))
+        expect(JSON.parse(await decompressed.text()).batch[0].uuid).toBe('u1')
       } else {
-        expect(fetch.mock.calls[0][1].headers['Content-Encoding']).toBeUndefined()
-        expect(typeof fetch.mock.calls[0][1].body).toBe('string')
+        expect(options.headers['Content-Encoding']).toBeUndefined()
+        expect(typeof options.body).toBe('string')
       }
     })
   })
diff --git a/packages/node/src/__tests__/capture-v1/wiring.spec.ts b/packages/node/src/__tests__/capture-v1/wiring.spec.ts
index c63ce14969..ef14ce2a6f 100644
--- a/packages/node/src/__tests__/capture-v1/wiring.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/wiring.spec.ts
@@ -94,7 +94,7 @@ describe('capture v1 wiring (Node SDK)', () => {
       ['capture()', ANALYTICS_CAPTURE_PATH],
       ['captureAi()', AI_CAPTURE_PATH],
     ] as const)('uses Node gzip for %s on %s', async (method, path) => {
-      const posthog = makeClient({ disableCompression: false })
+      const posthog = makeClient({ disableCompression: false, captureAiCompression: undefined })
       const event = { distinctId: 'u', event: '$ai_generation', properties: { $ai_model: 'gpt-4o-mini' } }
       if (method === 'capture()') {
         posthog.capture(event)
diff --git a/packages/node/src/__tests__/utils/v1-wiring.ts b/packages/node/src/__tests__/utils/v1-wiring.ts
index d5bd86f85c..6cad9108e2 100644
--- a/packages/node/src/__tests__/utils/v1-wiring.ts
+++ b/packages/node/src/__tests__/utils/v1-wiring.ts
@@ -40,6 +40,8 @@ export class V1WiringHarness {
       host: 'http://example.com',
       fetchRetryCount: 0,
       disableCompression: true,
+      // The AI lane ignores disableCompression.
+      captureAiCompression: 'none',
       ...options,
     })
     this.clients.push(client)
diff --git a/packages/node/src/__tests__/waituntil-flush.spec.ts b/packages/node/src/__tests__/waituntil-flush.spec.ts
index 5daa98d88a..5b1b902425 100644
--- a/packages/node/src/__tests__/waituntil-flush.spec.ts
+++ b/packages/node/src/__tests__/waituntil-flush.spec.ts
@@ -74,6 +74,7 @@ describe('waitUntil debounced flush', () => {
         flushInterval: 60000, // Long interval so timer doesn't trigger
         fetchRetryCount: 0,
         disableCompression: true,
+        captureAiCompression: 'none',
         waitUntil: mockWaitUntil,
         waitUntilDebounceMs: DEBOUNCE_MS,
       })
diff --git a/packages/node/src/capture-lane/limits.ts b/packages/node/src/capture-lane/limits.ts
index c9408b71c2..7cbafe4472 100644
--- a/packages/node/src/capture-lane/limits.ts
+++ b/packages/node/src/capture-lane/limits.ts
@@ -6,5 +6,3 @@ export const ANALYTICS_MAX_EVENT_BYTES = 10 * 1024 * 1024
 
 /** The AI endpoint rejects an event whose serialized `properties` are larger than this. */
 export const AI_MAX_PROPERTIES_BYTES = 8 * 1024 * 1024
-
-export const AI_MAX_QUEUE_SIZE = 1000
diff --git a/packages/node/src/capture-lane/settings.ts b/packages/node/src/capture-lane/settings.ts
new file mode 100644
index 0000000000..c5da0194e3
--- /dev/null
+++ b/packages/node/src/capture-lane/settings.ts
@@ -0,0 +1,119 @@
+import { CAPTURE_COMPRESSIONS, type CaptureCompression } from '../capture-v1/compression'
+import type { PostHogOptions } from '../types'
+
+export const DEFAULT_CAPTURE_MAX_RETRIES = 3
+export const MAX_CAPTURE_MAX_RETRIES = 9
+export const DEFAULT_REQUEST_TIMEOUT_MS = 10_000
+export const DEFAULT_AI_REQUEST_TIMEOUT_MS = 30_000
+export const DEFAULT_AI_MAX_QUEUE_SIZE = 1000
+
+/** Capture settings resolved once per client from `PostHogOptions`. */
+export interface CaptureSettings {
+  /** Retries after the first attempt, for both lanes. */
+  maxRetries: number
+  analytics: CaptureLaneSettings
+  ai: CaptureLaneSettings & {
+    /** Queued AI events; the analytics queue size stays a client setting. */
+    maxQueueSize: number
+  }
+}
+
+export interface CaptureLaneSettings {
+  /** The requested body encoding; the runtime may not support it. */
+  compression: CaptureCompression
+  requestTimeoutMs: number
+}
+
+type LogInvalid = (message: string) => void
+
+const isIntegerInRange = (value: unknown, min: number, max: number): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max
+
+/**
+ * Validates the capture options. An invalid value is reported once through `logInvalid` and
+ * behaves as if it were not set, so a bad option never throws.
+ */
+export function resolveCaptureSettings(options: PostHogOptions, logInvalid: LogInvalid): CaptureSettings {
+  return {
+    maxRetries: resolveMaxRetries(options, logInvalid),
+    analytics: {
+      compression:
+        resolveCompression('captureCompression', options.captureCompression, logInvalid) ??
+        (options.disableCompression ? 'none' : 'gzip'),
+      requestTimeoutMs: options.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    },
+    ai: {
+      // The AI lane does not read captureCompression or disableCompression.
+      compression: resolveCompression('captureAiCompression', options.captureAiCompression, logInvalid) ?? 'gzip',
+      requestTimeoutMs: resolvePositive(
+        'captureAiRequestTimeoutMs',
+        options.captureAiRequestTimeoutMs,
+        DEFAULT_AI_REQUEST_TIMEOUT_MS,
+        logInvalid,
+        { integer: false }
+      ),
+      maxQueueSize: resolvePositive(
+        'captureAiMaxQueueSize',
+        options.captureAiMaxQueueSize,
+        DEFAULT_AI_MAX_QUEUE_SIZE,
+        logInvalid,
+        { integer: true }
+      ),
+    },
+  }
+}
+
+function resolveCompression(name: string, value: unknown, logInvalid: LogInvalid): CaptureCompression | undefined {
+  if (value == null) {
+    return undefined
+  }
+  if ((CAPTURE_COMPRESSIONS as readonly unknown[]).includes(value)) {
+    return value as CaptureCompression
+  }
+  logInvalid(
+    `${name} must be one of ${CAPTURE_COMPRESSIONS.map((codec) => `'${codec}'`).join(', ')}; using the default.`
+  )
+  return undefined
+}
+
+// Node clamps a timer delay above this to 1 ms, which would time out every request.
+const MAX_SETTING_VALUE = 2_147_483_647
+
+function resolvePositive(
+  name: string,
+  value: unknown,
+  fallback: number,
+  logInvalid: LogInvalid,
+  { integer }: { integer: boolean }
+): number {
+  if (value == null) {
+    return fallback
+  }
+  if (
+    typeof value === 'number' &&
+    value > 0 &&
+    value <= MAX_SETTING_VALUE &&
+    (integer ? Number.isSafeInteger(value) : Number.isFinite(value))
+  ) {
+    return value
+  }
+  logInvalid(
+    `${name} must be a positive ${integer ? 'integer' : 'number'} up to ${MAX_SETTING_VALUE}; using the default.`
+  )
+  return fallback
+}
+
+function resolveMaxRetries(options: PostHogOptions, logInvalid: LogInvalid): number {
+  const { captureMaxRetries, fetchRetryCount } = options
+  if (captureMaxRetries != null) {
+    if (isIntegerInRange(captureMaxRetries, 0, MAX_CAPTURE_MAX_RETRIES)) {
+      return captureMaxRetries
+    }
+    logInvalid(`captureMaxRetries must be an integer from 0 to ${MAX_CAPTURE_MAX_RETRIES}; using the default.`)
+  }
+  // fetchRetryCount also configures other requests, so an out-of-range value is clamped for capture, not reported.
+  if (typeof fetchRetryCount === 'number' && Number.isFinite(fetchRetryCount)) {
+    return Math.min(Math.max(Math.trunc(fetchRetryCount), 0), MAX_CAPTURE_MAX_RETRIES)
+  }
+  return DEFAULT_CAPTURE_MAX_RETRIES
+}
diff --git a/packages/node/src/capture-v1/compression.ts b/packages/node/src/capture-v1/compression.ts
new file mode 100644
index 0000000000..403ff2f222
--- /dev/null
+++ b/packages/node/src/capture-v1/compression.ts
@@ -0,0 +1,50 @@
+import { gzipCompress, isGzipSupported } from '@posthog/core'
+
+export const CAPTURE_COMPRESSIONS = ['none', 'gzip', 'deflate', 'zstd'] as const
+
+/** A capture request body encoding; `deflate` is zlib-wrapped, as HTTP `Content-Encoding: deflate` requires. */
+export type CaptureCompression = (typeof CAPTURE_COMPRESSIONS)[number]
+
+export type CaptureCodec = Exclude<CaptureCompression, 'none'>
+
+/** Compresses capture request bodies with the codecs one runtime provides. */
+export interface CaptureCompressor {
+  supports(codec: CaptureCodec): boolean
+  /** Resolves to null, or rejects, when compression fails; the sender then sends the body uncompressed. */
+  compress(payload: string, codec: CaptureCodec): Promise<Uint8Array | null>
+}
+
+/** Uses CompressionStream, so it works wherever the runtime has one. It has no zstd. */
+export const webCompressor: CaptureCompressor = {
+  supports: (codec) => codec !== 'zstd' && isGzipSupported(),
+  async compress(payload, codec) {
+    if (codec === 'gzip') {
+      const compressed = await gzipCompress(payload, false)
+      return compressed && new Uint8Array(await compressed.arrayBuffer())
+    }
+    if (codec !== 'deflate') {
+      return null
+    }
+    const stream = new Response(payload).body!.pipeThrough(new globalThis.CompressionStream('deflate'))
+    return new Uint8Array(await new Response(stream).arrayBuffer())
+  },
+}
+
+/**
+ * The codec a lane sends with: `requested` when the runtime has it, gzip in place of an unavailable
+ * zstd, or no compression when the runtime cannot compress at all.
+ */
+export function resolveCaptureCodec(
+  requested: CaptureCompression,
+  compressor: CaptureCompressor,
+  onZstdUnavailable: (fallback: CaptureCompression) => void
+): CaptureCompression {
+  if (requested === 'none' || compressor.supports(requested)) {
+    return requested
+  }
+  const fallback = compressor.supports('gzip') ? 'gzip' : 'none'
+  if (requested === 'zstd') {
+    onZstdUnavailable(fallback)
+  }
+  return fallback
+}
diff --git a/packages/node/src/capture-v1/sender.ts b/packages/node/src/capture-v1/sender.ts
index 8fdb5cf71d..6b95edc2ef 100644
--- a/packages/node/src/capture-v1/sender.ts
+++ b/packages/node/src/capture-v1/sender.ts
@@ -1,17 +1,14 @@
-import {
-  type FetchLike,
-  type PostHogFetchBodyBytes,
-  type PostHogFetchOptions,
-  type PostHogFetchResponse,
-  gzipCompress,
-  uuidv7,
-} from '@posthog/core'
+import { type FetchLike, type PostHogFetchOptions, type PostHogFetchResponse, uuidv7 } from '@posthog/core'
 
+import { type CaptureCodec, type CaptureCompression, webCompressor } from './compression'
 import { CaptureError, type CaptureDroppedEvent, type CaptureErrorParams } from './errors'
 import { type SerializedV1Event, buildV1Body } from './serialize'
 import type { CaptureEndpoint, V1BatchResponse } from './types'
 
-const DEFAULT_MAX_BACKOFF_MS = 30_000
+/** Wait before the first retry; each later retry doubles it. */
+export const RETRY_BASE_DELAY_MS = 100
+/** Ceiling for every retry wait, including one raised by `Retry-After`. */
+export const MAX_RETRY_DELAY_MS = 30_000
 
 // Retry waits and request deadlines use ref'd timers, unlike safeSetTimeout, so an
 // awaited flush or shutdown keeps the process alive until the send finishes.
@@ -56,8 +53,8 @@ function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
   })
 }
 
-/** HTTP statuses the v1 backend wants retried. 429 is intentionally terminal in v1. */
-const RETRYABLE_STATUSES = new Set([408, 500, 502, 503, 504])
+/** HTTP statuses a capture request is retried on. 404 and 429 can come from a proxy in front of capture. */
+const RETRYABLE_STATUSES = new Set([404, 408, 429, 500, 502, 503, 504])
 
 export interface V1CaptureSenderConfig {
   host: string
@@ -70,15 +67,11 @@ export interface V1CaptureSenderConfig {
   /** Value for the `User-Agent` header, if the runtime allows setting it. */
   userAgent?: string
   historicalMigration: boolean
-  /** When true, the body is gzip-compressed (falling back to uncompressed on failure). */
-  compressionEnabled: boolean
+  /** The body encoding; a body that fails to compress is sent uncompressed. */
+  compression: CaptureCompression
   requestTimeoutMs: number
-  /** Total attempts, including the first (1 initial + N retries). */
-  maxAttempts: number
-  /** Base exponential backoff, doubled each retry and capped at `maxBackoffMs`. */
-  initialRetryDelayMs: number
-  /** Single ceiling for both the backoff schedule and the `Retry-After` clamp. */
-  maxBackoffMs?: number
+  /** Retries after the first attempt. */
+  maxRetries: number
   isDebug?: boolean
 }
 
@@ -90,7 +83,9 @@ export interface V1CaptureSenderHooks {
   /** Waits between attempts. The sender stops waiting when `signal` aborts, even if this does not. */
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>
   generateRequestId?: () => string
-  compress?: (payload: string, isDebug?: boolean) => Promise<Blob | PostHogFetchBodyBytes | null>
+  /** Uniform in [0, 1); sets the jitter of each retry wait. */
+  random?: () => number
+  compress?: (payload: string, codec: CaptureCodec) => Promise<Uint8Array | null>
 }
 
 export interface V1SendOptions {
@@ -125,23 +120,23 @@ interface V1CaptureAttempt {
  */
 export class V1CaptureSender {
   private readonly config: V1CaptureSenderConfig
-  private readonly maxBackoffMs: number
   private readonly fetchFn: FetchLike
   private readonly onError: (error: Error) => void
   private readonly now: () => number
   private readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>
   private readonly generateRequestId: () => string
-  private readonly compress: (payload: string, isDebug?: boolean) => Promise<Blob | PostHogFetchBodyBytes | null>
+  private readonly random: () => number
+  private readonly compress: (payload: string, codec: CaptureCodec) => Promise<Uint8Array | null>
 
   constructor(config: V1CaptureSenderConfig, hooks: V1CaptureSenderHooks) {
     this.config = config
-    this.maxBackoffMs = config.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS
     this.fetchFn = hooks.fetch
     this.onError = hooks.onError
     this.now = hooks.now ?? Date.now
     this.sleep = hooks.sleep ?? abortableSleep
     this.generateRequestId = hooks.generateRequestId ?? uuidv7
-    this.compress = hooks.compress ?? gzipCompress
+    this.random = hooks.random ?? Math.random
+    this.compress = hooks.compress ?? webCompressor.compress
   }
 
   /** Sends `events` and resolves with the ones to queue again (always empty unless `keepUnsent`). */
@@ -167,10 +162,9 @@ export class V1CaptureSender {
       return []
     }
 
-    // Guard against a misconfigured budget (e.g. fetchRetryCount: -1): always make
-    // at least one attempt so a bad config surfaces a delivery error instead of
-    // silently dropping the batch without ever sending or calling onError.
-    const maxAttempts = Math.max(1, this.config.maxAttempts)
+    // Always make one attempt, so a bad budget reports a delivery error instead of dropping the batch silently.
+    const { maxRetries } = this.config
+    const maxAttempts = (Number.isInteger(maxRetries) && maxRetries > 0 ? maxRetries : 0) + 1
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       if (signal?.aborted) {
         return unsent(signal.reason)
@@ -281,16 +275,8 @@ export class V1CaptureSender {
     externalSignal: AbortSignal | undefined
   ): Promise<V1CaptureAttempt> {
     const headers = this.buildHeaders(attempt, requestId)
-    let body: string | Blob | PostHogFetchBodyBytes = payload
-    if (this.config.compressionEnabled) {
-      // Compression runs on the libuv pool, so a busy pool must not hold the request past an external deadline.
-      const compressed = await raceAbort(this.compress(payload, this.config.isDebug), externalSignal)
-      if (compressed !== null) {
-        body = compressed
-        headers['Content-Encoding'] = 'gzip'
-      }
-      // A codec that fails to compress falls back to sending uncompressed.
-    }
+    // Compression runs on the libuv pool, so a busy pool must not hold the request past an external deadline.
+    const body = await raceAbort(this.encodeBody(payload, headers), externalSignal)
 
     const controller = new AbortController()
     let timeoutPhase = 'waiting for response headers'
@@ -335,7 +321,13 @@ export class V1CaptureSender {
     // Keeps an early abort from surfacing as an unhandled rejection before the race below observes it.
     deadline.catch(() => {})
     try {
-      const fetchPromise = this.fetchFn(url, { method: 'POST', headers, body, signal: controller.signal })
+      // A fresh copy per request: fetch may detach a byte body it has sent.
+      const fetchPromise = this.fetchFn(url, {
+        method: 'POST',
+        headers,
+        body: typeof body === 'string' ? body : body.slice(),
+        signal: controller.signal,
+      })
       let responseAccepted = false
       void fetchPromise
         .then((lateResponse) => {
@@ -378,6 +370,26 @@ export class V1CaptureSender {
     }
   }
 
+  /** Compresses `payload` with the configured codec and sets `Content-Encoding` to match. */
+  private async encodeBody(payload: string, headers: PostHogFetchOptions['headers']): Promise<string | Uint8Array> {
+    const codec = this.config.compression
+    if (codec === 'none') {
+      return payload
+    }
+    try {
+      const compressed = await this.compress(payload, codec)
+      if (compressed !== null) {
+        headers['Content-Encoding'] = codec
+        return compressed
+      }
+    } catch (error) {
+      if (this.config.isDebug) {
+        console.error(`Failed to ${codec} compress the capture request body`, error)
+      }
+    }
+    return payload
+  }
+
   private buildHeaders(attempt: number, requestId: string): PostHogFetchOptions['headers'] {
     const sdkInfo = `${this.config.libraryId}/${this.config.libraryVersion}`
     const headers: { [key: string]: string } = {
@@ -422,13 +434,15 @@ export class V1CaptureSender {
     return retryable
   }
 
+  /** The wait after failed attempt `attempt` (1-based): jittered exponential backoff, raised to `Retry-After`. */
   private backoffDelay(attempt: number, retryAfterMs?: number): number {
-    const exponential = Math.min(this.config.initialRetryDelayMs * 2 ** (attempt - 1), this.maxBackoffMs)
+    const jitter = 0.75 + 0.5 * this.random()
+    const backoff = Math.min(RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) * jitter, MAX_RETRY_DELAY_MS)
     if (retryAfterMs === undefined) {
-      return exponential
+      return backoff
     }
-    // Retry-After is a minimum (never lets us retry earlier than our own backoff) and is clamped to the ceiling.
-    return Math.max(exponential, Math.min(retryAfterMs, this.maxBackoffMs))
+    // Compared after jitter, so jitter can never make the wait shorter than Retry-After.
+    return Math.max(backoff, Math.min(retryAfterMs, MAX_RETRY_DELAY_MS))
   }
 
   /** Parse `Retry-After` (delta-seconds or HTTP-date). Non-positive/past values are ignored. */
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index 413adf67c6..583a368656 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -74,12 +74,9 @@ import { V1CaptureSender, type V1CaptureSenderConfig } from './capture-v1/sender
 import { AI_CAPTURE_ENDPOINT, ANALYTICS_CAPTURE_ENDPOINT, type CaptureEndpoint } from './capture-v1/types'
 import type { CaptureError } from './capture-v1/errors'
 import { CaptureLane, type CaptureLaneConfig } from './capture-lane/lane'
-import {
-  AI_MAX_PROPERTIES_BYTES,
-  AI_MAX_QUEUE_SIZE,
-  ANALYTICS_MAX_EVENT_BYTES,
-  CAPTURE_BATCH_TARGET_BYTES,
-} from './capture-lane/limits'
+import { AI_MAX_PROPERTIES_BYTES, ANALYTICS_MAX_EVENT_BYTES, CAPTURE_BATCH_TARGET_BYTES } from './capture-lane/limits'
+import { type CaptureSettings, resolveCaptureSettings } from './capture-lane/settings'
+import { type CaptureCompressor, resolveCaptureCodec, webCompressor } from './capture-v1/compression'
 import { AI_CAPTURE_ROUTE } from './ai-capture/routing'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
@@ -168,6 +165,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
   // Created on first use, so a client that never calls captureAi has no AI lane.
   private readonly _captureLanes = new Map<CaptureEndpoint, CaptureLane>()
+  private readonly _captureSettings: CaptureSettings
   /** Whether this client captures full AI content: see `enableFullAiCapture` in `PostHogOptions`. */
   public readonly enableFullAiCapture: boolean
   /** Whether PostHog AI integrations redact content: see `privacyMode` in `PostHogOptions`. */
@@ -255,6 +253,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     this.options = normalizedOptions
     this.warnIfCaptureModeSet()
+    // console.error, not this._logger: the logger only prints in debug mode, and a bad option changes delivery.
+    this._captureSettings = resolveCaptureSettings(normalizedOptions, (message) =>
+      console.error(`[PostHog] ${message}`)
+    )
     this.enableFullAiCapture = normalizedOptions.enableFullAiCapture === true
     this.privacyMode = normalizedOptions.privacyMode === true
     this.context = this.initializeContext()
@@ -573,11 +575,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     const endpoint = route === AI_CAPTURE_ROUTE ? AI_CAPTURE_ENDPOINT : ANALYTICS_CAPTURE_ENDPOINT
     let lane = this._captureLanes.get(endpoint)
     if (!lane) {
+      const compressor = this.captureCompressor()
       lane = new CaptureLane(this._captureLaneConfig(endpoint), {
-        sender: new V1CaptureSender(this.captureSenderConfig(endpoint), {
+        sender: new V1CaptureSender(this.captureSenderConfig(endpoint, compressor), {
           fetch: (url, fetchOptions) => this.fetch(url, fetchOptions),
           onError: (error) => this._events.emit('error', error),
-          compress: (payload) => this.compressPayload(payload),
+          compress: (payload, codec) => compressor.compress(payload, codec),
         }),
         onLocalDrops: (error) => this._reportLocalCaptureDrops(error),
         onError: (error) => this._events.emit('error', error),
@@ -592,13 +595,17 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
   private _captureLaneConfig(endpoint: CaptureEndpoint): CaptureLaneConfig {
     const isAi = endpoint === AI_CAPTURE_ENDPOINT
+    // The AI queue cap bounds memory for large events, so it is kept as set and the AI lane flushes no later than when
+    // its queue is full. The analytics queue keeps its floor at flushAt, so the flushAt trigger can always fire.
+    const flushAt = isAi ? Math.min(this.flushAt, this._captureSettings.ai.maxQueueSize) : this.flushAt
     return {
       endpoint,
-      flushAt: this.flushAt,
+      flushAt,
       flushIntervalMs: this.options.flushInterval ?? 5000,
-      maxBatchSize: Math.max(this.flushAt, this.options.maxBatchSize ?? 100),
-      // Never below flushAt, or the flushAt trigger could never fire.
-      maxQueueSize: Math.max(this.flushAt, isAi ? AI_MAX_QUEUE_SIZE : (this.options.maxQueueSize ?? 10000)),
+      maxBatchSize: Math.max(flushAt, this.options.maxBatchSize ?? 100),
+      maxQueueSize: isAi
+        ? this._captureSettings.ai.maxQueueSize
+        : Math.max(this.flushAt, this.options.maxQueueSize ?? 10000),
       targetBatchBytes: CAPTURE_BATCH_TARGET_BYTES,
       maxEventBytes: isAi ? AI_MAX_PROPERTIES_BYTES : ANALYTICS_MAX_EVENT_BYTES,
       maxEventBytesOf: isAi ? 'properties' : 'event',
@@ -614,8 +621,21 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
   }
 
-  /** Every lane shares the client's retry, timeout and compression settings. */
-  private captureSenderConfig(path: CaptureEndpoint): V1CaptureSenderConfig {
+  /**
+   * Compresses capture request bodies. The edge build uses CompressionStream; the Node
+   * entrypoint overrides this with node:zlib.
+   *
+   * @internal
+   */
+  protected captureCompressor(): CaptureCompressor {
+    return webCompressor
+  }
+
+  private captureSenderConfig(path: CaptureEndpoint, compressor: CaptureCompressor): V1CaptureSenderConfig {
+    const laneSettings = path === AI_CAPTURE_ENDPOINT ? this._captureSettings.ai : this._captureSettings.analytics
+    const compression = resolveCaptureCodec(laneSettings.compression, compressor, (fallback) =>
+      this._logger.debug(`zstd compression is not available in this runtime; ${path} uses ${fallback} instead`)
+    )
     return {
       host: this.host,
       path,
@@ -624,11 +644,9 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       libraryVersion: this.getLibraryVersion(),
       userAgent: this.getCustomUserAgent() || undefined,
       historicalMigration: this.historicalMigration,
-      compressionEnabled: !this.disableCompression,
-      requestTimeoutMs: this.requestTimeout,
-      // 1 initial attempt + fetchRetryCount retries.
-      maxAttempts: (this.options.fetchRetryCount ?? 3) + 1,
-      initialRetryDelayMs: this.options.fetchRetryDelay ?? 3000,
+      compression,
+      requestTimeoutMs: laneSettings.requestTimeoutMs,
+      maxRetries: this._captureSettings.maxRetries,
       isDebug: this.isDebug,
     }
   }
diff --git a/packages/node/src/compression.node.ts b/packages/node/src/compression.node.ts
new file mode 100644
index 0000000000..4ac3a88338
--- /dev/null
+++ b/packages/node/src/compression.node.ts
@@ -0,0 +1,30 @@
+import * as zlib from 'node:zlib'
+import { promisify } from 'node:util'
+
+import type { CaptureCodec, CaptureCompressor } from './capture-v1/compression'
+
+type ZlibCompress = typeof zlib.gzip
+
+/** The zlib functions the compressor uses; `zstdCompress` exists from Node 22.15. */
+export interface ZlibCodecs {
+  gzip: ZlibCompress
+  deflate: ZlibCompress
+  zstdCompress?: ZlibCompress
+}
+
+export function createZlibCompressor(codecs: ZlibCodecs = zlib as ZlibCodecs): CaptureCompressor {
+  const compressors: Record<CaptureCodec, ((input: string) => Promise<Buffer>) | undefined> = {
+    gzip: promisify(codecs.gzip),
+    deflate: promisify(codecs.deflate),
+    zstd: typeof codecs.zstdCompress === 'function' ? promisify(codecs.zstdCompress) : undefined,
+  }
+  return {
+    supports: (codec) => compressors[codec] !== undefined,
+    async compress(payload, codec) {
+      const compress = compressors[codec]
+      return compress ? new Uint8Array(await compress(payload)) : null
+    },
+  }
+}
+
+export const zlibCompressor = createZlibCompressor()
diff --git a/packages/node/src/entrypoints/index.node.ts b/packages/node/src/entrypoints/index.node.ts
index c456c50645..963b795e78 100644
--- a/packages/node/src/entrypoints/index.node.ts
+++ b/packages/node/src/entrypoints/index.node.ts
@@ -10,6 +10,8 @@ import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
 import type { SpanContextManager } from '@posthog/core'
 import { PostHogContext } from '../extensions/context/context'
 import { AsyncLocalStorageSpanContextManager } from '../extensions/context/span-context.node'
+import type { CaptureCompressor } from '../capture-v1/compression'
+import { zlibCompressor } from '../compression.node'
 import { gzipCompress } from '../gzip.node'
 import { hostOsResourceAttributes } from '../host-os.node'
 
@@ -22,6 +24,10 @@ export class PostHog extends PostHogBackendClient {
     return gzipCompress(payload, this.isDebug)
   }
 
+  protected override captureCompressor(): CaptureCompressor {
+    return zlibCompressor
+  }
+
   protected initializeContext(): PostHogContext {
     return new PostHogContext()
   }
diff --git a/packages/node/src/types.ts b/packages/node/src/types.ts
index fa2c9cc7bc..81f4ec15f0 100644
--- a/packages/node/src/types.ts
+++ b/packages/node/src/types.ts
@@ -166,7 +166,16 @@ export type FeatureFlagEvaluationRuntime = 'all' | 'client' | 'server'
 
 export type BeforeSendFn = (event: EventMessage) => EventMessage | null
 
-export type PostHogOptions = Omit<PostHogCoreOptions, 'before_send' | 'flushInterval' | 'maxQueueSize'> & {
+export type PostHogOptions = Omit<
+  PostHogCoreOptions,
+  | 'before_send'
+  | 'flushInterval'
+  | 'maxQueueSize'
+  | 'fetchRetryCount'
+  | 'fetchRetryDelay'
+  | 'disableCompression'
+  | 'requestTimeout'
+> & {
   persistence?: 'memory'
   /**
    * The interval in milliseconds between periodic flushes
@@ -177,11 +186,74 @@ export type PostHogOptions = Omit<PostHogCoreOptions, 'before_send' | 'flushInte
   /**
    * The maximum number of analytics events held in memory waiting to be sent (must be higher than `flushAt`).
    * When the queue is full, the oldest event is dropped and reported through the `'error'` event.
-   * `captureAi` events have their own queue and do not count toward this limit.
+   * `captureAi` events have their own queue, sized by `captureAiMaxQueueSize`, and do not count toward this limit.
    *
    * @default 10000
    */
   maxQueueSize?: number
+  /**
+   * How many times a capture request is retried after its first attempt, on both capture lanes.
+   * Waits start at 100 ms and double each retry, with jitter, up to 30 seconds; a `Retry-After`
+   * header can raise a wait. Only HTTP 404, 408, 429, 500, 502, 503 and 504 and network errors are retried.
+   * When not set, `fetchRetryCount` is used.
+   *
+   * @default 3
+   */
+  captureMaxRetries?: number
+  /**
+   * How many times HTTP requests are retried. Capture requests use `captureMaxRetries` when it is set.
+   *
+   * @default 3
+   */
+  fetchRetryCount?: number
+  /**
+   * The delay between HTTP request retries in milliseconds. Capture requests do not use it:
+   * see `captureMaxRetries` for their retry waits.
+   *
+   * @default 3000
+   */
+  fetchRetryDelay?: number
+  /**
+   * How analytics capture requests compress their body. `'deflate'` is zlib-wrapped. `'zstd'` needs
+   * Node 22.15 or later and falls back to `'gzip'` elsewhere, including the edge build. When not set,
+   * `disableCompression: true` means `'none'`.
+   *
+   * @default 'gzip'
+   */
+  captureCompression?: 'none' | 'gzip' | 'deflate' | 'zstd'
+  /**
+   * How `captureAi` requests compress their body, with the same values as `captureCompression`.
+   * It does not read `captureCompression` or `disableCompression`.
+   *
+   * @default 'gzip'
+   */
+  captureAiCompression?: 'none' | 'gzip' | 'deflate' | 'zstd'
+  /**
+   * Timeout in milliseconds for any calls. `captureAi` requests use `captureAiRequestTimeoutMs`.
+   *
+   * @default 10000
+   */
+  requestTimeout?: number
+  /**
+   * The maximum number of `captureAi` events held in memory waiting to be sent. When the queue is
+   * full, the oldest AI event is dropped and reported through the `'error'` event.
+   *
+   * @default 1000
+   */
+  captureAiMaxQueueSize?: number
+  /**
+   * Timeout in milliseconds for each `captureAi` request. Analytics capture requests use `requestTimeout`.
+   *
+   * @default 30000
+   */
+  captureAiRequestTimeoutMs?: number
+  /**
+   * Whether to disable GZIP compression. Analytics capture requests use `captureCompression` when it
+   * is set, and `captureAi` requests use `captureAiCompression`.
+   *
+   * @default false
+   */
+  disableCompression?: boolean
   /**
    * Configuration for the `posthog.metrics` API (count, gauge, histogram).
    * Set `serviceName` so series can be filtered per service in the Metrics UI.

From 47eded7406e49a390e21b2a60e0c824854fc4ff3 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:16:07 -0700
Subject: [PATCH 08/20] feat(node)!: capture redirect, uuid and duplicate rules
 (#5416)

* feat(core): add an optional redirect mode to PostHogFetchOptions

Type-only and additive: no core runtime change. It lets posthog-node send capture requests with `redirect: 'manual'`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: follow only same-origin 307 and 308 capture redirects

Capture requests use redirect: 'manual' and follow a 307 or 308 whose Location
has the configured host's origin, at most 5 times, with the same method,
headers and a fresh copy of the body. Any other redirect is a final failure
reported as a CaptureError. A custom fetch that follows redirects itself
still works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): send event uuids in canonical form

Before an event is queued or sent, and again after before_send, its uuid must
be 32 hex digits, the hyphenated form, the braced hyphenated form or the
urn:uuid: form, in any case; it is sent lowercase and hyphenated, and results
match by that form. Any other uuid is replaced with a generated v7 uuid and one
warning that does not repeat the value. An empty or missing uuid is generated
silently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): report copies the server dropped as duplicates

When a 2xx result carries duplicates_dropped: n, the first event with that
uuid in the request takes the result, the next n are reported as drops with
details duplicate_event_uuid and are never retried, and later copies take the
kept result. Values that are not positive integers are ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): log one line per batch that loses capture events

With no 'error' listener, a batch that loses events (server drops, exhausted
retries, a final request failure) and a lane flush that drops events locally
each log one console line. It names the lane, the count of events not
delivered and each cause with its HTTP status, and never includes server
response text, event content or uuids. With a listener there is no line: the
listener gets the CaptureError as before. Local drops at shutdown now arrive
in one report.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for capture redirects, uuids and duplicates

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(react-native): regenerate the public API references

The optional `redirect` field on `PostHogFetchOptions` is part of the React
Native public API.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): warn once per call for an invalid uuid, add a core changeset for the redirect option

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-core-fetch-redirect.md     |   5 +
 .../posthog-node-capture-sender-rules.md      |   5 +
 packages/core/src/types.ts                    |   1 +
 .../posthog-node-references-latest.json       |   6 +-
 .../src/__tests__/ai-capture/wiring.spec.ts   |   2 +-
 .../src/__tests__/capture-lane/lane.spec.ts   |  28 ++-
 .../__tests__/capture-v1/loss-summary.spec.ts | 212 +++++++++++++++++
 .../capture-v1/redirect-undici.spec.ts        |  76 +++++++
 .../src/__tests__/capture-v1/sender.spec.ts   | 215 ++++++++++++++++++
 .../src/__tests__/capture-v1/uuid.spec.ts     | 153 +++++++++++++
 packages/node/src/capture-lane/lane.ts        |  78 ++++---
 packages/node/src/capture-v1/errors.ts        |  32 +++
 packages/node/src/capture-v1/sender.ts        | 213 ++++++++++++++---
 packages/node/src/capture-v1/types.ts         |   2 +
 packages/node/src/capture-v1/uuid.ts          |  20 ++
 packages/node/src/client.ts                   |  64 +++++-
 ...osthog-react-native-references-latest.json |   4 +
 17 files changed, 1033 insertions(+), 83 deletions(-)
 create mode 100644 .changeset/posthog-core-fetch-redirect.md
 create mode 100644 .changeset/posthog-node-capture-sender-rules.md
 create mode 100644 packages/node/src/__tests__/capture-v1/loss-summary.spec.ts
 create mode 100644 packages/node/src/__tests__/capture-v1/redirect-undici.spec.ts
 create mode 100644 packages/node/src/__tests__/capture-v1/uuid.spec.ts
 create mode 100644 packages/node/src/capture-v1/uuid.ts

diff --git a/.changeset/posthog-core-fetch-redirect.md b/.changeset/posthog-core-fetch-redirect.md
new file mode 100644
index 0000000000..7460224fbc
--- /dev/null
+++ b/.changeset/posthog-core-fetch-redirect.md
@@ -0,0 +1,5 @@
+---
+'@posthog/core': patch
+---
+
+`PostHogFetchOptions` has an optional `redirect` field, so a custom `fetch` sees how capture asks it to handle redirects.
diff --git a/.changeset/posthog-node-capture-sender-rules.md b/.changeset/posthog-node-capture-sender-rules.md
new file mode 100644
index 0000000000..58acea1e4a
--- /dev/null
+++ b/.changeset/posthog-node-capture-sender-rules.md
@@ -0,0 +1,5 @@
+---
+'posthog-node': major
+---
+
+Capture follows only same-origin 307 and 308 redirects; invalid event uuids are replaced with a warning, and dropped duplicate copies are reported.
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index 9c1475e472..928181bf6a 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -309,6 +309,7 @@ export type PostHogFetchOptions = {
   headers: { [key: string]: string }
   body?: string | Blob | PostHogFetchBodyBytes
   signal?: AbortSignal
+  redirect?: 'follow' | 'manual' | 'error'
 }
 
 // Check out posthog-js for these additional options and try to keep them in sync
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index 9eebd8cc0b..1c74ef5d75 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -3514,6 +3514,10 @@
         {
           "type": "AbortSignal",
           "name": "signal"
+        },
+        {
+          "type": "\"follow\" | \"manual\" | \"error\"",
+          "name": "redirect"
         }
       ],
       "path": "../core/src/types.ts"
@@ -4345,7 +4349,7 @@
           "name": "prefix"
         },
         {
-          "type": "(\"fatal\" | \"error\" | \"warning\" | \"log\" | \"info\" | \"debug\")[] | \"*\"",
+          "type": "(\"error\" | \"fatal\" | \"warning\" | \"log\" | \"info\" | \"debug\")[] | \"*\"",
           "name": "severityAllowList"
         },
         {
diff --git a/packages/node/src/__tests__/ai-capture/wiring.spec.ts b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
index ddb8540193..c0a4c17e24 100644
--- a/packages/node/src/__tests__/ai-capture/wiring.spec.ts
+++ b/packages/node/src/__tests__/ai-capture/wiring.spec.ts
@@ -124,7 +124,7 @@ describe('AI capture lane wiring (Node SDK)', () => {
 
     expect(console.warn).toHaveBeenCalledTimes(1)
     expect(console.warn).toHaveBeenCalledWith(
-      `[PostHog] Dropped 2 event(s) for ${AI_CAPTURE_PATH} before sending: 2 with properties larger than 8388608 bytes`
+      `[PostHog] 2 event(s) were not delivered to ${AI_CAPTURE_PATH}: 2 dropped because their properties were larger than 8388608 bytes`
     )
   })
 
diff --git a/packages/node/src/__tests__/capture-lane/lane.spec.ts b/packages/node/src/__tests__/capture-lane/lane.spec.ts
index c3a129456c..bfa3b59aab 100644
--- a/packages/node/src/__tests__/capture-lane/lane.spec.ts
+++ b/packages/node/src/__tests__/capture-lane/lane.spec.ts
@@ -37,6 +37,8 @@ function makeLane(config: Partial<CaptureLaneConfig> = {}, behavior: SendBehavio
   const batches: string[][] = []
   const flushes: string[][] = []
   const localDrops: CaptureError[] = []
+  // One entry per report: a report can carry several errors but has one summary line.
+  const summaries: string[] = []
   const errors: unknown[] = []
   const backgroundFlushes: Promise<void>[] = []
   let currentBehavior = behavior
@@ -58,7 +60,10 @@ function makeLane(config: Partial<CaptureLaneConfig> = {}, behavior: SendBehavio
     },
     {
       sender: { send: send as any },
-      onLocalDrops: (error) => localDrops.push(error),
+      onLocalDrops: (reported, summary) => {
+        localDrops.push(...reported)
+        summaries.push(summary)
+      },
       onError: (error) => errors.push(error),
       onFlush: (messages) => flushes.push(messages.map((message) => String(message.uuid))),
       onBackgroundFlush: (flush) => backgroundFlushes.push(flush),
@@ -68,7 +73,7 @@ function makeLane(config: Partial<CaptureLaneConfig> = {}, behavior: SendBehavio
   const setBehavior = (next: SendBehavior): void => {
     currentBehavior = next
   }
-  return { lane, send, batches, flushes, localDrops, errors, backgroundFlushes, setBehavior }
+  return { lane, send, batches, flushes, localDrops, summaries, errors, backgroundFlushes, setBehavior }
 }
 
 const ids = (count: number, from = 1): string[] => Array.from({ length: count }, (_, i) => `u${from + i}`)
@@ -398,6 +403,25 @@ describe('CaptureLane', () => {
       expect(lane.length).toBe(0)
     })
 
+    it('reports leftovers and local drops at shutdown in one report with one summary line', async () => {
+      const { lane, localDrops, summaries } = makeLane({ maxQueueSize: 2, maxEventBytes: 500 }, abortable)
+      lane.enqueue(msg(1, { pad: 'x'.repeat(1000) }))
+      lane.enqueue(msg(2))
+      lane.enqueue(msg(3))
+      lane.enqueue(msg(4))
+
+      lane.finishShutdown()
+
+      expect(localDrops.map((error) => [error.retryExhausted, error.drops.map((drop) => drop.uuid)])).toEqual([
+        [['u3', 'u4'], []],
+        [[], ['u1', 'u2']],
+      ])
+      expect(summaries).toEqual([
+        '4 event(s) were not delivered to /i/v1/analytics/events: 2 still queued when shutdown ended, ' +
+          '1 dropped because the queue was full (2 events), 1 dropped because they were larger than 500 bytes',
+      ])
+    })
+
     it('drains events enqueued while an earlier flush was in flight', async () => {
       let release!: () => void
       const { lane, batches, setBehavior } = makeLane()
diff --git a/packages/node/src/__tests__/capture-v1/loss-summary.spec.ts b/packages/node/src/__tests__/capture-v1/loss-summary.spec.ts
new file mode 100644
index 0000000000..7f512b47e9
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/loss-summary.spec.ts
@@ -0,0 +1,212 @@
+import { CaptureError, type PostHog, type PostHogOptions } from '@/entrypoints/index.node'
+
+import { ANALYTICS_CAPTURE_PATH, v1Response } from '../utils'
+import { V1WiringHarness } from '../utils/v1-wiring'
+
+vi.mock('../../version', () => ({ version: '1.2.3' }))
+
+const SERVER_TEXT = 'internal server detail 0198c0de-1234-7abc-8def-0123456789ab'
+const UUID = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i
+const SECRET_PROPERTY = 'secret-property-value'
+
+const response = (status: number, body: string, headers: Record<string, string> = {}): any => ({
+  status,
+  text: () => Promise.resolve(body),
+  headers: { get: (name: string) => headers[name] ?? null },
+  body: null,
+})
+
+describe('capture loss summary', () => {
+  const harness = new V1WiringHarness()
+  let warn: vi.SpyInstance
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    harness.useDefaultRouting()
+  })
+
+  afterEach(async () => {
+    harness.useDefaultRouting()
+    await harness.cleanup()
+    vi.clearAllMocks()
+  })
+
+  const lines = (): string[] => warn.mock.calls.map(([line]) => String(line))
+
+  /** Answers capture requests in order with `responses`, then accepts everything. */
+  function answerCapture(...responses: (() => Promise<any>)[]): void {
+    harness.fetch.mockImplementation((url: any) => {
+      if (!String(url).includes(ANALYTICS_CAPTURE_PATH)) {
+        return Promise.resolve(v1Response())
+      }
+      const next = responses.shift()
+      return next ? next() : Promise.resolve(v1Response())
+    })
+  }
+
+  async function captureTwo(posthog: PostHog, immediate = false): Promise<string[]> {
+    const uuids = ['0198c0de-0000-7000-8000-000000000001', '0198c0de-0000-7000-8000-000000000002']
+    for (const uuid of uuids) {
+      const event = { distinctId: 'u', event: 'signup', properties: { secret: SECRET_PROPERTY }, uuid }
+      if (immediate) {
+        await posthog.captureImmediate(event)
+      } else {
+        posthog.capture(event)
+      }
+    }
+    if (!immediate) {
+      const flush = posthog.flush()
+      await vi.advanceTimersByTimeAsync(60_000)
+      await flush
+    }
+    return uuids
+  }
+
+  function expectContentFree(line: string): void {
+    expect(line).not.toMatch(UUID)
+    expect(line).not.toContain(SERVER_TEXT)
+    expect(line).not.toContain('billing')
+    expect(line).not.toContain(SECRET_PROPERTY)
+    expect(line).not.toContain('signup')
+  }
+
+  it.each<[string, (() => Promise<any>)[], string, PostHogOptions?]>([
+    [
+      'a final HTTP error',
+      [() => Promise.resolve(response(400, SERVER_TEXT))],
+      '2 event(s) were not delivered to /i/v1/analytics/events: 2 failed with HTTP 400',
+    ],
+    [
+      'exhausted retries',
+      [() => Promise.resolve(response(503, SERVER_TEXT)), () => Promise.resolve(response(503, SERVER_TEXT))],
+      '2 event(s) were not delivered to /i/v1/analytics/events: 2 failed with HTTP 503',
+      { captureMaxRetries: 1 },
+    ],
+    [
+      'server drops and duplicates',
+      [
+        () =>
+          Promise.resolve(
+            response(
+              200,
+              JSON.stringify({
+                results: {
+                  '0198c0de-0000-7000-8000-000000000001': { result: 'drop', details: `billing ${SERVER_TEXT}` },
+                  '0198c0de-0000-7000-8000-000000000002': { result: 'retry' },
+                },
+              })
+            )
+          ),
+        () =>
+          Promise.resolve(
+            response(200, JSON.stringify({ results: { '0198c0de-0000-7000-8000-000000000002': { result: 'retry' } } }))
+          ),
+      ],
+      '2 event(s) were not delivered to /i/v1/analytics/events: 1 dropped by the server (HTTP 200), ' +
+        '1 still marked for retry after 2 attempt(s) (HTTP 200)',
+      { captureMaxRetries: 1 },
+    ],
+    [
+      'an unfollowed redirect',
+      [() => Promise.resolve(response(302, SERVER_TEXT, { Location: '/elsewhere' }))],
+      '2 event(s) were not delivered to /i/v1/analytics/events: 2 failed on a redirect it does not follow (HTTP 302)',
+    ],
+    [
+      'an unreadable 2xx',
+      [() => Promise.resolve(response(200, SERVER_TEXT))],
+      '2 event(s) were not delivered to /i/v1/analytics/events: 2 failed with an unreadable response (HTTP 200)',
+    ],
+  ])('logs one content-free line for %s when nothing listens', async (_label, responses, expected, options) => {
+    answerCapture(...responses)
+    const posthog = harness.makeClient(options)
+
+    await captureTwo(posthog)
+
+    expect(lines()).toEqual([`[PostHog] ${expected}`])
+    expectContentFree(lines()[0])
+  })
+
+  it('names duplicate drops', async () => {
+    answerCapture(() =>
+      Promise.resolve(
+        response(
+          200,
+          JSON.stringify({
+            results: { '0198c0de-0000-7000-8000-000000000001': { result: 'ok', duplicates_dropped: 1 } },
+          })
+        )
+      )
+    )
+    const posthog = harness.makeClient()
+    const uuid = '0198c0de-0000-7000-8000-000000000001'
+    posthog.capture({ distinctId: 'u', event: 'signup', properties: {}, uuid })
+    posthog.capture({ distinctId: 'u', event: 'signup', properties: {}, uuid })
+    await posthog.flush()
+
+    expect(lines()).toEqual([
+      '[PostHog] 1 event(s) were not delivered to /i/v1/analytics/events: 1 dropped as duplicate uuids (HTTP 200)',
+    ])
+  })
+
+  it.each<[string, () => Promise<any>, string, PostHogOptions]>([
+    [
+      'a network error',
+      () => Promise.reject(new TypeError(`fetch failed: ${SERVER_TEXT}`)),
+      '1 failed with a network error (TypeError)',
+      {},
+    ],
+    ['a timeout', () => new Promise(() => {}), '1 failed: request timed out', { requestTimeout: 1000 }],
+  ])('logs one line per immediate send lost to %s', async (_label, answer, expected, options) => {
+    answerCapture(answer, answer)
+    const posthog = harness.makeClient(options)
+
+    const sends = captureTwo(posthog, true)
+    await vi.advanceTimersByTimeAsync(5000)
+    await sends
+
+    expect(lines()).toEqual([
+      `[PostHog] 1 event(s) were not delivered to /i/v1/analytics/events: ${expected}`,
+      `[PostHog] 1 event(s) were not delivered to /i/v1/analytics/events: ${expected}`,
+    ])
+    lines().forEach(expectContentFree)
+  })
+
+  it('logs nothing when a network failure keeps the events for the next flush', async () => {
+    answerCapture(() => Promise.reject(new TypeError('fetch failed')))
+    const posthog = harness.makeClient()
+
+    await captureTwo(posthog)
+
+    expect(lines()).toEqual([])
+  })
+
+  it('logs one line per batch', async () => {
+    answerCapture(
+      () => Promise.resolve(response(400, SERVER_TEXT)),
+      () => Promise.resolve(response(413, SERVER_TEXT))
+    )
+    const posthog = harness.makeClient({ maxBatchSize: 1, flushAt: 1 })
+
+    await captureTwo(posthog)
+
+    expect(lines()).toEqual([
+      '[PostHog] 1 event(s) were not delivered to /i/v1/analytics/events: 1 failed with HTTP 400',
+      '[PostHog] 1 event(s) were not delivered to /i/v1/analytics/events: 1 failed with HTTP 413',
+    ])
+  })
+
+  it("logs nothing and hands the CaptureError to an 'error' listener", async () => {
+    answerCapture(() => Promise.resolve(response(400, SERVER_TEXT)))
+    const posthog = harness.makeClient()
+    const errors: unknown[] = []
+    posthog.on('error', (error) => errors.push(error))
+
+    const uuids = await captureTwo(posthog)
+
+    expect(lines()).toEqual([])
+    expect(errors).toHaveLength(1)
+    expect(errors[0]).toBeInstanceOf(CaptureError)
+    expect((errors[0] as CaptureError).retryExhausted).toEqual(uuids)
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/redirect-undici.spec.ts b/packages/node/src/__tests__/capture-v1/redirect-undici.spec.ts
new file mode 100644
index 0000000000..fadd1da6f7
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/redirect-undici.spec.ts
@@ -0,0 +1,76 @@
+/** @vitest-environment node */
+
+import { type AddressInfo } from 'node:net'
+import { createServer, type Server } from 'node:http'
+import { gunzipSync } from 'node:zlib'
+
+import { V1CaptureSender } from '@/capture-v1/sender'
+import { serializeV1Event } from '@/capture-v1/serialize'
+import { zlibCompressor } from '@/compression.node'
+
+// Node's fetch throws when it replays a byte body on a redirect it follows itself, so this runs against a real server.
+describe('capture redirects through Node fetch', () => {
+  let server: Server
+  let host: string
+  const received: { url: string; encoding?: string; body: Buffer }[] = []
+
+  beforeAll(async () => {
+    vi.useRealTimers()
+    server = createServer((request, response) => {
+      const chunks: Buffer[] = []
+      request.on('data', (chunk: Buffer) => chunks.push(chunk))
+      request.on('end', () => {
+        received.push({
+          url: request.url!,
+          encoding: request.headers['content-encoding'] as string | undefined,
+          body: Buffer.concat(chunks),
+        })
+        if (request.url === '/i/v1/analytics/events') {
+          response.writeHead(307, { Location: '/moved/i/v1/analytics/events' }).end()
+        } else {
+          response.writeHead(200, { 'Content-Type': 'application/json' }).end('{"results":{}}')
+        }
+      })
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    host = `http://127.0.0.1:${(server.address() as AddressInfo).port}`
+  })
+
+  afterAll(async () => {
+    await new Promise((resolve) => server.close(resolve))
+    vi.useFakeTimers()
+  })
+
+  it('resends a compressed body to a same-origin 307 target', async () => {
+    const errors: Error[] = []
+    const sender = new V1CaptureSender(
+      {
+        host,
+        path: '/i/v1/analytics/events',
+        apiKey: 'phc_test',
+        libraryId: 'posthog-node',
+        libraryVersion: '1.2.3',
+        historicalMigration: false,
+        compression: 'gzip',
+        requestTimeoutMs: 5000,
+        maxRetries: 0,
+      },
+      {
+        fetch: (url, options) => fetch(url, options as RequestInit),
+        onError: (error) => errors.push(error),
+        compress: (payload, codec) => zlibCompressor.compress(payload, codec),
+      }
+    )
+
+    await sender.send([serializeV1Event({ event: 'e', distinct_id: 'u', uuid: 'u1', properties: {} })])
+
+    expect(errors).toEqual([])
+    expect(received.map(({ url, encoding }) => [url, encoding])).toEqual([
+      ['/i/v1/analytics/events', 'gzip'],
+      ['/moved/i/v1/analytics/events', 'gzip'],
+    ])
+    for (const { body } of received) {
+      expect(JSON.parse(gunzipSync(body).toString()).batch[0].uuid).toBe('u1')
+    }
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/sender.spec.ts b/packages/node/src/__tests__/capture-v1/sender.spec.ts
index 6a503a1f26..6c0bfd7e1c 100644
--- a/packages/node/src/__tests__/capture-v1/sender.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/sender.spec.ts
@@ -278,6 +278,104 @@ describe('V1CaptureSender', () => {
     })
   })
 
+  describe('redirects', () => {
+    const redirect = (status: number, location?: string): PostHogFetchResponse =>
+      makeResponse(status, 'moved', location === undefined ? {} : { Location: location })
+
+    it.each<[number, string, string]>([
+      [307, '/i/v1/analytics/events?moved=1', 'https://t.posthog.com/i/v1/analytics/events?moved=1'],
+      [308, 'https://t.posthog.com:443/elsewhere', 'https://t.posthog.com/elsewhere'],
+    ])('follows a same-origin %s with the same method, headers and body', async (status, location, resolved) => {
+      const compressed = new Uint8Array([7, 8, 9])
+      const { sender, fetch, errors } = makeSender(
+        { compression: 'gzip' },
+        { compress: () => Promise.resolve(compressed) }
+      )
+      fetch.mockResolvedValueOnce(redirect(status, location)).mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(fetch.mock.calls.map(([url]) => url)).toEqual(['https://t.posthog.com/i/v1/analytics/events', resolved])
+      const [first, second] = fetch.mock.calls.map(([, options]) => options)
+      expect(second.method).toBe('POST')
+      expect(second.headers).toEqual(first.headers)
+      expect(second.headers['PostHog-Attempt']).toBe('1')
+      expect(second.body).toEqual(compressed)
+      expect(second.body).not.toBe(first.body)
+      expect([first.redirect, second.redirect]).toEqual(['manual', 'manual'])
+      expect(errors).toEqual([])
+    })
+
+    it('follows up to 5 redirects and reports the 6th as a final failure', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValue(redirect(307, '/i/v1/analytics/events'))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(fetch).toHaveBeenCalledTimes(6)
+      expect(errors).toHaveLength(1)
+      expect((errors[0] as CaptureError).retryExhausted).toEqual(['u1'])
+      expect(((errors[0] as CaptureError).cause as Error).message).toBe(
+        'Capture V1 request was redirected more than 5 times'
+      )
+    })
+
+    it('reaches a final response on the 5th redirect', async () => {
+      const { sender, fetch, errors } = makeSender()
+      for (let i = 0; i < 5; i++) {
+        fetch.mockResolvedValueOnce(redirect(308, `/hop-${i}`))
+      }
+      fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(fetch).toHaveBeenCalledTimes(6)
+      expect(errors).toEqual([])
+    })
+
+    it.each<[string, PostHogFetchResponse, string]>([
+      [
+        'another host',
+        redirect(307, 'https://evil.example.com/i/v1/analytics/events'),
+        'away from the configured host',
+      ],
+      ['another scheme', redirect(307, 'http://t.posthog.com/i/v1/analytics/events'), 'away from the configured host'],
+      [
+        'another port',
+        redirect(308, 'https://t.posthog.com:8443/i/v1/analytics/events'),
+        'away from the configured host',
+      ],
+      ['no Location', redirect(307), 'away from the configured host'],
+      ['a 301', redirect(301, '/i/v1/analytics/events'), 'HTTP 301 redirect, which it does not follow'],
+      ['a 302', redirect(302, '/i/v1/analytics/events'), 'HTTP 302 redirect, which it does not follow'],
+      ['a 303', redirect(303, '/i/v1/analytics/events'), 'HTTP 303 redirect, which it does not follow'],
+    ])('reports a redirect to %s as a final failure without retrying', async (_label, response, reason) => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValue(response)
+
+      const unsent = await sender.send(v1Events([msg('u1')]), { keepUnsent: true })
+
+      expect(unsent).toEqual([])
+      expect(fetch).toHaveBeenCalledTimes(1)
+      expect(errors).toHaveLength(1)
+      const error = errors[0] as CaptureError
+      expect(error).toBeInstanceOf(CaptureError)
+      expect(error.retryExhausted).toEqual(['u1'])
+      expect((error.cause as Error).message).toContain(reason)
+      expect((error.cause as Error).message).not.toContain('moved')
+    })
+
+    it('treats the final response of a fetch that follows redirects itself normally', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValueOnce(makeResponse(200, { results: { u1: { result: 'drop', details: 'billing' } } }))
+
+      await sender.send(v1Events([msg('u1')]))
+
+      expect(fetch).toHaveBeenCalledTimes(1)
+      expect((errors[0] as CaptureError).drops).toEqual([{ uuid: 'u1', details: 'billing' }])
+    })
+  })
+
   describe('2xx per-event classification', () => {
     it.each([
       ['ok', { result: 'ok' }],
@@ -293,6 +391,23 @@ describe('V1CaptureSender', () => {
       expect(errors).toEqual([])
     })
 
+    it.each<[string, (uuid: string) => string]>([
+      ['uppercase', (uuid) => uuid.toUpperCase()],
+      ['braced', (uuid) => `{${uuid}}`],
+      ['urn', (uuid) => `urn:uuid:${uuid}`],
+      ['32-hex', (uuid) => uuid.replace(/-/g, '')],
+    ])('matches a result keyed by the %s form of the event uuid', async (_label, form) => {
+      const uuid = '0198c0de-1234-7abc-8def-0123456789ab'
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValueOnce(
+        makeResponse(200, { results: { [form(uuid)]: { result: 'drop', details: 'billing' } } })
+      )
+
+      await sender.send(v1Events([msg(uuid)]))
+
+      expect((errors[0] as CaptureError).drops).toEqual([{ uuid, details: 'billing' }])
+    })
+
     it('treats an absent uuid as accepted', async () => {
       const { sender, fetch, errors } = makeSender()
       fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
@@ -384,6 +499,106 @@ describe('V1CaptureSender', () => {
     })
   })
 
+  describe('duplicates_dropped', () => {
+    const DUP = { uuid: 'a', details: 'duplicate_event_uuid' }
+    const uuidsIn = (fetch: Harness['fetch'], call: number): string[] =>
+      bodyOf(fetch, call).batch.map((e: any) => e.uuid)
+
+    it('reports the next n copies as duplicate drops when the kept copy is ok', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValueOnce(makeResponse(200, { results: { a: { result: 'ok', duplicates_dropped: 2 } } }))
+
+      await sender.send(v1Events([msg('a'), msg('a'), msg('a')]))
+
+      expect(fetch).toHaveBeenCalledTimes(1)
+      expect(errors).toHaveLength(1)
+      expect(errors[0]).toMatchObject({ drops: [DUP, DUP], retryExhausted: [] })
+    })
+
+    it('keeps the drop details on the kept copy', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValueOnce(
+        makeResponse(200, { results: { a: { result: 'drop', details: 'billing', duplicates_dropped: 1 } } })
+      )
+
+      await sender.send(v1Events([msg('a'), msg('a')]))
+
+      expect((errors[0] as CaptureError).drops).toEqual([{ uuid: 'a', details: 'billing' }, DUP])
+    })
+
+    it('resends only the kept copy when its result is retry', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch
+        .mockResolvedValueOnce(makeResponse(200, { results: { a: { result: 'retry', duplicates_dropped: 1 } } }))
+        .mockResolvedValueOnce(makeResponse(200, { results: { a: { result: 'ok' } } }))
+
+      await sender.send(v1Events([msg('a'), msg('a')]))
+
+      expect(uuidsIn(fetch, 1)).toEqual(['a'])
+      expect(errors[0]).toMatchObject({ drops: [DUP], retryExhausted: [] })
+    })
+
+    it('counts copies per uuid when uuids interleave', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValueOnce(
+        makeResponse(200, {
+          results: { a: { result: 'ok', duplicates_dropped: 2 }, b: { result: 'retry', duplicates_dropped: 1 } },
+        })
+      )
+      fetch.mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+      await sender.send(v1Events([msg('a'), msg('b'), msg('a'), msg('b'), msg('a')]))
+
+      expect(uuidsIn(fetch, 1)).toEqual(['b'])
+      expect((errors[0] as CaptureError).drops).toEqual([DUP, { ...DUP, uuid: 'b' }, DUP])
+    })
+
+    it('gives copies past n the kept verdict', async () => {
+      const { sender, fetch, errors } = makeSender()
+      fetch
+        .mockResolvedValueOnce(
+          makeResponse(200, {
+            results: {
+              a: { result: 'retry', duplicates_dropped: 1 },
+              b: { result: 'drop', details: 'billing', duplicates_dropped: 1 },
+            },
+          })
+        )
+        .mockResolvedValueOnce(makeResponse(200, { results: {} }))
+
+      await sender.send(v1Events([msg('a'), msg('a'), msg('a'), msg('b'), msg('b'), msg('b')]))
+
+      expect(uuidsIn(fetch, 1)).toEqual(['a', 'a'])
+      expect((errors[0] as CaptureError).drops).toEqual([
+        DUP,
+        { uuid: 'b', details: 'billing' },
+        { ...DUP, uuid: 'b' },
+        { uuid: 'b', details: 'billing' },
+      ])
+    })
+
+    it.each<[string, unknown]>([
+      ['zero', 0],
+      ['negative', -1],
+      ['fractional', 1.5],
+      ['a string', '1'],
+      ['null', null],
+      ['absent', undefined],
+    ])('ignores a %s duplicates_dropped and gives every copy the result', async (_label, duplicates) => {
+      const { sender, fetch, errors } = makeSender()
+      fetch.mockResolvedValueOnce(
+        makeResponse(200, { results: { a: { result: 'drop', details: 'billing', duplicates_dropped: duplicates } } })
+      )
+
+      await sender.send(v1Events([msg('a'), msg('a')]))
+
+      expect((errors[0] as CaptureError).drops).toEqual([
+        { uuid: 'a', details: 'billing' },
+        { uuid: 'a', details: 'billing' },
+      ])
+    })
+  })
+
   describe('2xx malformed body', () => {
     it('treats an unparseable 2xx body as terminal failure without retrying', async () => {
       const { sender, fetch, errors } = makeSender()
diff --git a/packages/node/src/__tests__/capture-v1/uuid.spec.ts b/packages/node/src/__tests__/capture-v1/uuid.spec.ts
new file mode 100644
index 0000000000..4cded9a07b
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/uuid.spec.ts
@@ -0,0 +1,153 @@
+import { canonicalizeUuid } from '@/capture-v1/uuid'
+import type { PostHogOptions } from '@/entrypoints/index.node'
+
+import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, captureEvents } from '../utils'
+import { V1WiringHarness } from '../utils/v1-wiring'
+
+vi.mock('../../version', () => ({ version: '1.2.3' }))
+
+const CANONICAL = '0198c0de-1234-7abc-8def-0123456789ab'
+const WARNING = '[PostHog] Replaced an invalid event uuid with a generated one; uuids must be RFC 4122 strings'
+const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+const ACCEPTED: [string, string][] = [
+  ['hyphenated', CANONICAL],
+  ['uppercase', CANONICAL.toUpperCase()],
+  ['braced', `{${CANONICAL}}`],
+  ['braced uppercase', `{${CANONICAL.toUpperCase()}}`],
+  ['urn', `urn:uuid:${CANONICAL}`],
+  ['uppercase urn', `URN:UUID:${CANONICAL.toUpperCase()}`],
+  ['32 hex digits', CANONICAL.replace(/-/g, '')],
+]
+
+const REJECTED: [string, string][] = [
+  ['bracketed', `[${CANONICAL}]`],
+  ['parenthesized', `(${CANONICAL})`],
+  ['misplaced hyphens', '0198c0de1-234-7abc-8def-0123456789ab'],
+  ['hyphens in the 32-hex form', '0198c0de-12347abc8def0123456789ab'],
+  ['a braced 32-hex form', `{${CANONICAL.replace(/-/g, '')}}`],
+  ['a urn 32-hex form', `urn:uuid:${CANONICAL.replace(/-/g, '')}`],
+  ['an unclosed brace', `{${CANONICAL}`],
+  ['surrounding whitespace', ` ${CANONICAL}`],
+  ['a non-hex digit', CANONICAL.replace('a', 'g')],
+  ['31 hex digits', CANONICAL.replace(/-/g, '').slice(1)],
+  ['free text', 'my-event-id'],
+]
+
+describe('canonicalizeUuid', () => {
+  it.each(ACCEPTED)('accepts the %s form as lowercase hyphenated', (_label, value) => {
+    expect(canonicalizeUuid(value)).toBe(CANONICAL)
+  })
+
+  it.each(REJECTED)('rejects %s', (_label, value) => {
+    expect(canonicalizeUuid(value)).toBeUndefined()
+  })
+})
+
+describe('event uuids on the client', () => {
+  const harness = new V1WiringHarness()
+  let warn: vi.SpyInstance
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    harness.useDefaultRouting()
+  })
+
+  afterEach(async () => {
+    await harness.cleanup()
+    vi.clearAllMocks()
+  })
+
+  const uuidWarnings = (): unknown[][] => warn.mock.calls.filter(([message]) => String(message).includes('uuid'))
+
+  async function wireUuid(uuid: string | undefined, options: PostHogOptions = {}): Promise<string> {
+    const posthog = harness.makeClient(options)
+    posthog.capture({ distinctId: 'u', event: 'e', properties: {}, uuid })
+    await posthog.flush()
+    const events = captureEvents(harness.fetch, ANALYTICS_CAPTURE_PATH)
+    expect(events).toHaveLength(1)
+    return events[0].uuid
+  }
+
+  it.each(ACCEPTED)('sends a %s uuid in canonical form without a warning', async (_label, value) => {
+    expect(await wireUuid(value)).toBe(CANONICAL)
+    expect(uuidWarnings()).toEqual([])
+  })
+
+  it.each(REJECTED)('replaces a uuid with %s, with one warning that does not repeat it', async (_label, value) => {
+    const sent = await wireUuid(value)
+
+    expect(sent).toMatch(UUID_V7)
+    expect(uuidWarnings()).toEqual([[WARNING]])
+    expect(WARNING).not.toContain(value)
+  })
+
+  it.each<[string, string | undefined]>([
+    ['empty', ''],
+    ['missing', undefined],
+  ])('generates a uuid for a %s one without a warning', async (_label, value) => {
+    expect(await wireUuid(value)).toMatch(UUID_V7)
+    expect(uuidWarnings()).toEqual([])
+  })
+
+  it('shows before_send the canonical uuid', async () => {
+    const seen: (string | undefined)[] = []
+    await wireUuid(`{${CANONICAL.toUpperCase()}}`, {
+      before_send: (event) => {
+        seen.push(event?.uuid)
+        return event
+      },
+    })
+
+    expect(seen).toEqual([CANONICAL])
+  })
+
+  it.each<[string, string, string | RegExp, unknown[][]]>([
+    ['canonicalizes', `urn:uuid:${CANONICAL.toUpperCase()}`, CANONICAL, []],
+    ['replaces, with one warning,', 'not-a-uuid', UUID_V7, [[WARNING]]],
+  ])('%s a uuid that before_send sets', async (_label, hookUuid, expected, warnings) => {
+    const sent = await wireUuid(undefined, { before_send: (event) => event && { ...event, uuid: hookUuid } })
+
+    expect(sent).toMatch(expected)
+    expect(uuidWarnings()).toEqual(warnings)
+  })
+
+  it('warns once when the caller and before_send set different invalid uuids', async () => {
+    const sent = await wireUuid('bad-uuid', { before_send: (event) => event && { ...event, uuid: 'other-bad-uuid' } })
+
+    expect(sent).toMatch(UUID_V7)
+    expect(uuidWarnings()).toEqual([[WARNING]])
+  })
+
+  it('warns once when the caller and before_send both keep an invalid uuid', async () => {
+    const sent = await wireUuid('bad-uuid', { before_send: (event) => event })
+
+    expect(sent).toMatch(UUID_V7)
+    expect(uuidWarnings()).toEqual([[WARNING]])
+  })
+
+  it.each<[string, string, string | RegExp, unknown[][]]>([
+    ['a canonical form of', `{${CANONICAL.toUpperCase()}}`, CANONICAL, []],
+    ['a generated replacement for', `[${CANONICAL}]`, UUID_V7, [[WARNING]]],
+  ])('captureAi returns and sends %s the caller uuid', async (_label, value, expected, warnings) => {
+    const posthog = harness.makeClient()
+
+    const returned = posthog.captureAi({ distinctId: 'u', event: '$ai_generation', properties: {}, uuid: value })
+    await posthog.flush()
+
+    expect(returned).toMatch(expected)
+    expect(captureEvents(harness.fetch, AI_CAPTURE_PATH).map((event) => event.uuid)).toEqual([returned])
+    expect(uuidWarnings()).toEqual(warnings)
+  })
+
+  it('warns once per bad call', async () => {
+    const posthog = harness.makeClient()
+
+    posthog.capture({ distinctId: 'u', event: 'a', properties: {}, uuid: 'bad-1' })
+    posthog.capture({ distinctId: 'u', event: 'b', properties: {}, uuid: 'bad-2' })
+    await posthog.flush()
+
+    expect(uuidWarnings()).toEqual([[WARNING], [WARNING]])
+  })
+})
diff --git a/packages/node/src/capture-lane/lane.ts b/packages/node/src/capture-lane/lane.ts
index adbf1be816..30bd4ea5a1 100644
--- a/packages/node/src/capture-lane/lane.ts
+++ b/packages/node/src/capture-lane/lane.ts
@@ -1,6 +1,6 @@
 import { type Logger, type PostHogEventProperties, safeSetTimeout } from '@posthog/core'
 
-import { CaptureError, type CaptureDroppedEvent } from '../capture-v1/errors'
+import { CaptureError, CaptureLossTally, type CaptureDroppedEvent, describeCaptureLoss } from '../capture-v1/errors'
 import type { V1SendOptions } from '../capture-v1/sender'
 import { type SerializedV1Event, serializeV1Event } from '../capture-v1/serialize'
 import type { CaptureEndpoint } from '../capture-v1/types'
@@ -32,8 +32,11 @@ export interface CaptureLaneConfig {
 
 export interface CaptureLaneHooks {
   sender: CaptureLaneSender
-  /** Events this lane dropped without sending, at most one report per flush cycle. */
-  onLocalDrops: (error: CaptureError) => void
+  /**
+   * Events this lane dropped without sending, at most one report per flush cycle. `summary` is
+   * one line with counts and causes only, for when nothing listens.
+   */
+  onLocalDrops: (errors: CaptureError[], summary: string) => void
   /** Failures the sender did not handle itself. */
   onError: (error: unknown) => void
   /** The messages one flush cycle sent. */
@@ -160,18 +163,7 @@ export class CaptureLane {
     clearTimeout(this.abortTimer)
     this.abortTimer = undefined
     this.clearFlushTimer()
-    const leftovers = this.queue.splice(0)
-    if (leftovers.length > 0) {
-      const error = new CaptureError({
-        endpoint: this.config.endpoint,
-        requestId: '',
-        drops: [],
-        retryExhausted: leftovers.map((event) => event.uuid),
-      })
-      error.message = `${leftovers.length} event(s) for ${this.config.endpoint} were still queued when shutdown ended and were not sent`
-      this.safely(() => this.hooks.onLocalDrops(error))
-    }
-    this.reportLocalDrops()
+    this.reportLocalDrops(this.queue.splice(0))
     if (this.abortController.signal.aborted) {
       this.abortController = new AbortController()
     }
@@ -283,33 +275,49 @@ export class CaptureLane {
     }
   }
 
-  private reportLocalDrops(): void {
+  private reportLocalDrops(leftovers: SerializedV1Event[] = []): void {
     const tally = this.localDrops
     this.localDrops = emptyTally()
-    this.reportTally(tally)
+    this.reportTally(tally, leftovers)
   }
 
-  private reportTally(tally: LocalDropTally): void {
-    const total = tally.queueFull + tally.tooLarge
-    if (total === 0) {
-      return
+  /** Reports `tally` and the events still queued at the end of a shutdown together, in one report. */
+  private reportTally(tally: LocalDropTally, leftovers: SerializedV1Event[] = []): void {
+    const errors: CaptureError[] = []
+    const loss = new CaptureLossTally()
+    const { endpoint } = this.config
+    if (leftovers.length > 0) {
+      const error = new CaptureError({
+        endpoint,
+        requestId: '',
+        drops: [],
+        retryExhausted: leftovers.map((event) => event.uuid),
+      })
+      error.message = `${leftovers.length} event(s) for ${endpoint} were still queued when shutdown ended and were not sent`
+      errors.push(error)
+      loss.add('still queued when shutdown ended', leftovers.length)
     }
-    const reasons: string[] = []
-    if (tally.queueFull > 0) {
-      reasons.push(`${tally.queueFull} because the queue was full (${this.config.maxQueueSize} events)`)
+    const total = tally.queueFull + tally.tooLarge
+    if (total > 0) {
+      const { maxQueueSize, maxEventBytes, maxEventBytesOf } = this.config
+      const reasons: string[] = []
+      if (tally.queueFull > 0) {
+        reasons.push(`${tally.queueFull} because the queue was full (${maxQueueSize} events)`)
+      }
+      if (tally.tooLarge > 0) {
+        const measured = maxEventBytesOf === 'properties' ? 'properties larger' : 'larger'
+        reasons.push(`${tally.tooLarge} with ${measured} than ${maxEventBytes} bytes`)
+      }
+      const error = new CaptureError({ endpoint, requestId: '', drops: tally.sample, retryExhausted: [] })
+      error.message = `Dropped ${total} event(s) for ${endpoint} before sending: ${reasons.join(', ')}`
+      errors.push(error)
+      loss.add(`dropped because the queue was full (${maxQueueSize} events)`, tally.queueFull)
+      const measured = maxEventBytesOf === 'properties' ? 'their properties were' : 'they were'
+      loss.add(`dropped because ${measured} larger than ${maxEventBytes} bytes`, tally.tooLarge)
     }
-    if (tally.tooLarge > 0) {
-      const measured = this.config.maxEventBytesOf === 'properties' ? 'properties larger' : 'larger'
-      reasons.push(`${tally.tooLarge} with ${measured} than ${this.config.maxEventBytes} bytes`)
+    if (errors.length > 0) {
+      this.safely(() => this.hooks.onLocalDrops(errors, describeCaptureLoss(endpoint, loss)))
     }
-    const error = new CaptureError({
-      endpoint: this.config.endpoint,
-      requestId: '',
-      drops: tally.sample,
-      retryExhausted: [],
-    })
-    error.message = `Dropped ${total} event(s) for ${this.config.endpoint} before sending: ${reasons.join(', ')}`
-    this.safely(() => this.hooks.onLocalDrops(error))
   }
 
   private armFlushTimer(): void {
diff --git a/packages/node/src/capture-v1/errors.ts b/packages/node/src/capture-v1/errors.ts
index 9568128450..6e5085d1fd 100644
--- a/packages/node/src/capture-v1/errors.ts
+++ b/packages/node/src/capture-v1/errors.ts
@@ -57,3 +57,35 @@ export class CaptureError extends Error {
     return message
   }
 }
+
+/** Counts of undelivered events by cause, in the order the causes first occurred. */
+export class CaptureLossTally {
+  private readonly counts = new Map<string, number>()
+
+  add(cause: string, count: number): void {
+    if (count > 0) {
+      this.counts.set(cause, (this.counts.get(cause) ?? 0) + count)
+    }
+  }
+
+  get total(): number {
+    let total = 0
+    for (const count of this.counts.values()) {
+      total += count
+    }
+    return total
+  }
+
+  entries(): [cause: string, count: number][] {
+    return [...this.counts]
+  }
+}
+
+/**
+ * The one line logged for a capture loss when nothing listens for `'error'`. It holds the lane,
+ * counts and causes only: never server response text, event content or uuids.
+ */
+export function describeCaptureLoss(endpoint: CaptureEndpoint, loss: CaptureLossTally): string {
+  const causes = loss.entries().map(([cause, count]) => `${count} ${cause}`)
+  return `${loss.total} event(s) were not delivered to ${endpoint}: ${causes.join(', ')}`
+}
diff --git a/packages/node/src/capture-v1/sender.ts b/packages/node/src/capture-v1/sender.ts
index 6b95edc2ef..20ad7c4489 100644
--- a/packages/node/src/capture-v1/sender.ts
+++ b/packages/node/src/capture-v1/sender.ts
@@ -1,9 +1,16 @@
 import { type FetchLike, type PostHogFetchOptions, type PostHogFetchResponse, uuidv7 } from '@posthog/core'
 
 import { type CaptureCodec, type CaptureCompression, webCompressor } from './compression'
-import { CaptureError, type CaptureDroppedEvent, type CaptureErrorParams } from './errors'
+import {
+  CaptureError,
+  CaptureLossTally,
+  type CaptureDroppedEvent,
+  type CaptureErrorParams,
+  describeCaptureLoss,
+} from './errors'
 import { type SerializedV1Event, buildV1Body } from './serialize'
-import type { CaptureEndpoint, V1BatchResponse } from './types'
+import type { CaptureEndpoint, V1BatchResponse, V1EventResult } from './types'
+import { canonicalizeUuid } from './uuid'
 
 /** Wait before the first retry; each later retry doubles it. */
 export const RETRY_BASE_DELAY_MS = 100
@@ -56,6 +63,16 @@ function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
 /** HTTP statuses a capture request is retried on. 404 and 429 can come from a proxy in front of capture. */
 const RETRYABLE_STATUSES = new Set([404, 408, 429, 500, 502, 503, 504])
 
+/** Only these redirects keep the method and body, so they are the only ones a capture request follows. */
+const FOLLOWED_REDIRECT_STATUSES = new Set([307, 308])
+const MAX_REDIRECTS = 5
+
+/** Errors the sender raised for its own request deadline, so a loss summary can call them timeouts. */
+const timeoutErrors = new WeakSet<Error>()
+
+/** Drop details for a copy of an event the server dropped as a duplicate of an earlier one in the request. */
+export const DUPLICATE_EVENT_UUID = 'duplicate_event_uuid'
+
 export interface V1CaptureSenderConfig {
   host: string
   /** The capture lane this sender posts to. */
@@ -77,8 +94,11 @@ export interface V1CaptureSenderConfig {
 
 export interface V1CaptureSenderHooks {
   fetch: FetchLike
-  /** Surfaces partial/terminal delivery failures on the client error channel. */
-  onError: (error: Error) => void
+  /**
+   * Surfaces partial/terminal delivery failures on the client error channel, at most once per
+   * batch. `summary` is one line with counts and causes only, for when nothing listens.
+   */
+  onError: (error: CaptureError, summary: string) => void
   now?: () => number
   /** Waits between attempts. The sender stops waiting when `signal` aborts, even if this does not. */
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>
@@ -99,8 +119,13 @@ export interface V1SendOptions {
   keepUnsent?: boolean
 }
 
-interface V1CaptureAttempt {
+interface RedirectOutcome {
   response: PostHogFetchResponse
+  /** Set when `response` is a redirect the sender does not follow. */
+  redirectFailure?: string
+}
+
+interface V1CaptureAttempt extends RedirectOutcome {
   signal: AbortSignal
   waitFor<T>(operation: Promise<T>): Promise<T>
   cancelBody: () => Promise<void>
@@ -120,8 +145,9 @@ interface V1CaptureAttempt {
  */
 export class V1CaptureSender {
   private readonly config: V1CaptureSenderConfig
+  private readonly hostOrigin: string | undefined
   private readonly fetchFn: FetchLike
-  private readonly onError: (error: Error) => void
+  private readonly onError: (error: CaptureError, summary: string) => void
   private readonly now: () => number
   private readonly sleep: (ms: number, signal?: AbortSignal) => Promise<void>
   private readonly generateRequestId: () => string
@@ -130,6 +156,7 @@ export class V1CaptureSender {
 
   constructor(config: V1CaptureSenderConfig, hooks: V1CaptureSenderHooks) {
     this.config = config
+    this.hostOrigin = originOf(config.host)
     this.fetchFn = hooks.fetch
     this.onError = hooks.onError
     this.now = hooks.now ?? Date.now
@@ -151,14 +178,15 @@ export class V1CaptureSender {
     const createdAt = new Date(this.now()).toISOString()
     const url = `${this.config.host}${this.config.path}`
     const drops: CaptureDroppedEvent[] = []
+    const loss = new CaptureLossTally()
     let pending = events
 
-    const unsent = (cause: unknown): T[] => {
+    const unsent = (cause: unknown, failure: string): T[] => {
       if (keepUnsent) {
-        this.surfacePartialDrops(requestId, drops)
+        this.surfacePartialDrops(requestId, drops, loss)
         return pending
       }
-      this.surfaceBatchFailure(requestId, drops, pending, cause)
+      this.surfaceBatchFailure(requestId, drops, pending, cause, loss, failure)
       return []
     }
 
@@ -167,7 +195,7 @@ export class V1CaptureSender {
     const maxAttempts = (Number.isInteger(maxRetries) && maxRetries > 0 ? maxRetries : 0) + 1
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       if (signal?.aborted) {
-        return unsent(signal.reason)
+        return unsent(signal.reason, 'not sent: aborted')
       }
       const isLastAttempt = attempt === maxAttempts
       const payload = buildV1Body(pending, { createdAt, historicalMigration: this.config.historicalMigration })
@@ -176,8 +204,14 @@ export class V1CaptureSender {
       let retryDelayMs: number | undefined
       try {
         captureAttempt = await this.sendOnce(url, payload, attempt, requestId, signal)
-        const { response, signal: attemptSignal } = captureAttempt
+        const { response, signal: attemptSignal, redirectFailure } = captureAttempt
         const { status } = response
+        if (redirectFailure !== undefined) {
+          await captureAttempt.waitFor(captureAttempt.cancelBody()).catch(() => {})
+          const failure = `failed on a redirect it does not follow (HTTP ${status})`
+          this.surfaceBatchFailure(requestId, drops, pending, new Error(redirectFailure), loss, failure)
+          return []
+        }
         if (status < 200 || status >= 300) {
           if (!isLastAttempt && RETRYABLE_STATUSES.has(status)) {
             const retryAfterMs = this.parseRetryAfter(response)
@@ -185,7 +219,7 @@ export class V1CaptureSender {
             retryDelayMs = this.backoffDelay(attempt, retryAfterMs)
           } else {
             const httpError = await this.buildHttpError(response, status, captureAttempt.waitFor)
-            this.surfaceBatchFailure(requestId, drops, pending, httpError)
+            this.surfaceBatchFailure(requestId, drops, pending, httpError, loss, `failed with HTTP ${status}`)
             return []
           }
         } else {
@@ -201,23 +235,32 @@ export class V1CaptureSender {
               requestId,
               drops,
               pending,
-              new Error(`Capture V1 returned an unparseable ${status} response body`)
+              new Error(`Capture V1 returned an unparseable ${status} response body`),
+              loss,
+              `failed with an unreadable response (HTTP ${status})`
             )
             return []
           }
 
+          const dropsBefore = drops.length
           const retryable = this.classify(pending, parsed, drops)
+          for (const drop of drops.slice(dropsBefore)) {
+            const cause = drop.details === DUPLICATE_EVENT_UUID ? 'dropped as duplicate uuids' : 'dropped by the server'
+            loss.add(`${cause} (HTTP ${status})`, 1)
+          }
           if (retryable.length === 0) {
-            this.surfacePartialDrops(requestId, drops)
+            this.surfacePartialDrops(requestId, drops, loss)
             return []
           }
           if (isLastAttempt) {
-            this.onError(
+            loss.add(`still marked for retry after ${maxAttempts} attempt(s) (HTTP ${status})`, retryable.length)
+            this.report(
               this.captureError({
                 requestId,
                 drops,
                 retryExhausted: retryable.map((event) => event.uuid),
-              })
+              }),
+              loss
             )
             return []
           }
@@ -234,7 +277,7 @@ export class V1CaptureSender {
         // Connection/timeouts, including a timeout while consuming the response body,
         // are retried until the budget runs out.
         if (isLastAttempt || signal?.aborted) {
-          return unsent(transportError)
+          return unsent(transportError, this.describeTransportFailure(transportError, signal))
         }
         retryDelayMs = this.backoffDelay(attempt)
       } finally {
@@ -302,6 +345,7 @@ export class V1CaptureSender {
           `Capture V1 request timed out ${timeoutPhase} after ${this.config.requestTimeoutMs}ms`
         )
         timeoutError.name = 'AbortError'
+        timeoutErrors.add(timeoutError)
         abortWith(timeoutError)
       }, this.config.requestTimeoutMs)
       if (externalSignal) {
@@ -321,24 +365,18 @@ export class V1CaptureSender {
     // Keeps an early abort from surfacing as an unhandled rejection before the race below observes it.
     deadline.catch(() => {})
     try {
-      // A fresh copy per request: fetch may detach a byte body it has sent.
-      const fetchPromise = this.fetchFn(url, {
-        method: 'POST',
-        headers,
-        body: typeof body === 'string' ? body : body.slice(),
-        signal: controller.signal,
-      })
+      const fetchPromise = this.fetchFollowingRedirects(url, headers, body, controller.signal)
       let responseAccepted = false
       void fetchPromise
-        .then((lateResponse) => {
+        .then((late) => {
           if (controller.signal.aborted && !responseAccepted) {
             // An injected fetch may ignore abort and resolve after the deadline.
             // Cancel its otherwise unreachable body to release any held resources.
-            void this.cancelBody(lateResponse)
+            void this.cancelBody(late.response)
           }
         })
         .catch(() => {})
-      const response = await Promise.race([fetchPromise, deadline])
+      const { response, redirectFailure } = await Promise.race([fetchPromise, deadline])
       responseAccepted = true
       timeoutPhase = 'while reading the response body'
       let cleanedUp = false
@@ -346,6 +384,7 @@ export class V1CaptureSender {
       const cancelBody = (): Promise<void> => (cancellation ??= this.cancelBody(response))
       return {
         response,
+        redirectFailure,
         signal: controller.signal,
         waitFor: <T>(operation: Promise<T>) => Promise.race([operation, deadline]),
         cancelBody,
@@ -370,6 +409,56 @@ export class V1CaptureSender {
     }
   }
 
+  /**
+   * Sends with `redirect: 'manual'` and follows 307 and 308 to the configured host's origin, at most
+   * `MAX_REDIRECTS` times, with the same method, headers and body. A fetch that follows redirects
+   * itself still works: its final response is not a redirect.
+   */
+  private async fetchFollowingRedirects(
+    url: string,
+    headers: PostHogFetchOptions['headers'],
+    body: string | Uint8Array,
+    signal: AbortSignal
+  ): Promise<RedirectOutcome> {
+    let target = url
+    for (let redirects = 0; ; redirects++) {
+      const response = await this.fetchFn(target, {
+        method: 'POST',
+        headers,
+        // A fresh copy per request: fetch may detach a byte body it has sent.
+        body: typeof body === 'string' ? body : body.slice(),
+        signal,
+        redirect: 'manual',
+      })
+      const { status } = response
+      if (status < 300 || status >= 400) {
+        return { response }
+      }
+      if (!FOLLOWED_REDIRECT_STATUSES.has(status)) {
+        return {
+          response,
+          redirectFailure: `Capture V1 request got an HTTP ${status} redirect, which it does not follow`,
+        }
+      }
+      if (redirects === MAX_REDIRECTS) {
+        return { response, redirectFailure: `Capture V1 request was redirected more than ${MAX_REDIRECTS} times` }
+      }
+      const next = resolveLocation(response.headers?.get('Location'), target)
+      if (next === undefined || originOf(next) !== this.hostOrigin) {
+        return {
+          response,
+          redirectFailure: `Capture V1 request got an HTTP ${status} redirect away from the configured host`,
+        }
+      }
+      void this.cancelBody(response)
+      // An injected fetch may ignore abort, so stop the chain here.
+      if (signal.aborted) {
+        throw signal.reason
+      }
+      target = next
+    }
+  }
+
   /** Compresses `payload` with the configured codec and sets `Content-Encoding` to match. */
   private async encodeBody(payload: string, headers: PostHogFetchOptions['headers']): Promise<string | Uint8Array> {
     const codec = this.config.compression
@@ -417,13 +506,30 @@ export class V1CaptureSender {
     parsed: V1BatchResponse,
     drops: CaptureDroppedEvent[]
   ): T[] {
-    const results = parsed.results ?? {}
+    // Events carry canonical uuids, so results match by the canonical form of the server's keys.
+    const results = new Map<string, V1EventResult>()
+    for (const [uuid, result] of Object.entries(parsed.results ?? {})) {
+      results.set(canonicalizeUuid(uuid) ?? uuid, result)
+    }
     const retryable: T[] = []
+    // Only built when a result reports duplicates, so the usual response costs nothing extra.
+    let copiesSeen: Map<string, number> | undefined
     for (const event of pending) {
-      const result = results[event.uuid]
+      const result = results.get(event.uuid)
       if (!result) {
         continue
       }
+      const duplicates = result.duplicates_dropped
+      if (typeof duplicates === 'number' && Number.isSafeInteger(duplicates) && duplicates > 0) {
+        copiesSeen ??= new Map()
+        const copy = copiesSeen.get(event.uuid) ?? 0
+        copiesSeen.set(event.uuid, copy + 1)
+        // The first copy takes the result; the next `duplicates` copies are the ones the server dropped.
+        if (copy >= 1 && copy <= duplicates) {
+          drops.push({ uuid: event.uuid, details: DUPLICATE_EVENT_UUID })
+          continue
+        }
+      }
       if (result.result === 'drop') {
         drops.push({ uuid: event.uuid, details: result.details ?? undefined })
       } else if (result.result === 'retry') {
@@ -496,15 +602,37 @@ export class V1CaptureSender {
     requestId: string,
     drops: CaptureDroppedEvent[],
     pending: SerializedV1Event[],
-    cause: unknown
+    cause: unknown,
+    loss: CaptureLossTally,
+    failure: string
   ): void {
-    this.onError(this.captureError({ requestId, drops, retryExhausted: pending.map((event) => event.uuid), cause }))
+    loss.add(failure, pending.length)
+    this.report(
+      this.captureError({ requestId, drops, retryExhausted: pending.map((event) => event.uuid), cause }),
+      loss
+    )
   }
 
-  private surfacePartialDrops(requestId: string, drops: CaptureDroppedEvent[]): void {
+  private surfacePartialDrops(requestId: string, drops: CaptureDroppedEvent[], loss: CaptureLossTally): void {
     if (drops.length > 0) {
-      this.onError(this.captureError({ requestId, drops, retryExhausted: [] }))
+      this.report(this.captureError({ requestId, drops, retryExhausted: [] }), loss)
+    }
+  }
+
+  private report(error: CaptureError, loss: CaptureLossTally): void {
+    this.onError(error, describeCaptureLoss(this.config.path, loss))
+  }
+
+  /** A failure without an HTTP response, named by type only: its message can carry server or proxy text. */
+  private describeTransportFailure(error: unknown, signal: AbortSignal | undefined): string {
+    if (error instanceof Error && timeoutErrors.has(error)) {
+      return 'failed: request timed out'
+    }
+    if (signal?.aborted) {
+      return 'failed: request aborted'
     }
+    const name = error instanceof Error && /^\w{1,64}$/.test(error.name) ? error.name : 'unknown'
+    return `failed with a network error (${name})`
   }
 
   private captureError(params: Omit<CaptureErrorParams, 'endpoint'>): CaptureError {
@@ -519,3 +647,22 @@ export class V1CaptureSender {
     }
   }
 }
+
+function originOf(url: string): string | undefined {
+  try {
+    return new URL(url).origin
+  } catch {
+    return undefined
+  }
+}
+
+function resolveLocation(location: string | null | undefined, base: string): string | undefined {
+  if (!location) {
+    return undefined
+  }
+  try {
+    return new URL(location, base).href
+  } catch {
+    return undefined
+  }
+}
diff --git a/packages/node/src/capture-v1/types.ts b/packages/node/src/capture-v1/types.ts
index 559e90a20e..97d60b7558 100644
--- a/packages/node/src/capture-v1/types.ts
+++ b/packages/node/src/capture-v1/types.ts
@@ -45,6 +45,8 @@ export type V1ResultCode = 'ok' | 'warning' | 'drop' | 'retry'
 export interface V1EventResult {
   result: V1ResultCode | string
   details?: string | null
+  /** How many later copies of this uuid in the request the server dropped as duplicates. */
+  duplicates_dropped?: number
 }
 
 /** Shape of a v1 2xx response body: a per-uuid map of results. */
diff --git a/packages/node/src/capture-v1/uuid.ts b/packages/node/src/capture-v1/uuid.ts
new file mode 100644
index 0000000000..ec2967dc8c
--- /dev/null
+++ b/packages/node/src/capture-v1/uuid.ts
@@ -0,0 +1,20 @@
+const HYPHENATED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const HEX_32 = /^[0-9a-f]{32}$/i
+const URN_PREFIX = 'urn:uuid:'
+
+/**
+ * The lowercase, hyphenated form of an RFC 4122 uuid string, or undefined for anything else.
+ * Accepts 32 hex digits, the hyphenated form, the hyphenated form in braces, and the
+ * `urn:uuid:` form, in any case.
+ */
+export function canonicalizeUuid(value: string): string | undefined {
+  let hyphenated = value
+  if (value.length === 38 && value.startsWith('{') && value.endsWith('}')) {
+    hyphenated = value.slice(1, -1)
+  } else if (value.length === 45 && value.slice(0, URN_PREFIX.length).toLowerCase() === URN_PREFIX) {
+    hyphenated = value.slice(URN_PREFIX.length)
+  } else if (HEX_32.test(value)) {
+    hyphenated = `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`
+  }
+  return HYPHENATED.test(hyphenated) ? hyphenated.toLowerCase() : undefined
+}
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index 583a368656..aefe57c49b 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -3,7 +3,6 @@ import { version } from './version'
 import {
   allSettled,
   FeatureFlagValue,
-  getEventUuid,
   isBlockedUA,
   isPlainObject,
   JsonType,
@@ -77,6 +76,7 @@ import { CaptureLane, type CaptureLaneConfig } from './capture-lane/lane'
 import { AI_MAX_PROPERTIES_BYTES, ANALYTICS_MAX_EVENT_BYTES, CAPTURE_BATCH_TARGET_BYTES } from './capture-lane/limits'
 import { type CaptureSettings, resolveCaptureSettings } from './capture-lane/settings'
 import { type CaptureCompressor, resolveCaptureCodec, webCompressor } from './capture-v1/compression'
+import { canonicalizeUuid } from './capture-v1/uuid'
 import { AI_CAPTURE_ROUTE } from './ai-capture/routing'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
@@ -117,6 +117,17 @@ function normalizePersonalApiKey(value?: unknown): string | undefined {
   return normalizedValue || undefined
 }
 
+/** Capture options plus a flag that the caller's uuid was already replaced, with its one warning. */
+type LaneCaptureOptions = PostHogCaptureOptions & { _invalidUuidWarned?: boolean }
+
+function isUnsetUuid(uuid: unknown): boolean {
+  return uuid === undefined || uuid === null || uuid === ''
+}
+
+function isInvalidUuid(uuid: unknown): boolean {
+  return !isUnsetUuid(uuid) && (typeof uuid !== 'string' || canonicalizeUuid(uuid) === undefined)
+}
+
 function normalizeHost(value?: unknown): string {
   const normalizedValue = typeof value === 'string' ? value.trim() : ''
   return normalizedValue || DEFAULT_NODE_HOST
@@ -367,10 +378,32 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   }
 
   private _prepareLaneMessage(message: any, options?: PostHogCaptureOptions): PostHogEventProperties | null {
-    const prepared = this.processBeforeEnqueue(this.prepareMessage(message, options))
+    const { _invalidUuidWarned, ...captureOptions } = (options ?? {}) as LaneCaptureOptions
+    // before_send already ran, so this is the hook's uuid; check it again, warning at most once per call.
+    const uuid = this._canonicalEventUuid(captureOptions.uuid, !_invalidUuidWarned)
+    const prepared = this.processBeforeEnqueue(this.prepareMessage(message, { ...captureOptions, uuid }))
     return prepared === null ? null : this.normalizeMessage(prepared)
   }
 
+  /**
+   * The canonical form of a caller's event uuid, or undefined when there is none to keep. An
+   * invalid uuid is replaced with a generated one and a warning that never repeats the value.
+   */
+  private _canonicalEventUuid(uuid: unknown, warnIfInvalid = true): string | undefined {
+    if (isUnsetUuid(uuid)) {
+      return undefined
+    }
+    const canonical = typeof uuid === 'string' ? canonicalizeUuid(uuid) : undefined
+    if (canonical !== undefined) {
+      return canonical
+    }
+    if (warnIfInvalid) {
+      // console.warn, not this._logger: the logger only prints in debug mode, and the event loses its uuid.
+      console.warn('[PostHog] Replaced an invalid event uuid with a generated one; uuids must be RFC 4122 strings')
+    }
+    return uuidv7()
+  }
+
   /**
    * Concurrent so a serverless handler waits for one round trip, not two. A
    * failed span export leaves the spans queued rather than rejecting, since
@@ -579,10 +612,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       lane = new CaptureLane(this._captureLaneConfig(endpoint), {
         sender: new V1CaptureSender(this.captureSenderConfig(endpoint, compressor), {
           fetch: (url, fetchOptions) => this.fetch(url, fetchOptions),
-          onError: (error) => this._events.emit('error', error),
+          onError: (error, summary) => this._reportCaptureLoss([error], summary),
           compress: (payload, codec) => compressor.compress(payload, codec),
         }),
-        onLocalDrops: (error) => this._reportLocalCaptureDrops(error),
+        onLocalDrops: (errors, summary) => this._reportCaptureLoss(errors, summary),
         onError: (error) => this._events.emit('error', error),
         onFlush: (messages) => this._events.emit('flush', messages),
         onBackgroundFlush: (flush) => this._onLaneBackgroundFlush(flush),
@@ -612,12 +645,15 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
   }
 
-  private _reportLocalCaptureDrops(error: CaptureError): void {
+  /** Emits each error; with no `'error'` listener, logs `summary` once instead, since the events are lost. */
+  private _reportCaptureLoss(errors: CaptureError[], summary: string): void {
     const errorListeners = this._events.events['error']?.length ?? 0
-    this._events.emit('error', error)
+    for (const error of errors) {
+      this._events.emit('error', error)
+    }
     if (errorListeners === 0) {
-      // console.warn, not this._logger: the logger only prints in debug mode, and these drops lose data.
-      console.warn(`[PostHog] ${error.message}`)
+      // console.warn, not this._logger: the logger only prints in debug mode.
+      console.warn(`[PostHog] ${summary}`)
     }
   }
 
@@ -993,13 +1029,19 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     prepareOptions?: { includeContextProperties?: boolean },
     explicitRoute?: string
   ): Promise<void> {
+    const invalidUuidWarned = isInvalidUuid(props.uuid)
+    const uuid = this._canonicalEventUuid(props.uuid)
+    if (uuid !== props.uuid) {
+      props = { ...props, uuid }
+    }
     return this.addPendingPromise(
       this._prepareEventMessage(props, prepareOptions)
         .then(({ distinctId, event, properties, options }) => {
-          const captureOptions: PostHogCaptureOptions = {
+          const captureOptions: LaneCaptureOptions = {
             timestamp: options.timestamp,
             disableGeoip: options.disableGeoip,
             uuid: options.uuid,
+            _invalidUuidWarned: invalidUuidWarned,
           }
           const message = {
             distinctId,
@@ -1120,7 +1162,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (this.disabled) {
       return undefined
     }
-    const uuid = getEventUuid(props.uuid, uuidv7)
+    const uuid = this._canonicalEventUuid(props.uuid) ?? uuidv7()
     void this._sendPreparedAiEvent({ ...props, uuid }, false)
     return uuid
   }
@@ -1139,7 +1181,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (this.disabled) {
       return undefined
     }
-    const uuid = getEventUuid(props.uuid, uuidv7)
+    const uuid = this._canonicalEventUuid(props.uuid) ?? uuidv7()
     await this._sendPreparedAiEvent({ ...props, uuid }, true)
     return uuid
   }
diff --git a/packages/react-native/references/posthog-react-native-references-latest.json b/packages/react-native/references/posthog-react-native-references-latest.json
index 62ac6aaa72..c7b319b4ac 100644
--- a/packages/react-native/references/posthog-react-native-references-latest.json
+++ b/packages/react-native/references/posthog-react-native-references-latest.json
@@ -3624,6 +3624,10 @@
         {
           "type": "AbortSignal",
           "name": "signal"
+        },
+        {
+          "type": "\"error\" | \"follow\" | \"manual\"",
+          "name": "redirect"
         }
       ],
       "path": "../core/src/types.ts"

From 445ce89811570cb46970b6c871e41584a435b14a Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:21:05 -0700
Subject: [PATCH 09/20] feat(node)!: add per-event capture options and send
 their values unchanged (#5412)

* feat(node)!: send event option values unchanged

The wire builder no longer converts option values. It sends the event's
`options` object as given, removes each legacy option property
(`$process_person_profile`, `$cookieless_mode`, `$ignore_sent_at`,
`$product_tour_id`) from `properties`, and uses its value only when the
matching option is missing or null. Unknown option keys pass through, and
an `options` value that is not an object is logged once and ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): warn when a non-string session or window id is dropped

`$session_id` and `$window_id` still move to the top-level `session_id` and
`window_id` only when they are strings. A null value is dropped silently;
any other value is dropped with a warning that names its JSON type and
never the value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node): add per-event options to every capture call

`capture`, `captureImmediate`, `captureAi`, `captureAiImmediate`, `identify`,
`alias`, `groupIdentify`, `setPersonProperties` and `unsetPersonProperties`
(and their immediate forms) take an optional `options` map that is sent to
capture unchanged. An `options` value that is not an object is logged once
and the event is sent without it.

`before_send` receives the options and its returned options are sent. The
hook now gets copies of `properties` and its `$set`, `$set_once`, `$groups`
and `$group_set` maps, so it cannot change the caller's objects.

An event with no distinct id now sets the `process_person_profile` option
to false, unless the caller set it, instead of the legacy
`$process_person_profile` property.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for per-event capture options

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): accept options on alias in the IPostHog interface

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): give before_send a full copy of plain values and always an options object

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(node): before_send always gets an options object

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): note that capture drops an event with an unreadable option

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-node-capture-options.md    |   7 +
 .../posthog-node-references-latest.json       |  41 +-
 .../server-wire-snapshots.spec.ts.snap        |  18 +-
 .../src/__tests__/capture-v1/options.spec.ts  | 373 ++++++++++++++++++
 .../__tests__/capture-v1/transform.spec.ts    | 247 ++++++++----
 .../node/src/__tests__/posthog-node.spec.ts   |   1 +
 .../__tests__/server-wire-snapshots.spec.ts   |   5 +-
 .../src/__tests__/types/public-interface.ts   |   2 +
 packages/node/src/capture-v1/transform.ts     | 124 +++---
 packages/node/src/capture-v1/types.ts         |  13 +-
 packages/node/src/client.ts                   |  92 ++++-
 packages/node/src/types.ts                    |  36 +-
 12 files changed, 768 insertions(+), 191 deletions(-)
 create mode 100644 .changeset/posthog-node-capture-options.md
 create mode 100644 packages/node/src/__tests__/capture-v1/options.spec.ts

diff --git a/.changeset/posthog-node-capture-options.md b/.changeset/posthog-node-capture-options.md
new file mode 100644
index 0000000000..3020c0c5fa
--- /dev/null
+++ b/.changeset/posthog-node-capture-options.md
@@ -0,0 +1,7 @@
+---
+'posthog-node': major
+---
+
+Every capture call takes a per-event `options` map that is sent to capture unchanged (the SDK no longer converts option values); legacy `$` option properties such as `$process_person_profile` still fill unset options and are removed from `properties`.
+A `$session_id` or `$window_id` that is not a string is dropped with a warning.
+Capture drops an event whose option value it cannot read, such as `cookieless_mode: [1, 2, 3]`, and the SDK reports it through `'error'` with `details: 'invalid_options'`.
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index 1c74ef5d75..eef0b06c7b 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -94,7 +94,7 @@
             {
               "description": "The alias data containing distinctId and alias",
               "isOptional": false,
-              "type": "{\n        distinctId: string;\n        alias: string;\n        disableGeoip?: boolean;\n    }",
+              "type": "{\n        distinctId: string;\n        alias: string;\n        disableGeoip?: boolean;\n        options?: Record<string, JsonType>;\n    }",
               "name": "data"
             }
           ],
@@ -123,7 +123,7 @@
             {
               "description": "The alias data containing distinctId and alias",
               "isOptional": false,
-              "type": "{\n        distinctId: string;\n        alias: string;\n        disableGeoip?: boolean;\n    }",
+              "type": "{\n        distinctId: string;\n        alias: string;\n        disableGeoip?: boolean;\n        options?: Record<string, JsonType>;\n    }",
               "name": "data"
             }
           ],
@@ -1008,7 +1008,7 @@
               "description": "",
               "isOptional": false,
               "type": "any",
-              "name": "{ groupType, groupKey, properties, distinctId, disableGeoip }"
+              "name": "{ groupType, groupKey, properties, distinctId, disableGeoip, options }"
             },
             {
               "description": "",
@@ -1043,7 +1043,7 @@
               "description": "",
               "isOptional": false,
               "type": "any",
-              "name": "{ groupType, groupKey, properties, distinctId, disableGeoip, }"
+              "name": "{ groupType, groupKey, properties, distinctId, disableGeoip, options, }"
             },
             {
               "description": "",
@@ -1083,7 +1083,7 @@
               "description": "",
               "isOptional": false,
               "type": "any",
-              "name": "{ distinctId, properties, disableGeoip }"
+              "name": "{ distinctId, properties, disableGeoip, options }"
             },
             {
               "description": "",
@@ -1118,7 +1118,7 @@
               "description": "",
               "isOptional": false,
               "type": "any",
-              "name": "{ distinctId, properties, disableGeoip }"
+              "name": "{ distinctId, properties, disableGeoip, options }"
             },
             {
               "description": "",
@@ -1345,7 +1345,7 @@
               "description": "",
               "isOptional": false,
               "type": "any",
-              "name": "{ distinctId, properties, propertiesOnce }"
+              "name": "{ distinctId, properties, propertiesOnce, options }"
             },
             {
               "description": "",
@@ -1415,7 +1415,7 @@
               "description": "",
               "isOptional": false,
               "type": "any",
-              "name": "{ distinctId, properties }"
+              "name": "{ distinctId, properties, options }"
             },
             {
               "description": "",
@@ -2268,6 +2268,11 @@
           "type": "boolean",
           "name": "disableGeoip"
         },
+        {
+          "description": "Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,\n`cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;\nunknown keys pass through. A legacy property such as `$process_person_profile` fills an option\nleft unset. Capture drops an event whose option value it cannot read (`invalid_options`), and\nthe SDK reports the drop through the `'error'` event.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
+        },
         {
           "type": "string",
           "name": "distinctId"
@@ -2714,6 +2719,11 @@
         {
           "type": "boolean",
           "name": "disableGeoip"
+        },
+        {
+          "description": "Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,\n`cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;\nunknown keys pass through. A legacy property such as `$process_person_profile` fills an option\nleft unset. Capture drops an event whose option value it cannot read (`invalid_options`), and\nthe SDK reports the drop through the `'error'` event.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
         }
       ],
       "path": "src/types.ts"
@@ -2733,6 +2743,11 @@
         {
           "type": "boolean",
           "name": "disableGeoip"
+        },
+        {
+          "description": "Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,\n`cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;\nunknown keys pass through. A legacy property such as `$process_person_profile` fills an option\nleft unset. Capture drops an event whose option value it cannot read (`invalid_options`), and\nthe SDK reports the drop through the `'error'` event.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
         }
       ],
       "path": "src/types.ts"
@@ -4374,6 +4389,11 @@
         {
           "type": "Record<string | number, any>",
           "name": "propertiesOnce"
+        },
+        {
+          "description": "Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,\n`cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;\nunknown keys pass through. A legacy property such as `$process_person_profile` fills an option\nleft unset. Capture drops an event whose option value it cannot read (`invalid_options`), and\nthe SDK reports the drop through the `'error'` event.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
         }
       ],
       "path": "src/types.ts"
@@ -4988,6 +5008,11 @@
         {
           "type": "string | string[]",
           "name": "properties"
+        },
+        {
+          "description": "Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,\n`cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;\nunknown keys pass through. A legacy property such as `$process_person_profile` fills an option\nleft unset. Capture drops an event whose option value it cannot read (`invalid_options`), and\nthe SDK reports the drop through the `'error'` event.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
         }
       ],
       "path": "src/types.ts"
diff --git a/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap b/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap
index ed6ed57a73..65f38c9af0 100644
--- a/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap
+++ b/packages/node/src/__tests__/__snapshots__/server-wire-snapshots.spec.ts.snap
@@ -130,11 +130,12 @@ exports[`server wire snapshots > snapshots the canonical Capture V1 transform an
     "batch": [
       {
         "distinct_id": "person-1",
-        "event": "all-valid-sentinels",
+        "event": "options-and-legacy-properties",
         "options": {
-          "cookieless_mode": true,
-          "disable_skew_correction": false,
-          "process_person_profile": false,
+          "cookieless_mode": "1",
+          "disable_skew_correction": "false",
+          "future_option": "kept",
+          "process_person_profile": true,
           "product_tour_id": "tour-7",
         },
         "properties": {
@@ -159,8 +160,13 @@ exports[`server wire snapshots > snapshots the canonical Capture V1 transform an
       },
       {
         "distinct_id": "person-2",
-        "event": "invalid-sentinels-are-omitted",
-        "options": {},
+        "event": "legacy-option-values-sent-unchanged",
+        "options": {
+          "cookieless_mode": "maybe",
+          "disable_skew_correction": null,
+          "process_person_profile": [],
+          "product_tour_id": 7,
+        },
         "properties": {
           "ordinary": true,
         },
diff --git a/packages/node/src/__tests__/capture-v1/options.spec.ts b/packages/node/src/__tests__/capture-v1/options.spec.ts
new file mode 100644
index 0000000000..e956480132
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/options.spec.ts
@@ -0,0 +1,373 @@
+import type { JsonType } from '@posthog/core'
+
+import { EventMessage, PostHog, PostHogOptions } from '@/entrypoints/index.node'
+import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, captureEvents } from '../utils'
+import { V1WiringHarness } from '../utils/v1-wiring'
+
+const UUID = '0199c3e8-4c7b-7e2e-9f21-2b6d5a1c9e04'
+const OPTIONS_ERROR = /^\[PostHog\] options must be an object, got \w+; sending the event without its options$/
+
+describe('per-event capture options', () => {
+  vi.useFakeTimers()
+
+  const harness = new V1WiringHarness()
+  const makeClient = (options?: PostHogOptions): PostHog => harness.makeClient(options)
+  const wireEvents = (path: string = ANALYTICS_CAPTURE_PATH): any[] => captureEvents(harness.fetch, path)
+
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(console, 'info').mockImplementation(() => {})
+    harness.useDefaultRouting()
+  })
+
+  afterEach(async () => {
+    await harness.cleanup()
+    vi.clearAllMocks()
+  })
+
+  const optionsErrors = (): unknown[][] =>
+    (console.error as vi.Mock).mock.calls.filter((call) => OPTIONS_ERROR.test(String(call[0])))
+
+  /** Sends one event through `client` and returns the single wire event it produced on `path`. */
+  const sendOne = async (
+    send: (client: PostHog) => unknown,
+    clientOptions?: PostHogOptions,
+    path: string = ANALYTICS_CAPTURE_PATH
+  ): Promise<any> => {
+    const posthog = makeClient(clientOptions)
+    await send(posthog)
+    await posthog.flush()
+    const events = wireEvents(path)
+    expect(events).toHaveLength(1)
+    return events[0]
+  }
+
+  describe('every capture call sends its options', () => {
+    // Values a converting SDK would change: each must arrive exactly as sent.
+    const OPTIONS: Record<string, JsonType> = {
+      cookieless_mode: 'YES',
+      disable_skew_correction: 0,
+      product_tour_id: ['tour', 1],
+      future_option: { nested: 'no' },
+    }
+
+    it.each<[string, (client: PostHog, options: Record<string, JsonType>) => unknown, string]>([
+      ['capture', (c, options) => c.capture({ distinctId: 'u', event: 'e', options }), ANALYTICS_CAPTURE_PATH],
+      [
+        'captureImmediate',
+        (c, options) => c.captureImmediate({ distinctId: 'u', event: 'e', options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      ['captureAi', (c, options) => c.captureAi({ distinctId: 'u', event: '$ai_span', options }), AI_CAPTURE_PATH],
+      [
+        'captureAiImmediate',
+        (c, options) => c.captureAiImmediate({ distinctId: 'u', event: '$ai_span', options }),
+        AI_CAPTURE_PATH,
+      ],
+      [
+        'identify',
+        (c, options) => c.identify({ distinctId: 'u', properties: { a: 1 }, options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'identifyImmediate',
+        (c, options) => c.identifyImmediate({ distinctId: 'u', properties: { a: 1 }, options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      ['alias', (c, options) => c.alias({ distinctId: 'u', alias: 'anon', options }), ANALYTICS_CAPTURE_PATH],
+      [
+        'aliasImmediate',
+        (c, options) => c.aliasImmediate({ distinctId: 'u', alias: 'anon', options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'groupIdentify',
+        (c, options) => c.groupIdentify({ groupType: 'company', groupKey: 'acme', options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'groupIdentifyImmediate',
+        (c, options) => c.groupIdentifyImmediate({ groupType: 'company', groupKey: 'acme', options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'setPersonProperties',
+        (c, options) => c.setPersonProperties({ distinctId: 'u', properties: { plan: 'pro' }, options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'unsetPersonProperties',
+        (c, options) => c.unsetPersonProperties({ distinctId: 'u', properties: ['plan'], options }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+    ])('%s', async (_method, send, path) => {
+      const event = await sendOne((client) => send(client, OPTIONS), undefined, path)
+
+      expect(event.options).toStrictEqual(OPTIONS)
+    })
+  })
+
+  describe('an options value that is not an object', () => {
+    it.each<[string, unknown]>([
+      ['an array', ['cookieless_mode']],
+      ['a string', 'cookieless_mode'],
+      ['a number', 1],
+      ['a boolean', true],
+    ])('logs one error for %s and sends the event without it', async (_label, options) => {
+      const event = await sendOne((client) =>
+        client.capture({
+          distinctId: 'u',
+          event: 'e',
+          properties: { $cookieless_mode: true, keep: 'me' },
+          options: options as Record<string, JsonType>,
+        })
+      )
+
+      expect(event.options).toStrictEqual({ cookieless_mode: true })
+      expect(event.properties.keep).toBe('me')
+      expect(event.properties).not.toHaveProperty('$cookieless_mode')
+      expect(optionsErrors()).toHaveLength(1)
+    })
+
+    it('still applies the personless default', async () => {
+      const event = await sendOne((client) =>
+        client.capture({ event: 'e', options: 'bad' as unknown as Record<string, JsonType> })
+      )
+
+      expect(event.options).toStrictEqual({ process_person_profile: false })
+      expect(optionsErrors()).toHaveLength(1)
+    })
+
+    it('logs one error when before_send returns one', async () => {
+      const event = await sendOne(
+        (client) => client.capture({ distinctId: 'u', event: 'e', options: { cookieless_mode: true } }),
+        { before_send: (e) => (e ? { ...e, options: 'bad' as unknown as Record<string, JsonType> } : e) }
+      )
+
+      expect(event.options).toStrictEqual({})
+      expect(optionsErrors()).toHaveLength(1)
+    })
+
+    it.each([null, undefined])('treats %s as no options, without logging', async (options) => {
+      const event = await sendOne((client) =>
+        client.capture({ distinctId: 'u', event: 'e', options: options as unknown as Record<string, JsonType> })
+      )
+
+      expect(event.options).toStrictEqual({})
+      expect(console.error).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('personless events', () => {
+    it('sets the process_person_profile option, not the legacy property, before before_send', async () => {
+      const seen: EventMessage[] = []
+      const event = await sendOne((client) => client.capture({ event: 'e', properties: { keep: 'me' } }), {
+        before_send: (e) => {
+          seen.push(structuredClone(e!))
+          return e
+        },
+      })
+
+      expect(seen[0].options).toStrictEqual({ process_person_profile: false })
+      expect(seen[0].properties).not.toHaveProperty('$process_person_profile')
+      expect(event.options).toStrictEqual({ process_person_profile: false })
+    })
+
+    it.each<[string, Record<string, JsonType>, Record<string, JsonType>]>([
+      ['a caller true option wins', { process_person_profile: true }, { process_person_profile: true }],
+      ['a caller null option gets the default', { process_person_profile: null }, { process_person_profile: false }],
+      [
+        'other caller options are kept',
+        { cookieless_mode: true },
+        { cookieless_mode: true, process_person_profile: false },
+      ],
+    ])('%s', async (_label, options, expected) => {
+      const event = await sendOne((client) => client.capture({ event: 'e', options }))
+
+      expect(event.options).toStrictEqual(expected)
+    })
+
+    it('does not set the option when the event has a distinct id', async () => {
+      const event = await sendOne((client) => client.capture({ distinctId: 'u', event: 'e' }))
+
+      expect(event.options).toStrictEqual({})
+    })
+  })
+
+  describe('before_send', () => {
+    it('receives copies, so a hook that mutates the event cannot change the caller objects', async () => {
+      const options: Record<string, JsonType> = { cookieless_mode: false }
+      const properties = {
+        $set: { name: 'caller' },
+        $set_once: { first: 'caller' },
+        $groups: { company: 'caller' },
+        plain: 'caller',
+        cart: { items: ['caller'] },
+        user: { email: 'caller@example.com', name: 'caller' },
+      }
+      const snapshot = structuredClone({ options, properties })
+
+      const event = await sendOne((client) => client.capture({ distinctId: 'u', event: 'e', properties, options }), {
+        before_send: (e) => {
+          e!.options!.cookieless_mode = true
+          e!.options!.added = 'hook'
+          e!.properties!.$set.name = 'hook'
+          e!.properties!.$set_once.first = 'hook'
+          e!.properties!.$groups.company = 'hook'
+          e!.properties!.plain = 'hook'
+          e!.properties!.cart.items.push('hook')
+          delete e!.properties!.user.email
+          return e
+        },
+      })
+
+      expect({ options, properties }).toStrictEqual(snapshot)
+      expect(event.options).toStrictEqual({ cookieless_mode: true, added: 'hook' })
+      expect(event.properties).toMatchObject({
+        $set: { name: 'hook' },
+        $set_once: { first: 'hook' },
+        $groups: { company: 'hook' },
+        plain: 'hook',
+        cart: { items: ['caller', 'hook'] },
+        user: { name: 'caller' },
+      })
+    })
+
+    it('cannot change register() defaults for later events', async () => {
+      let first = true
+      const posthog = makeClient({
+        before_send: (e) => {
+          if (first) {
+            e!.properties!.app.version = 'hook'
+            first = false
+          }
+          return e
+        },
+      })
+      await posthog.register({ app: { version: 'caller' } })
+
+      posthog.capture({ distinctId: 'u', event: 'first' })
+      posthog.capture({ distinctId: 'u', event: 'second' })
+      await posthog.flush()
+
+      expect(wireEvents().map((event) => event.properties.app.version)).toEqual(['hook', 'caller'])
+    })
+
+    it('gets an options object when the caller passes none', async () => {
+      const event = await sendOne((client) => client.capture({ distinctId: 'u', event: 'e' }), {
+        before_send: (e) => {
+          e!.options!.process_person_profile = false
+          return e
+        },
+      })
+
+      expect(event.options).toStrictEqual({ process_person_profile: false })
+      expect(console.error).not.toHaveBeenCalled()
+    })
+
+    it.each<[string, (client: PostHog, properties: Record<string, any>) => unknown, string]>([
+      [
+        'capture',
+        (c, properties) => c.capture({ distinctId: 'u', event: 'e', properties, uuid: UUID, timestamp: new Date(0) }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'captureAi',
+        (c, properties) =>
+          c.captureAi({ distinctId: 'u', event: '$ai_span', properties, uuid: UUID, timestamp: new Date(0) }),
+        AI_CAPTURE_PATH,
+      ],
+    ])('a pass-through hook leaves the %s wire event unchanged', async (_method, send, path) => {
+      const properties = () => ({
+        nested: { list: [1, { deep: null }], empty_object: {}, empty_array: [] },
+        nothing: null,
+        when: new Date(0),
+      })
+
+      for (const client of [makeClient(), makeClient({ before_send: (e) => e })]) {
+        await send(client, properties())
+        await client.flush()
+      }
+
+      const events = captureEvents(harness.fetch, path)
+      expect(events).toHaveLength(2)
+      expect(events[1]).toStrictEqual(events[0])
+    })
+
+    it.each<[string, (client: PostHog, properties: Record<string, any>) => unknown]>([
+      ['identify', (c, properties) => c.identify({ distinctId: 'u', properties: { $set: properties } })],
+      ['groupIdentify', (c, properties) => c.groupIdentify({ groupType: 'company', groupKey: 'acme', properties })],
+    ])('cannot change the person or group properties the caller passed to %s', async (_method, send) => {
+      const callerProperties = { name: 'caller' }
+
+      await sendOne((client) => send(client, callerProperties), {
+        before_send: (e) => {
+          for (const key of ['$set', '$group_set']) {
+            if (e!.properties![key]) {
+              e!.properties![key].name = 'hook'
+            }
+          }
+          return e
+        },
+      })
+
+      expect(callerProperties).toStrictEqual({ name: 'caller' })
+    })
+
+    it.each<[string, (e: EventMessage) => EventMessage, Record<string, JsonType>]>([
+      [
+        'replaced options are sent',
+        (e) => ({ ...e, options: { product_tour_id: 'hook' } }),
+        { product_tour_id: 'hook' },
+      ],
+      ['removed options remove the caller options', ({ options: _options, ...e }) => e, {}],
+      [
+        'an added legacy property fills an unset option',
+        (e) => ({ ...e, properties: { ...e.properties, $process_person_profile: false } }),
+        { cookieless_mode: true, process_person_profile: false },
+      ],
+      [
+        'an added legacy property does not replace a set option',
+        (e) => ({ ...e, properties: { ...e.properties, $cookieless_mode: false } }),
+        { cookieless_mode: true },
+      ],
+    ])('%s', async (_label, hook, expected) => {
+      const event = await sendOne(
+        (client) => client.capture({ distinctId: 'u', event: 'e', options: { cookieless_mode: true } }),
+        { before_send: (e) => hook(e!) }
+      )
+
+      expect(event.options).toStrictEqual(expected)
+    })
+
+    it('sees a caller $lib, and neither it nor a hook-set $lib is sent', async () => {
+      const seenLib: unknown[] = []
+      const event = await sendOne(
+        (client) => client.capture({ distinctId: 'u', event: 'e', properties: { $lib: 'caller-lib', keep: 'me' } }),
+        {
+          before_send: (e) => {
+            seenLib.push(e!.properties!.$lib)
+            return { ...e!, properties: { ...e!.properties, $lib: 'hook-lib', $lib_version: 'hook-version' } }
+          },
+        }
+      )
+
+      expect(seenLib).toEqual(['caller-lib'])
+      expect(event.properties.keep).toBe('me')
+      expect(event.properties).not.toHaveProperty('$lib')
+      expect(event.properties).not.toHaveProperty('$lib_version')
+    })
+
+    it('can add $session_id and $window_id, which move to the top level', async () => {
+      const event = await sendOne((client) => client.capture({ distinctId: 'u', event: 'e' }), {
+        before_send: (e) => ({ ...e!, properties: { ...e!.properties, $session_id: 's', $window_id: 'w' } }),
+      })
+
+      expect(event.session_id).toBe('s')
+      expect(event.window_id).toBe('w')
+      expect(event.properties).not.toHaveProperty('$session_id')
+      expect(event.properties).not.toHaveProperty('$window_id')
+    })
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/transform.spec.ts b/packages/node/src/__tests__/capture-v1/transform.spec.ts
index 9698d03776..91632d2992 100644
--- a/packages/node/src/__tests__/capture-v1/transform.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/transform.spec.ts
@@ -1,6 +1,6 @@
 import type { JsonType, PostHogEventProperties } from '@posthog/core'
 
-import { buildV1Event, coerceBool, coerceString } from '@/capture-v1/transform'
+import { buildV1Event } from '@/capture-v1/transform'
 
 function baseMessage(overrides: PostHogEventProperties = {}): PostHogEventProperties {
   return {
@@ -14,102 +14,134 @@ function baseMessage(overrides: PostHogEventProperties = {}): PostHogEventProper
 }
 
 describe('capture v1 transform', () => {
-  describe('coerceBool', () => {
-    it.each<[string, JsonType, boolean | undefined]>([
-      ['native true', true, true],
-      ['native false', false, false],
-      ['string "true"', 'true', true],
-      ['string "TRUE" (case-insensitive)', 'TRUE', true],
-      ['string " true " (trimmed)', ' true ', true],
-      ['string "1"', '1', true],
-      ['string "false"', 'false', false],
-      ['string "FALSE"', 'FALSE', false],
-      ['string " 0 " (trimmed)', ' 0 ', false],
-      ['string "0"', '0', false],
-      ['number 1', 1, true],
-      ['number 42', 42, true],
-      ['number -1 (nonzero)', -1, true],
-      ['number 0', 0, false],
-      ['string "yes" (uncoercible)', 'yes', undefined],
-      ['string "off" (uncoercible)', 'off', undefined],
-      ['empty string (uncoercible)', '', undefined],
-      ['null (uncoercible)', null, undefined],
-      ['array (uncoercible)', [], undefined],
-      ['object (uncoercible)', {}, undefined],
-    ])('coerces %s', (_label, input, expected) => {
-      expect(coerceBool(input)).toBe(expected)
-    })
+  afterEach(() => {
+    vi.restoreAllMocks()
   })
 
-  describe('coerceString', () => {
-    it.each<[string, JsonType, string | undefined]>([
-      ['native string', 'abc', 'abc'],
-      ['empty string', '', ''],
-      ['integer (dropped)', 42, undefined],
-      ['zero (dropped)', 0, undefined],
-      ['negative integer (dropped)', -7, undefined],
-      ['float (dropped)', 1.5, undefined],
-      ['bool (dropped)', true, undefined],
-      ['null (dropped)', null, undefined],
-      ['array (dropped)', [], undefined],
-      ['object (dropped)', {}, undefined],
-    ])('accepts only strings: %s', (_label, input, expected) => {
-      expect(coerceString(input)).toBe(expected)
-    })
-  })
+  describe('buildV1Event - options and legacy option properties', () => {
+    const LEGACY_PAIRS = [
+      ['$process_person_profile', 'process_person_profile'],
+      ['$cookieless_mode', 'cookieless_mode'],
+      ['$ignore_sent_at', 'disable_skew_correction'],
+      ['$product_tour_id', 'product_tour_id'],
+    ] as const
+
+    describe.each(LEGACY_PAIRS)('%s and %s', (property, optionKey) => {
+      it.each<[string, JsonType | undefined, JsonType | undefined, JsonType | undefined]>([
+        ['a set option wins over the legacy property', 'from-option', 'from-legacy', 'from-option'],
+        ['a false option wins over a true legacy property', false, true, false],
+        ['the legacy property fills a missing option', undefined, 'from-legacy', 'from-legacy'],
+        ['the legacy property fills a null option', null, false, false],
+        ['a null option without a legacy property is sent as null', null, undefined, null],
+        ['a null legacy property fills a missing option with null', undefined, null, null],
+      ])('%s', (_label, optionValue, legacyValue, expected) => {
+        const event = buildV1Event(
+          baseMessage({
+            options: optionValue === undefined ? {} : { [optionKey]: optionValue },
+            properties: legacyValue === undefined ? { keep: 'me' } : { [property]: legacyValue, keep: 'me' },
+          })
+        )
+
+        expect(event.options).toStrictEqual({ [optionKey]: expected })
+        expect(event.properties).toStrictEqual({ keep: 'me' })
+      })
 
-  describe('buildV1Event - option sentinels', () => {
-    it.each<[string, JsonType, keyof ReturnType<typeof buildV1Event>['options'], boolean | string]>([
-      ['$cookieless_mode', true, 'cookieless_mode', true],
-      ['$ignore_sent_at', 'true', 'disable_skew_correction', true],
-      ['$process_person_profile', 0, 'process_person_profile', false],
-      ['$product_tour_id', 'tour_9', 'product_tour_id', 'tour_9'],
-    ])('lifts %s into options and strips it from properties', (property, value, optionKey, expected) => {
-      const event = buildV1Event(baseMessage({ properties: { [property]: value, keep: 'me' } }))
-
-      expect(event.options[optionKey]).toBe(expected)
-      expect(event.properties).not.toHaveProperty(property)
-      expect(event.properties.keep).toBe('me')
-    })
+      it('leaves the option out when neither the option nor the legacy property is set', () => {
+        const event = buildV1Event(baseMessage({ properties: { keep: 'me' } }))
 
-    it('drops a non-string $product_tour_id but still strips the sentinel', () => {
-      const event = buildV1Event(baseMessage({ properties: { $product_tour_id: 42, keep: 'me' } }))
-      expect(event.options).not.toHaveProperty('product_tour_id')
-      expect(event.properties).not.toHaveProperty('$product_tour_id')
-      expect(event.properties.keep).toBe('me')
-    })
+        expect(event.options).not.toHaveProperty(optionKey)
+      })
+
+      it.each<[string, JsonType]>([
+        ['string "no"', 'no'],
+        ['string "YES"', 'YES'],
+        ['string "maybe"', 'maybe'],
+        ['number 0', 0],
+        ['number 1.5', 1.5],
+        ['array', ['a', 1]],
+        ['object', { nested: true }],
+      ])('sends a legacy %s value unchanged', (_label, value) => {
+        const event = buildV1Event(baseMessage({ properties: { [property]: value } }))
+
+        expect(event.options).toStrictEqual({ [optionKey]: value })
+        expect(event.properties).toStrictEqual({})
+      })
 
-    it('omits an option that cannot be coerced but still strips the sentinel', () => {
-      const event = buildV1Event(baseMessage({ properties: { $cookieless_mode: 'maybe', $product_tour_id: 1.5 } }))
+      it.each<[string, JsonType]>([
+        ['string "no"', 'no'],
+        ['string "YES"', 'YES'],
+        ['string "maybe"', 'maybe'],
+        ['number 0', 0],
+        ['array', [true]],
+      ])('sends an option %s value unchanged', (_label, value) => {
+        const event = buildV1Event(baseMessage({ options: { [optionKey]: value } }))
 
-      expect(event.options).not.toHaveProperty('cookieless_mode')
-      expect(event.options).not.toHaveProperty('product_tour_id')
-      expect(event.properties).not.toHaveProperty('$cookieless_mode')
-      expect(event.properties).not.toHaveProperty('$product_tour_id')
+        expect(event.options).toStrictEqual({ [optionKey]: value })
+      })
     })
 
-    it('leaves options as an empty object when no sentinels are present', () => {
-      const event = buildV1Event(baseMessage({ properties: { foo: 'bar' } }))
-      expect(event.options).toEqual({})
+    it('passes unknown option keys through unchanged', () => {
+      const event = buildV1Event(
+        baseMessage({ options: { future_option: 'x', another: [1, { deep: null }] }, properties: { keep: 'me' } })
+      )
+
+      expect(event.options).toStrictEqual({ future_option: 'x', another: [1, { deep: null }] })
+      expect(event.properties).toStrictEqual({ keep: 'me' })
     })
 
-    it('populates multiple options together', () => {
+    it('combines caller options with every legacy property', () => {
       const event = buildV1Event(
         baseMessage({
+          options: { process_person_profile: true, future_option: 1 },
           properties: {
+            $process_person_profile: false,
             $cookieless_mode: '1',
-            $ignore_sent_at: false,
-            $process_person_profile: true,
-            $product_tour_id: 'abc',
+            $ignore_sent_at: 'false',
+            $product_tour_id: 7,
+            keep: 'me',
           },
         })
       )
-      expect(event.options).toEqual({
-        cookieless_mode: true,
-        disable_skew_correction: false,
+
+      expect(event.options).toStrictEqual({
         process_person_profile: true,
-        product_tour_id: 'abc',
+        future_option: 1,
+        cookieless_mode: '1',
+        disable_skew_correction: 'false',
+        product_tour_id: 7,
       })
+      expect(event.properties).toStrictEqual({ keep: 'me' })
+    })
+
+    it('sends options as an empty object when nothing sets one', () => {
+      expect(buildV1Event(baseMessage({ properties: { foo: 'bar' } })).options).toStrictEqual({})
+      expect(buildV1Event(baseMessage({ options: null })).options).toStrictEqual({})
+    })
+
+    it('does not log when options are missing or null', () => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      buildV1Event(baseMessage())
+      buildV1Event(baseMessage({ options: null }))
+
+      expect(error).not.toHaveBeenCalled()
+    })
+
+    it.each<[string, JsonType, string]>([
+      ['an array', ['process_person_profile'], 'array'],
+      ['a string', 'process_person_profile', 'string'],
+      ['a number', 0, 'number'],
+      ['a boolean', true, 'boolean'],
+    ])('logs one error for %s options and still lifts the legacy properties', (_label, options, typeName) => {
+      const error = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+      const event = buildV1Event(baseMessage({ options, properties: { $cookieless_mode: true, keep: 'me' } }))
+
+      expect(event.options).toStrictEqual({ cookieless_mode: true })
+      expect(event.properties).toStrictEqual({ keep: 'me' })
+      expect(error.mock.calls).toEqual([
+        [`[PostHog] options must be an object, got ${typeName}; sending the event without its options`],
+      ])
     })
   })
 
@@ -126,11 +158,53 @@ describe('capture v1 transform', () => {
       expect(event.properties.keep).toBe('me')
     })
 
-    it('drops a non-string $session_id but still strips it', () => {
-      const event = buildV1Event(baseMessage({ properties: { $session_id: 123 } }))
+    it.each(['$session_id', '$window_id'] as const)('sends an empty %s string as an empty string', (property) => {
+      const event = buildV1Event(baseMessage({ properties: { [property]: '' } }))
 
-      expect(event.session_id).toBeUndefined()
-      expect(event.properties).not.toHaveProperty('$session_id')
+      expect(event[property === '$session_id' ? 'session_id' : 'window_id']).toBe('')
+      expect(event.properties).toStrictEqual({})
+    })
+
+    it.each(['$session_id', '$window_id'] as const)('drops a null %s without a warning', (property) => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      const event = buildV1Event(baseMessage({ properties: { [property]: null } }))
+
+      expect(event).not.toHaveProperty('session_id')
+      expect(event).not.toHaveProperty('window_id')
+      expect(event.properties).toStrictEqual({})
+      expect(warn).not.toHaveBeenCalled()
+    })
+
+    describe.each(['$session_id', '$window_id'] as const)('a %s that is not a string', (property) => {
+      it.each<[string, JsonType]>([
+        ['number', 123],
+        ['boolean', false],
+        ['object', { id: 'secret-value' }],
+        ['array', ['secret-value']],
+      ])('is dropped with a warning naming its %s type and not its value', (typeName, value) => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+        const event = buildV1Event(baseMessage({ properties: { [property]: value, keep: 'me' } }))
+
+        expect(event).not.toHaveProperty('session_id')
+        expect(event).not.toHaveProperty('window_id')
+        expect(event.properties).toStrictEqual({ keep: 'me' })
+        expect(warn.mock.calls).toEqual([[`[PostHog] dropping ${property}: a ${typeName} value is not a string`]])
+      })
+    })
+
+    it('warns on every dropped id, not once per process', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+      buildV1Event(baseMessage({ properties: { $session_id: 1, $window_id: 2 } }))
+      buildV1Event(baseMessage({ properties: { $session_id: 3 } }))
+
+      expect(warn.mock.calls).toEqual([
+        ['[PostHog] dropping $session_id: a number value is not a string'],
+        ['[PostHog] dropping $window_id: a number value is not a string'],
+        ['[PostHog] dropping $session_id: a number value is not a string'],
+      ])
     })
 
     it('omits session_id/window_id when the sentinels are absent', () => {
@@ -254,7 +328,14 @@ describe('capture v1 transform', () => {
     it('does not mutate the input message or its properties', () => {
       const message = baseMessage({
         $set: { name: 'Jane' },
-        properties: { $cookieless_mode: true, $session_id: 'sess', $lib: 'posthog-node', keep: 'me' },
+        options: { process_person_profile: null },
+        properties: {
+          $cookieless_mode: true,
+          $process_person_profile: false,
+          $session_id: 'sess',
+          $lib: 'posthog-node',
+          keep: 'me',
+        },
       })
       const snapshot = structuredClone(message)
 
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index 530ea011f4..b7a4fa2085 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -718,6 +718,7 @@ describe('PostHog Node.js', () => {
         distinctId: '123',
         event: 'test-event',
         properties: { foo: 'bar' },
+        options: {},
         groups: undefined,
         sendFeatureFlags: undefined,
         timestamp: undefined,
diff --git a/packages/node/src/__tests__/server-wire-snapshots.spec.ts b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
index 3e4294f814..4e790bff0e 100644
--- a/packages/node/src/__tests__/server-wire-snapshots.spec.ts
+++ b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
@@ -99,12 +99,13 @@ describe('server wire snapshots', () => {
 
     const messages = [
       {
-        event: 'all-valid-sentinels',
+        event: 'options-and-legacy-properties',
         distinct_id: 'person-1',
         uuid: FIXED_EVENT_UUID,
         timestamp: '2025-02-03T05:05:06.123456+01:00',
         $set: { plan: 'pro' },
         $set_once: { first_seen: '2025-02-03' },
+        options: { process_person_profile: true, future_option: 'kept' },
         properties: {
           $cookieless_mode: '1',
           $ignore_sent_at: 'false',
@@ -118,7 +119,7 @@ describe('server wire snapshots', () => {
         },
       },
       {
-        event: 'invalid-sentinels-are-omitted',
+        event: 'legacy-option-values-sent-unchanged',
         distinct_id: 'person-2',
         uuid: '0194cc39-1f25-7000-8000-000000000003',
         timestamp: '2025-02-03T04:05:07.000Z',
diff --git a/packages/node/src/__tests__/types/public-interface.ts b/packages/node/src/__tests__/types/public-interface.ts
index a15eaa541a..14a88a62c4 100644
--- a/packages/node/src/__tests__/types/public-interface.ts
+++ b/packages/node/src/__tests__/types/public-interface.ts
@@ -4,5 +4,7 @@ export function checkPublicInterface(posthog: PostHog): Promise<void> {
   const client: IPostHog = posthog
   client.metrics.count('jobs.processed', 1)
   client.captureException(new Error('queued exception'), 'user')
+  client.alias({ distinctId: 'user', alias: 'anonymous', options: { cookieless_mode: true } })
+  void client.aliasImmediate({ distinctId: 'user', alias: 'anonymous', options: { cookieless_mode: true } })
   return client.captureExceptionImmediate(new Error('immediate exception'), 'user')
 }
diff --git a/packages/node/src/capture-v1/transform.ts b/packages/node/src/capture-v1/transform.ts
index d1ebd148ca..d81e0714b5 100644
--- a/packages/node/src/capture-v1/transform.ts
+++ b/packages/node/src/capture-v1/transform.ts
@@ -2,64 +2,46 @@ import type { JsonType, PostHogEventProperties } from '@posthog/core'
 
 import type { V1Event, V1EventOptions } from './types'
 
-/**
- * Coerce a value to a boolean the way the capture server does, or return
- * `undefined` if it cannot be coerced (the option is then omitted so the server
- * falls back to its default). Accepts native booleans, the strings
- * `"true"`/`"1"`/`"false"`/`"0"` (trimmed, case-insensitive), and any number
- * (nonzero -> true).
- */
-export function coerceBool(value: JsonType): boolean | undefined {
-  if (typeof value === 'boolean') {
-    return value
-  }
-  if (typeof value === 'number') {
-    return value !== 0
-  }
-  if (typeof value === 'string') {
-    const normalized = value.trim().toLowerCase()
-    if (normalized === 'true' || normalized === '1') {
-      return true
-    }
-    if (normalized === 'false' || normalized === '0') {
-      return false
-    }
-  }
-  return undefined
-}
-
-/**
- * Accept only a native string, else return `undefined` (the option is then
- * omitted). The backend's `product_tour_id` is `Option<String>`, so numbers,
- * booleans, objects, and arrays are dropped rather than coerced — matching
- * posthog-go, posthog-rs, and posthog-python exactly.
- */
-export function coerceString(value: JsonType): string | undefined {
-  return typeof value === 'string' ? value : undefined
-}
-
-/** Legacy sentinel property -> typed `options` field, with its coercion. */
-const OPTION_SENTINELS: ReadonlyArray<{
-  property: string
-  optionKey: keyof V1EventOptions
-  coerce: (value: JsonType) => boolean | string | undefined
-}> = [
-  { property: '$cookieless_mode', optionKey: 'cookieless_mode', coerce: coerceBool },
-  { property: '$ignore_sent_at', optionKey: 'disable_skew_correction', coerce: coerceBool },
-  { property: '$process_person_profile', optionKey: 'process_person_profile', coerce: coerceBool },
-  { property: '$product_tour_id', optionKey: 'product_tour_id', coerce: coerceString },
+/** Legacy property -> the `options` key it fills when the caller left that option unset. */
+const LEGACY_OPTION_PROPERTIES: ReadonlyArray<{ property: string; optionKey: string }> = [
+  { property: '$process_person_profile', optionKey: 'process_person_profile' },
+  { property: '$cookieless_mode', optionKey: 'cookieless_mode' },
+  { property: '$ignore_sent_at', optionKey: 'disable_skew_correction' },
+  { property: '$product_tour_id', optionKey: 'product_tour_id' },
 ]
 
-/** Sentinel property -> top-level string field (string-only, non-string dropped). */
+/** Property -> top-level string field; any value that is not a string is dropped. */
 const TOPLEVEL_SENTINELS: ReadonlyArray<{ property: string; field: 'session_id' | 'window_id' }> = [
   { property: '$session_id', field: 'session_id' },
   { property: '$window_id', field: 'window_id' },
 ]
 
-function isRecord(value: JsonType | undefined): value is PostHogEventProperties {
+function isRecord(value: unknown): value is PostHogEventProperties {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+function jsonTypeName(value: JsonType): string {
+  return Array.isArray(value) ? 'array' : typeof value
+}
+
+/**
+ * A copy of the caller's per-event options, or undefined when there are none. Any value that
+ * is not an object is reported and ignored, so the event is still sent.
+ */
+export function readEventOptions(value: unknown): V1EventOptions | undefined {
+  if (value === undefined || value === null) {
+    return undefined
+  }
+  if (isRecord(value)) {
+    return { ...value }
+  }
+  // console.error, not the client logger: the logger only prints in debug mode, and the event loses its options.
+  console.error(
+    `[PostHog] options must be an object, got ${jsonTypeName(value as JsonType)}; sending the event without its options`
+  )
+  return undefined
+}
+
 /**
  * Normalize an event timestamp to an RFC 3339 string. The queued message
  * carries either an ISO string (from `currentISOTime()`) or a `Date` (when the
@@ -101,36 +83,42 @@ function relocateInto(properties: PostHogEventProperties, key: string, value: Js
  * Transform one already-normalized queued message into a Capture V1 wire event.
  *
  * The input message is never mutated (events may be retried or handed to
- * callbacks): a fresh `properties` map is built. Sentinel properties are lifted
- * out of `properties` (deleting the copy) into the typed `options` object and
- * the top-level `session_id`/`window_id` fields; `$lib`/`$lib_version` are
- * stripped (the server injects them from `PostHog-Sdk-Info`); top-level
- * `$set`/`$set_once` are relocated into `properties`.
+ * callbacks): fresh `options` and `properties` maps are built. Option values are
+ * sent unchanged; capture reads them. Each legacy option property is removed from
+ * `properties` and fills its option when the caller left that option missing or
+ * `null`. `$session_id`/`$window_id` move to the top-level `session_id`/`window_id`
+ * fields; `$lib`/`$lib_version` are stripped (the server injects them from
+ * `PostHog-Sdk-Info`); top-level `$set`/`$set_once` are relocated into `properties`.
  */
 export function buildV1Event(message: PostHogEventProperties): V1Event {
   const sourceProperties = isRecord(message.properties) ? message.properties : {}
   const properties: PostHogEventProperties = { ...sourceProperties }
 
-  const options: V1EventOptions = {}
-  for (const { property, optionKey, coerce } of OPTION_SENTINELS) {
-    if (property in properties) {
-      const coerced = coerce(properties[property])
-      if (coerced !== undefined) {
-        ;(options as Record<string, boolean | string>)[optionKey] = coerced
-      }
-      // Always strip the sentinel, even when coercion omits the option.
-      delete properties[property]
+  const options: V1EventOptions = readEventOptions(message.options) ?? {}
+  for (const { property, optionKey } of LEGACY_OPTION_PROPERTIES) {
+    if (!(property in properties)) {
+      continue
+    }
+    const legacyValue = properties[property]
+    delete properties[property]
+    const option = options[optionKey]
+    if ((option === undefined || option === null) && legacyValue !== undefined) {
+      options[optionKey] = legacyValue
     }
   }
 
   const topLevel: { session_id?: string; window_id?: string } = {}
   for (const { property, field } of TOPLEVEL_SENTINELS) {
-    if (property in properties) {
-      const value = properties[property]
-      if (typeof value === 'string') {
-        topLevel[field] = value
-      }
-      delete properties[property]
+    if (!(property in properties)) {
+      continue
+    }
+    const value = properties[property]
+    delete properties[property]
+    if (typeof value === 'string') {
+      topLevel[field] = value
+    } else if (value !== undefined && value !== null) {
+      // console.warn, not the client logger: the logger only prints in debug mode, and the event loses this id.
+      console.warn(`[PostHog] dropping ${property}: a ${jsonTypeName(value)} value is not a string`)
     }
   }
 
diff --git a/packages/node/src/capture-v1/types.ts b/packages/node/src/capture-v1/types.ts
index 97d60b7558..15f593e6db 100644
--- a/packages/node/src/capture-v1/types.ts
+++ b/packages/node/src/capture-v1/types.ts
@@ -1,4 +1,4 @@
-import type { PostHogEventProperties } from '@posthog/core'
+import type { JsonType, PostHogEventProperties } from '@posthog/core'
 
 /** Capture lane for analytics events. */
 export const ANALYTICS_CAPTURE_ENDPOINT = '/i/v1/analytics/events'
@@ -9,16 +9,11 @@ export const AI_CAPTURE_ENDPOINT = '/i/v1/ai/events'
 export type CaptureEndpoint = typeof ANALYTICS_CAPTURE_ENDPOINT | typeof AI_CAPTURE_ENDPOINT
 
 /**
- * Typed `options` object on a Capture V1 event. Legacy `$`-prefixed sentinel
- * properties are lifted here (renamed + strictly typed) by the transform.
+ * The `options` object on a Capture V1 event: the caller's options plus any legacy
+ * `$`-prefixed option properties lifted by the transform. Values are sent unchanged.
  * Always serialized as an object (`{}` when empty), never `null`.
  */
-export interface V1EventOptions {
-  cookieless_mode?: boolean
-  disable_skew_correction?: boolean
-  process_person_profile?: boolean
-  product_tour_id?: string
-}
+export type V1EventOptions = Record<string, JsonType>
 
 /**
  * A single event in a Capture V1 batch.
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index aefe57c49b..bce9c6a3a1 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -77,6 +77,7 @@ import { AI_MAX_PROPERTIES_BYTES, ANALYTICS_MAX_EVENT_BYTES, CAPTURE_BATCH_TARGE
 import { type CaptureSettings, resolveCaptureSettings } from './capture-lane/settings'
 import { type CaptureCompressor, resolveCaptureCodec, webCompressor } from './capture-v1/compression'
 import { canonicalizeUuid } from './capture-v1/uuid'
+import { readEventOptions } from './capture-v1/transform'
 import { AI_CAPTURE_ROUTE } from './ai-capture/routing'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
@@ -133,6 +134,52 @@ function normalizeHost(value?: unknown): string {
   return normalizedValue || DEFAULT_NODE_HOST
 }
 
+/**
+ * A copy of the event for `before_send`, so a hook that mutates it cannot change the caller's
+ * objects or the `register()` and context defaults. Plain objects and arrays are copied all the
+ * way down; class instances (`Date`, `Buffer`, custom classes) stay shared. The hook always gets
+ * an `options` object it can write to.
+ */
+function isolateForBeforeSend(eventMessage: EventMessage): EventMessage {
+  const isolated = copyPlainValues(eventMessage, new WeakMap()) as EventMessage
+  isolated.options ??= {}
+  return isolated
+}
+
+/** Only objects with no prototype or `Object.prototype`: a copy keeps no class or `toJSON` method. */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+// `seen` keeps a circular value circular, so it still fails at serialization as it would without a hook.
+function copyPlainValues(value: unknown, seen: WeakMap<object, unknown>): unknown {
+  if (!Array.isArray(value) && !isPlainRecord(value)) {
+    return value
+  }
+  const known = seen.get(value)
+  if (known !== undefined) {
+    return known
+  }
+  if (Array.isArray(value)) {
+    const copy: unknown[] = new Array(value.length)
+    seen.set(value, copy)
+    value.forEach((item, index) => {
+      copy[index] = copyPlainValues(item, seen)
+    })
+    return copy
+  }
+  const copy: Record<string, unknown> = Object.getPrototypeOf(value) === null ? Object.create(null) : {}
+  seen.set(value, copy)
+  for (const key of Object.keys(value)) {
+    copy[key] = copyPlainValues(value[key], seen)
+  }
+  return copy
+}
+
 function normalizeUnsetPersonProperties(value: string | string[]): string[] {
   const propertyNames = Array.isArray(value) ? value : [value]
   return propertyNames.filter(
@@ -1036,7 +1083,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
     return this.addPendingPromise(
       this._prepareEventMessage(props, prepareOptions)
-        .then(({ distinctId, event, properties, options }) => {
+        .then(({ distinctId, event, properties, options, eventOptions }) => {
           const captureOptions: LaneCaptureOptions = {
             timestamp: options.timestamp,
             disableGeoip: options.disableGeoip,
@@ -1050,6 +1097,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
               ...properties,
               ...this.getCommonEventProperties(),
             },
+            ...(eventOptions !== undefined ? { options: eventOptions } : {}),
           }
           return immediate
             ? this.sendImmediate(type, message, captureOptions, explicitRoute)
@@ -1226,7 +1274,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param data - The identify data containing distinctId and properties
    */
-  identify({ distinctId, properties = {}, disableGeoip }: IdentifyMessage): void {
+  identify({ distinctId, properties = {}, disableGeoip, options }: IdentifyMessage): void {
     // Catch properties passed as $set and move them to the top level
     const { $set, $set_once, $anon_distinct_id, ...rest } = properties
     // if no $set is provided we assume all rest properties are $set
@@ -1239,7 +1287,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
     this._sendPreparedEvent(
       'identify',
-      { distinctId, event: '$identify', properties: eventProperties, disableGeoip },
+      { distinctId, event: '$identify', properties: eventProperties, disableGeoip, options },
       false,
       { includeContextProperties: false }
     )
@@ -1265,7 +1313,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param data - The identify data containing distinctId and properties
    * @returns Promise that resolves when the identify is processed
    */
-  async identifyImmediate({ distinctId, properties = {}, disableGeoip }: IdentifyMessage): Promise<void> {
+  async identifyImmediate({ distinctId, properties = {}, disableGeoip, options }: IdentifyMessage): Promise<void> {
     // Catch properties passed as $set and move them to the top level
     const { $set, $set_once, $anon_distinct_id, ...rest } = properties
     // if no $set is provided we assume all rest properties are $set
@@ -1278,7 +1326,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
     await this._sendPreparedEvent(
       'identify',
-      { distinctId, event: '$identify', properties: eventProperties, disableGeoip },
+      { distinctId, event: '$identify', properties: eventProperties, disableGeoip, options },
       true,
       { includeContextProperties: false }
     )
@@ -1300,7 +1348,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param data - The data containing distinctId and properties to set
    */
-  setPersonProperties({ distinctId, properties = {}, propertiesOnce = {} }: SetPersonPropertiesMessage): void {
+  setPersonProperties({ distinctId, properties = {}, propertiesOnce = {}, options }: SetPersonPropertiesMessage): void {
     if (Object.keys(properties).length === 0 && Object.keys(propertiesOnce).length === 0) {
       return
     }
@@ -1317,6 +1365,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       distinctId,
       event: '$set',
       properties: eventProperties,
+      options,
     })
   }
 
@@ -1335,13 +1384,13 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param data - The data containing distinctId and property names to unset
    */
-  unsetPersonProperties({ distinctId, properties }: UnsetPersonPropertiesMessage): void {
+  unsetPersonProperties({ distinctId, properties, options }: UnsetPersonPropertiesMessage): void {
     const propertyNames = normalizeUnsetPersonProperties(properties)
     if (propertyNames.length === 0) {
       return
     }
 
-    this.capture({ distinctId, event: '$set', properties: { $unset: propertyNames } })
+    this.capture({ distinctId, event: '$set', properties: { $unset: propertyNames }, options })
   }
 
   /**
@@ -1360,7 +1409,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param data - The alias data containing distinctId and alias
    */
-  alias(data: { distinctId: string; alias: string; disableGeoip?: boolean }): void {
+  alias(data: { distinctId: string; alias: string; disableGeoip?: boolean; options?: Record<string, JsonType> }): void {
     this._sendPreparedEvent(
       'alias',
       {
@@ -1368,6 +1417,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         event: '$create_alias',
         properties: { distinct_id: data.distinctId, alias: data.alias },
         disableGeoip: data.disableGeoip,
+        options: data.options,
       },
       false,
       { includeContextProperties: false }
@@ -1391,7 +1441,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param data - The alias data containing distinctId and alias
    * @returns Promise that resolves when the alias is processed
    */
-  async aliasImmediate(data: { distinctId: string; alias: string; disableGeoip?: boolean }): Promise<void> {
+  async aliasImmediate(data: {
+    distinctId: string
+    alias: string
+    disableGeoip?: boolean
+    options?: Record<string, JsonType>
+  }): Promise<void> {
     await this._sendPreparedEvent(
       'alias',
       {
@@ -1399,6 +1454,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         event: '$create_alias',
         properties: { distinct_id: data.distinctId, alias: data.alias },
         disableGeoip: data.disableGeoip,
+        options: data.options,
       },
       true,
       { includeContextProperties: false }
@@ -2687,7 +2743,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param data - The group identify data
    */
-  groupIdentify({ groupType, groupKey, properties, distinctId, disableGeoip }: GroupIdentifyMessage): void {
+  groupIdentify({ groupType, groupKey, properties, distinctId, disableGeoip, options }: GroupIdentifyMessage): void {
     this._sendPreparedEvent(
       'capture',
       {
@@ -2699,6 +2755,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
           $group_set: properties || {},
         },
         disableGeoip,
+        options,
       },
       false,
       { includeContextProperties: false }
@@ -2733,6 +2790,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     properties,
     distinctId,
     disableGeoip,
+    options,
   }: GroupIdentifyMessage): Promise<void> {
     await this._sendPreparedEvent(
       'capture',
@@ -2745,6 +2803,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
           $group_set: properties || {},
         },
         disableGeoip,
+        options,
       },
       true,
       { includeContextProperties: false }
@@ -3339,6 +3398,8 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     event: string
     properties: PostHogEventProperties
     options: PostHogCaptureOptions
+    /** The event's `options` map, sent to capture unchanged. */
+    eventOptions?: Record<string, JsonType>
   }> {
     const {
       distinctId,
@@ -3351,6 +3412,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       disableGeoip,
       uuid,
     }: EventMessage = props
+    let eventOptions = readEventOptions(props.options)
 
     const contextData = this.context?.get()
     const includeContextProperties = options.includeContextProperties ?? true
@@ -3371,7 +3433,9 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     if (!mergedDistinctId) {
       mergedDistinctId = uuidv7()
-      mergedProperties.$process_person_profile = false
+      if (eventOptions?.process_person_profile === undefined || eventOptions.process_person_profile === null) {
+        eventOptions = { ...eventOptions, process_person_profile: false }
+      }
     }
 
     if (includeContextProperties && contextData?.sessionId && !mergedProperties.$session_id) {
@@ -3397,6 +3461,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       timestamp,
       disableGeoip,
       uuid,
+      options: eventOptions,
     })
 
     if (!eventMessage) {
@@ -3482,6 +3547,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         disableGeoip: eventMessage.disableGeoip,
         uuid: eventMessage.uuid,
       },
+      eventOptions: eventMessage.options,
     }
   }
 
@@ -3492,7 +3558,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
 
     const fns = Array.isArray(beforeSend) ? beforeSend : [beforeSend]
-    let result: EventMessage | null = eventMessage
+    let result: EventMessage | null = isolateForBeforeSend(eventMessage)
 
     for (const fn of fns) {
       try {
diff --git a/packages/node/src/types.ts b/packages/node/src/types.ts
index 81f4ec15f0..bf2419f12d 100644
--- a/packages/node/src/types.ts
+++ b/packages/node/src/types.ts
@@ -22,17 +22,41 @@ export type IdentifyMessage = {
   distinctId: string
   properties?: Record<string | number, any>
   disableGeoip?: boolean
+  /**
+   * Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,
+   * `cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;
+   * unknown keys pass through. A legacy property such as `$process_person_profile` fills an option
+   * left unset. Capture drops an event whose option value it cannot read (`invalid_options`), and
+   * the SDK reports the drop through the `'error'` event.
+   */
+  options?: Record<string, JsonType>
 }
 
 export type SetPersonPropertiesMessage = {
   distinctId: string
   properties?: Record<string | number, any>
   propertiesOnce?: Record<string | number, any>
+  /**
+   * Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,
+   * `cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;
+   * unknown keys pass through. A legacy property such as `$process_person_profile` fills an option
+   * left unset. Capture drops an event whose option value it cannot read (`invalid_options`), and
+   * the SDK reports the drop through the `'error'` event.
+   */
+  options?: Record<string, JsonType>
 }
 
 export type UnsetPersonPropertiesMessage = {
   distinctId: string
   properties: string | string[]
+  /**
+   * Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,
+   * `cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;
+   * unknown keys pass through. A legacy property such as `$process_person_profile` fills an option
+   * left unset. Capture drops an event whose option value it cannot read (`invalid_options`), and
+   * the SDK reports the drop through the `'error'` event.
+   */
+  options?: Record<string, JsonType>
 }
 
 export type SendFeatureFlagsOptions = {
@@ -76,6 +100,14 @@ export type GroupIdentifyMessage = {
   properties?: Record<string | number, any>
   distinctId?: string // optional distinctId to associate message with a person
   disableGeoip?: boolean
+  /**
+   * Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,
+   * `cookieless_mode`, `disable_skew_correction` (legacy `$ignore_sent_at`) and `product_tour_id`;
+   * unknown keys pass through. A legacy property such as `$process_person_profile` fills an option
+   * left unset. Capture drops an event whose option value it cannot read (`invalid_options`), and
+   * the SDK reports the drop through the `'error'` event.
+   */
+  options?: Record<string, JsonType>
 }
 
 export type PropertyGroup = {
@@ -694,7 +726,7 @@ export interface IPostHog {
    * @param distinctId the current unique id
    * @param alias the unique ID of the user before
    */
-  alias(data: { distinctId: string; alias: string }): void
+  alias(data: { distinctId: string; alias: string; options?: Record<string, JsonType> }): void
 
   /**
    * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
@@ -702,7 +734,7 @@ export interface IPostHog {
    * @param distinctId the current unique id
    * @param alias the unique ID of the user before
    */
-  aliasImmediate(data: { distinctId: string; alias: string }): Promise<void>
+  aliasImmediate(data: { distinctId: string; alias: string; options?: Record<string, JsonType> }): Promise<void>
 
   /**
    * @description PostHog feature flags (https://posthog.com/docs/features/feature-flags)

From 0ac45c1221afb94f250ac138a0e812939672e031 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:21:57 -0700
Subject: [PATCH 10/20] feat(node)!: build every event in one layer order, with
 global and context options (#5413)

* feat(node): add registerOptions() and context options

`registerOptions()` and `unregisterOptions()` set options for every event,
next to `register()`. A context takes `options` next to `properties`;
nested contexts inherit them unless `fresh: true`.

Each event fills the options it left unset (missing or null) from the
context, then from `registerOptions()`, then from the SDK's personless
option, before `before_send` runs. A value that is not an object logs one
error and is ignored.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: fill context, global and SDK values before before_send

Each event now fills the properties it left unset (key missing or
undefined) from the context, then from `register()`, then from the values
the SDK adds: `$is_server`, `$geoip_disable` from the `disableGeoip`
setting, feature flag properties from `flags` or `sendFeatureFlags`, and,
on `$exception`, the OpenTelemetry trace ids (as a pair) and the injected
`$release_id`. So a value set on the event, in context or with
`register()` now beats every SDK value, and `before_send` sees and can
change all of them; nothing is added after the hook.

`$set`, `$set_once`, `$groups` and `$group_set` fill one level deep. Typed
`groups` merge over a `$groups` property key by key. A per-call
`disableGeoip` sets `$geoip_disable` under the event's own property, so
`disableGeoip: false` now sends `$geoip_disable: false`. The minimal
`$feature_flag_called` allowlist runs after every fill and keeps the
properties that set options and session fields. `$bot_pageview` renaming
happens before the hook.

`$lib` and `$lib_version` are no longer added to properties; the request
header carries them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: apply every layer to identify, alias and group identify

Context and `register()` properties and options now reach `$identify`,
`$create_alias` and `$groupidentify` like every other event. Identify's
context properties go into the event properties, not into `$set`, and
identify no longer sends an empty `$set_once`.

An empty or whitespace-only distinct id counts as missing, so the context
id or a personless id is used. `groupIdentify` without a distinct id uses
the context id before `$<groupType>_<groupKey>`, and never takes the
context session. `alias` never takes its target from a context or a
registered property, and its `distinct_id` property is the resolved id.

The `IPostHog` `alias` and `aliasImmediate` signatures accept
`disableGeoip` and `options`, like the client.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): ignore reserved exception properties passed to captureException

Following sdk-specs `exception-event-metadata`, properties passed to
`captureException` can no longer set the exception properties the SDK or
PostHog owns: `$exception_list`, `$exception_level`, `$exception_source`,
`$debug_images` and the processor-owned `$exception_*` and
`$cymbal_errors` keys. Other properties are kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for layered event values

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): note that before_send edits properties, not the disableGeoip or groups fields

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): note ignored exception properties and the cost of a bad registered option

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-node-capture-layers.md     |   8 +
 .../posthog-node-references-latest.json       | 200 +++--
 .../src/__tests__/capture-v1/layers.spec.ts   | 712 ++++++++++++++++++
 .../node/src/__tests__/evaluate-flags.spec.ts |   2 -
 .../src/__tests__/feature-flags.flags.spec.ts |  10 -
 .../node/src/__tests__/feature-flags.spec.ts  |   2 -
 .../node/src/__tests__/posthog-node.spec.ts   |  23 +-
 packages/node/src/client.ts                   | 457 ++++++-----
 packages/node/src/event-defaults.ts           |  75 ++
 .../node/src/extensions/context/context.ts    |   4 +
 packages/node/src/extensions/context/types.ts |   8 +
 .../src/extensions/error-tracking/index.ts    |  35 +-
 packages/node/src/types.ts                    |  46 +-
 13 files changed, 1312 insertions(+), 270 deletions(-)
 create mode 100644 .changeset/posthog-node-capture-layers.md
 create mode 100644 packages/node/src/__tests__/capture-v1/layers.spec.ts
 create mode 100644 packages/node/src/event-defaults.ts

diff --git a/.changeset/posthog-node-capture-layers.md b/.changeset/posthog-node-capture-layers.md
new file mode 100644
index 0000000000..02dd6d4fba
--- /dev/null
+++ b/.changeset/posthog-node-capture-layers.md
@@ -0,0 +1,8 @@
+---
+'posthog-node': major
+---
+
+Values set on the event, in context or with `register()` / the new `registerOptions()` now win over the values the SDK adds (`$is_server`, `$geoip_disable`, feature flag properties, trace ids), and `before_send` sees and can change all of them; context and registered properties and options, including the new context `options`, also reach identify, alias and group identify events.
+An empty or whitespace distinct id counts as missing, and `$groupidentify` without a distinct id uses the context id, then `$<type>_<key>`.
+`$geoip_disable` and `$groups` are filled before `before_send`, so a hook that changes the message's `disableGeoip` or `groups` field has no effect: edit the properties instead.
+Reserved exception properties such as `$exception_level` passed in `captureException()` properties are now ignored, so the SDK's value is sent.
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index eef0b06c7b..2aa4fb144c 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -254,7 +254,7 @@
               "name": "distinctId"
             },
             {
-              "description": "Optional additional properties to include",
+              "description": "Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.",
               "isOptional": true,
               "type": "Record<string | number, any>",
               "name": "additionalProperties"
@@ -312,7 +312,7 @@
               "name": "distinctId"
             },
             {
-              "description": "Optional additional properties to include",
+              "description": "Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.",
               "isOptional": true,
               "type": "Record<string | number, any>",
               "name": "additionalProperties"
@@ -464,7 +464,7 @@
           "releaseTag": "public",
           "params": [
             {
-              "description": "Context data to apply (distinctId, sessionId, properties)",
+              "description": "Context data to apply (distinctId, sessionId, properties, options)",
               "isOptional": false,
               "type": "Partial<ContextData>",
               "name": "data"
@@ -1258,6 +1258,64 @@
           },
           "path": "src/entrypoints/index.node.ts"
         },
+        {
+          "category": "Capture",
+          "description": "Register properties that every event sent by this client carries.",
+          "details": "Each event fills the keys it left unset in this order: the event's own values, then context properties, then these, then the values the SDK adds (such as `$is_server` and `$geoip_disable`). `before_send` sees the result and can change it.",
+          "id": "register",
+          "showDocs": true,
+          "title": "register",
+          "examples": [
+            {
+              "id": "",
+              "name": "",
+              "code": "\n\nawait client.register({ service: 'billing' })\n\n\n\n"
+            }
+          ],
+          "releaseTag": "public",
+          "params": [
+            {
+              "description": "The properties to add to every event",
+              "isOptional": false,
+              "type": "PostHogEventProperties",
+              "name": "properties"
+            }
+          ],
+          "returnType": {
+            "id": "Promise<void>",
+            "name": "Promise<void>"
+          },
+          "path": "src/entrypoints/index.node.ts"
+        },
+        {
+          "category": "Capture",
+          "description": "Register options that every event sent by this client carries.",
+          "details": "Each event fills the options it left unset (missing or `null`) in this order: the event's own `options`, then context options, then these, then the options the SDK adds (such as `process_person_profile: false` for an event with no distinct id). `before_send` sees the result and can change it. Values are sent to capture unchanged. Capture drops an event whose option value it cannot read, so a bad value registered here drops every event. An option beats its legacy property, such as `$process_person_profile`, wherever either one was set.",
+          "id": "registerOptions",
+          "showDocs": true,
+          "title": "registerOptions",
+          "examples": [
+            {
+              "id": "",
+              "name": "",
+              "code": "\n\nclient.registerOptions({ cookieless_mode: true })\n\n\n\n"
+            }
+          ],
+          "releaseTag": "public",
+          "params": [
+            {
+              "description": "The options to add to every event",
+              "isOptional": false,
+              "type": "Record<string, JsonType>",
+              "name": "options"
+            }
+          ],
+          "returnType": {
+            "id": "void",
+            "name": "void"
+          },
+          "path": "src/entrypoints/index.node.ts"
+        },
         {
           "category": "Feature flags",
           "description": "Reload feature flag definitions from the configured cache provider or PostHog for local evaluation.",
@@ -1395,6 +1453,64 @@
           },
           "path": "src/entrypoints/index.node.ts"
         },
+        {
+          "category": "Capture",
+          "description": "Remove a property added with `register()`.",
+          "details": null,
+          "id": "unregister",
+          "showDocs": true,
+          "title": "unregister",
+          "examples": [
+            {
+              "id": "unregister",
+              "name": "Generated example for unregister",
+              "code": "// Generated example for unregister\nposthog.unregister();"
+            }
+          ],
+          "releaseTag": "public",
+          "params": [
+            {
+              "description": "The property name to remove",
+              "isOptional": false,
+              "type": "string",
+              "name": "property"
+            }
+          ],
+          "returnType": {
+            "id": "Promise<void>",
+            "name": "Promise<void>"
+          },
+          "path": "src/entrypoints/index.node.ts"
+        },
+        {
+          "category": "Capture",
+          "description": "Remove an option added with `registerOptions()`.",
+          "details": null,
+          "id": "unregisterOptions",
+          "showDocs": true,
+          "title": "unregisterOptions",
+          "examples": [
+            {
+              "id": "unregisteroptions",
+              "name": "Generated example for unregisterOptions",
+              "code": "// Generated example for unregisterOptions\nposthog.unregisterOptions();"
+            }
+          ],
+          "releaseTag": "public",
+          "params": [
+            {
+              "description": "The option name to remove",
+              "isOptional": false,
+              "type": "string",
+              "name": "key"
+            }
+          ],
+          "returnType": {
+            "id": "void",
+            "name": "void"
+          },
+          "path": "src/entrypoints/index.node.ts"
+        },
         {
           "category": "Identification",
           "description": "Remove properties from a person profile.",
@@ -1467,7 +1583,7 @@
         {
           "category": "Context",
           "description": "Run a function with specific context that will be applied to all events captured within that context. It propagates the context to all subsequent calls down the call stack. Context properties like tags and sessionId will be automatically attached to all events. By default, nested contexts inherit from parent contexts. Use `{ fresh: true }` to start with a clean context.",
-          "details": null,
+          "details": "Context `properties` and `options` fill only what an event left unset: the event's own values win, and context values beat `register()` and `registerOptions()` values and the values the SDK adds. `before_send` sees the result and can change it.",
           "id": "withContext",
           "showDocs": true,
           "title": "withContext",
@@ -1481,7 +1597,7 @@
           "releaseTag": "public",
           "params": [
             {
-              "description": "Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)",
+              "description": "Context data to apply (sessionId, distinctId, properties, options)",
               "isOptional": false,
               "type": "Partial<ContextData>",
               "name": "data"
@@ -1672,34 +1788,6 @@
           },
           "path": "src/entrypoints/index.node.ts"
         },
-        {
-          "category": "",
-          "details": null,
-          "id": "register",
-          "showDocs": true,
-          "title": "register",
-          "examples": [
-            {
-              "id": "register",
-              "name": "Generated example for register",
-              "code": "// Generated example for register\nposthog.register();"
-            }
-          ],
-          "releaseTag": "public",
-          "params": [
-            {
-              "description": "",
-              "isOptional": false,
-              "type": "PostHogEventProperties",
-              "name": "properties"
-            }
-          ],
-          "returnType": {
-            "id": "Promise<void>",
-            "name": "Promise<void>"
-          },
-          "path": "src/entrypoints/index.node.ts"
-        },
         {
           "category": "Initialization",
           "description": "Shuts down the PostHog instance and ensures all events are sent.\nCall shutdown() once before the process exits to ensure that all events have been sent and all promises have resolved. Do not use this function if you intend to keep using this PostHog instance after calling it. Use flush() for per-request cleanup instead.",
@@ -1728,34 +1816,6 @@
             "name": "Promise<void>"
           },
           "path": "src/entrypoints/index.node.ts"
-        },
-        {
-          "category": "",
-          "details": null,
-          "id": "unregister",
-          "showDocs": true,
-          "title": "unregister",
-          "examples": [
-            {
-              "id": "unregister",
-              "name": "Generated example for unregister",
-              "code": "// Generated example for unregister\nposthog.unregister();"
-            }
-          ],
-          "releaseTag": "public",
-          "params": [
-            {
-              "description": "",
-              "isOptional": false,
-              "type": "string",
-              "name": "property"
-            }
-          ],
-          "returnType": {
-            "id": "Promise<void>",
-            "name": "Promise<void>"
-          },
-          "path": "src/entrypoints/index.node.ts"
         }
       ]
     }
@@ -2154,6 +2214,12 @@
           "name": "distinctId"
         },
         {
+          "description": "Options that fill the options an event left unset (missing or `null`). The event's own options win; these beat options from `registerOptions()`.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
+        },
+        {
+          "description": "Properties that fill the keys an event left unset. The event's own values win.",
           "type": "Record<string, any>",
           "name": "properties"
         },
@@ -2274,6 +2340,7 @@
           "name": "options"
         },
         {
+          "description": "The event's distinct id. When it is missing, empty or only whitespace, the context distinct id\nis used; without one, the event gets a generated id and `options.process_person_profile: false`.",
           "type": "string",
           "name": "distinctId"
         },
@@ -2713,6 +2780,7 @@
           "name": "properties"
         },
         {
+          "description": "The event's distinct id. When it is missing, empty or only whitespace, the context distinct id\nis used, then `$<groupType>_<groupKey>`.",
           "type": "string",
           "name": "distinctId"
         },
@@ -3652,11 +3720,6 @@
       "id": "PostHogOptions",
       "name": "PostHogOptions",
       "properties": [
-        {
-          "description": "Whether to disable GeoIP lookups",
-          "type": "boolean",
-          "name": "disableGeoip"
-        },
         {
           "description": "PostHog API host, usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'",
           "type": "string",
@@ -3768,6 +3831,11 @@
           "type": "\"memory\"",
           "name": "persistence"
         },
+        {
+          "description": "Whether to disable GeoIP lookups for events and feature flag requests. When on, every event\ngets `$geoip_disable: true` unless the event, its context or `register()` sets\n`$geoip_disable`. A per-call `disableGeoip` argument sets it for that event, under the event's\nown `$geoip_disable` property.",
+          "type": "boolean",
+          "name": "disableGeoip"
+        },
         {
           "description": "The interval in milliseconds between periodic flushes",
           "type": "number",
diff --git a/packages/node/src/__tests__/capture-v1/layers.spec.ts b/packages/node/src/__tests__/capture-v1/layers.spec.ts
new file mode 100644
index 0000000000..3392ff6a15
--- /dev/null
+++ b/packages/node/src/__tests__/capture-v1/layers.spec.ts
@@ -0,0 +1,712 @@
+import type { JsonType } from '@posthog/core'
+
+import { EventMessage, PostHog, PostHogOptions } from '@/entrypoints/index.node'
+import { FeatureFlagEvaluations } from '@/feature-flag-evaluations'
+import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, apiImplementationV4, captureEvents } from '../utils'
+import { V1WiringHarness } from '../utils/v1-wiring'
+
+const { TRACE_ID, SPAN_ID } = vi.hoisted(() => ({
+  TRACE_ID: '0af7651916cd43dd8448eb211c80319c',
+  SPAN_ID: 'b7ad6b7169203331',
+}))
+
+vi.mock('@/extensions/error-tracking/trace-context', () => ({
+  getActiveTraceProperties: async () => ({ $trace_id: TRACE_ID, $span_id: SPAN_ID }),
+}))
+
+type Layers = {
+  event?: Record<string, JsonType>
+  context?: Record<string, JsonType>
+  global?: Record<string, JsonType>
+}
+
+type Source = keyof Layers
+
+const SOURCES: Source[] = ['event', 'context', 'global']
+
+const UUID_V7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/
+
+/** What `before_send` received, copied so later changes cannot alter it. */
+type HookView = { event: string; properties: Record<string, any>; options?: Record<string, JsonType> }
+
+/** A `flags` snapshot with one enabled flag `x` set to variant `v`, built without a network call. */
+const flagSnapshot = (): FeatureFlagEvaluations =>
+  new FeatureFlagEvaluations({
+    host: { captureFlagCalledEventIfNeeded: () => {}, logWarning: () => {} },
+    distinctId: 'u',
+    flags: {
+      x: {
+        key: 'x',
+        enabled: true,
+        variant: 'v',
+        payload: undefined,
+        id: 1,
+        version: 1,
+        reason: undefined,
+        locallyEvaluated: true,
+        hasExperiment: undefined,
+      },
+    },
+  })
+
+describe('layered event values', () => {
+  vi.useFakeTimers()
+
+  const harness = new V1WiringHarness()
+  const wireEvents = (path: string = ANALYTICS_CAPTURE_PATH): any[] => captureEvents(harness.fetch, path)
+
+  beforeEach(() => {
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    harness.useDefaultRouting()
+  })
+
+  afterEach(async () => {
+    await harness.cleanup()
+    vi.clearAllMocks()
+  })
+
+  /** Sends what `send` captures on a new client and returns the one wire event it produced. */
+  const sendOne = async (
+    send: (client: PostHog) => unknown,
+    clientOptions?: PostHogOptions,
+    path: string = ANALYTICS_CAPTURE_PATH
+  ): Promise<any> => {
+    const client = harness.makeClient(clientOptions)
+    await send(client)
+    await client.flush()
+    const events = wireEvents(path)
+    expect(events).toHaveLength(1)
+    return events[0]
+  }
+
+  /** Captures one event with options from the event, a context and `registerOptions()`. */
+  const captureWithOptionLayers = (layers: Layers, message: Partial<EventMessage> = {}) =>
+    sendOne((client) => {
+      if (layers.global) {
+        client.registerOptions(layers.global)
+      }
+      const capture = (): void =>
+        client.capture({ distinctId: 'u', event: 'e', ...message, options: layers.event ?? message.options })
+      return layers.context ? client.withContext({ options: layers.context }, capture) : capture()
+    })
+
+  /**
+   * Sends one event whose properties come from the event, a context and `register()`, and returns
+   * the wire event plus what `before_send` saw.
+   */
+  const sendWithPropertyLayers = async (
+    layers: Layers,
+    message: Partial<EventMessage> = {},
+    clientOptions: PostHogOptions = {}
+  ): Promise<{ event: any; hookSaw: HookView }> => {
+    const seen: HookView[] = []
+    const event = await sendOne(
+      async (client) => {
+        if (layers.global) {
+          await client.register(layers.global)
+        }
+        const capture = (): void =>
+          client.capture({ distinctId: 'u', event: 'e', ...message, properties: layers.event ?? message.properties })
+        return layers.context ? client.withContext({ properties: layers.context }, capture) : capture()
+      },
+      {
+        ...clientOptions,
+        before_send: (hookEvent) => {
+          seen.push(
+            structuredClone({
+              event: hookEvent!.event,
+              properties: hookEvent!.properties!,
+              options: hookEvent!.options,
+            })
+          )
+          return hookEvent
+        },
+      }
+    )
+    expect(seen).toHaveLength(1)
+    return { event, hookSaw: seen[0] }
+  }
+
+  describe('properties', () => {
+    it.each<[string, Layers, JsonType]>([
+      [
+        'the event beats context and global',
+        { event: { k: 'event' }, context: { k: 'context' }, global: { k: 'global' } },
+        'event',
+      ],
+      ['context beats global', { context: { k: 'context' }, global: { k: 'global' } }, 'context'],
+      ['global fills alone', { global: { k: 'global' } }, 'global'],
+      [
+        'undefined on the event counts as unset',
+        { event: { k: undefined as any }, context: { k: 'context' } },
+        'context',
+      ],
+      ['null on the event blocks the fill', { event: { k: null }, context: { k: 'context' } }, null],
+      ['null in context blocks the global fill', { context: { k: null }, global: { k: 'global' } }, null],
+    ])('%s', async (_label, layers, expected) => {
+      const { event, hookSaw } = await sendWithPropertyLayers(layers)
+
+      expect(event.properties.k).toStrictEqual(expected)
+      expect(hookSaw.properties.k).toStrictEqual(expected)
+    })
+
+    describe('nested fill', () => {
+      it.each(['$set', '$set_once', '$groups', '$group_set'])('%s fills inner keys one level deep', async (key) => {
+        const { event } = await sendWithPropertyLayers({
+          event: { [key]: { a: 'event', u: undefined as any } },
+          context: { [key]: { a: 'context', b: 'context', u: 'context' } },
+          global: { [key]: { b: 'global', c: 'global' } },
+        })
+
+        expect(event.properties[key]).toStrictEqual({ a: 'event', b: 'context', c: 'global', u: 'context' })
+      })
+
+      it.each<[string, Layers, JsonType]>([
+        ['an event $set that is not an object wins whole', { event: { $set: 'x' }, context: { $set: { a: 1 } } }, 'x'],
+        ['$unset uses the top-level rule', { event: { $unset: ['a'] }, context: { $unset: ['b'] } }, ['a']],
+        [
+          'any other object uses the top-level rule',
+          { event: { meta: { a: 1 } }, context: { meta: { b: 2 } } },
+          { a: 1 },
+        ],
+      ])('%s', async (_label, layers, expected) => {
+        const key = Object.keys(layers.event!)[0]
+        const { event } = await sendWithPropertyLayers(layers)
+
+        expect(event.properties[key]).toStrictEqual(expected)
+      })
+
+      it('a filled default never changes the registered object', async () => {
+        const registered = { a: 'global' }
+        await sendWithPropertyLayers({ event: { $set: { b: 'event' } }, global: { $set: registered } })
+
+        expect(registered).toStrictEqual({ a: 'global' })
+      })
+    })
+
+    it('typed groups merge over a $groups property key by key, then context fills', async () => {
+      const { event, hookSaw } = await sendWithPropertyLayers(
+        { event: { $groups: { company: 'property', org: 'property' } }, context: { $groups: { project: 'context' } } },
+        { groups: { company: 'typed' } }
+      )
+
+      const expected = { company: 'typed', org: 'property', project: 'context' }
+      expect(event.properties.$groups).toStrictEqual(expected)
+      expect(hookSaw.properties.$groups).toStrictEqual(expected)
+    })
+
+    describe('SDK values', () => {
+      it('fill $is_server and $geoip_disable when no layer sets them, before before_send', async () => {
+        const { event, hookSaw } = await sendWithPropertyLayers({})
+
+        expect(event.properties).toStrictEqual({ $is_server: true, $geoip_disable: true })
+        expect(hookSaw.properties).toStrictEqual({ $is_server: true, $geoip_disable: true })
+      })
+
+      it.each<[string, PostHogOptions, string]>([
+        ['isServer: false', { isServer: false }, '$is_server'],
+        ['disableGeoip: false', { disableGeoip: false }, '$geoip_disable'],
+      ])('%s leaves the value out', async (_label, clientOptions, key) => {
+        const { event, hookSaw } = await sendWithPropertyLayers({}, {}, clientOptions)
+
+        expect(event.properties).not.toHaveProperty(key)
+        expect(hookSaw.properties).not.toHaveProperty(key)
+      })
+
+      const userValueCases = ['$is_server', '$geoip_disable'].flatMap((key) =>
+        SOURCES.map((source): [string, Source] => [key, source])
+      )
+      it.each(userValueCases)('%s set in the %s layer beats the SDK value', async (key, source) => {
+        const { event, hookSaw } = await sendWithPropertyLayers({ [source]: { [key]: false } })
+
+        expect(event.properties[key]).toBe(false)
+        expect(hookSaw.properties[key]).toBe(false)
+      })
+
+      it.each<[string, Layers, boolean]>([
+        ['beats context and global', { context: { $geoip_disable: false }, global: { $geoip_disable: false } }, true],
+        ["loses to the event's own property", { event: { $geoip_disable: false } }, false],
+      ])('a per-call disableGeoip %s', async (_label, layers, expected) => {
+        const { event } = await sendWithPropertyLayers(layers, { disableGeoip: true }, { disableGeoip: false })
+
+        expect(event.properties.$geoip_disable).toBe(expected)
+      })
+
+      describe('feature flag properties from a flags snapshot', () => {
+        it('fill before before_send', async () => {
+          const { event, hookSaw } = await sendWithPropertyLayers({}, { flags: flagSnapshot() })
+
+          for (const properties of [event.properties, hookSaw.properties]) {
+            expect(properties['$feature/x']).toBe('v')
+            expect(properties.$active_feature_flags).toStrictEqual(['x'])
+          }
+        })
+
+        it.each(SOURCES)('lose to the %s layer', async (source) => {
+          const userValues = { '$feature/x': 'mine', $active_feature_flags: ['mine'] }
+          const { event, hookSaw } = await sendWithPropertyLayers({ [source]: userValues }, { flags: flagSnapshot() })
+
+          expect(event.properties).toMatchObject(userValues)
+          expect(hookSaw.properties).toMatchObject(userValues)
+        })
+      })
+
+      describe('trace ids on $exception', () => {
+        it('fill as a pair before before_send', async () => {
+          const { event, hookSaw } = await sendWithPropertyLayers({}, { event: '$exception' })
+
+          for (const properties of [event.properties, hookSaw.properties]) {
+            expect(properties).toMatchObject({ $trace_id: TRACE_ID, $span_id: SPAN_ID })
+          }
+        })
+
+        const pairCases = ['$trace_id', '$span_id'].flatMap((key) =>
+          SOURCES.map((source): [string, Source] => [key, source])
+        )
+        it.each(pairCases)('a %s in the %s layer stops both', async (key, source) => {
+          const { event } = await sendWithPropertyLayers({ [source]: { [key]: 'mine' } }, { event: '$exception' })
+
+          const otherKey = key === '$trace_id' ? '$span_id' : '$trace_id'
+          expect(event.properties[key]).toBe('mine')
+          expect(event.properties).not.toHaveProperty(otherKey)
+        })
+
+        it('are not added to other events', async () => {
+          const { event } = await sendWithPropertyLayers({})
+
+          expect(event.properties).not.toHaveProperty('$trace_id')
+        })
+      })
+
+      describe('$release_id on $exception', () => {
+        beforeEach(() => {
+          vi.stubEnv('POSTHOG_RELEASE_ID', 'injected-release')
+        })
+
+        afterEach(() => {
+          vi.unstubAllEnvs()
+        })
+
+        it('fills before before_send', async () => {
+          const { event, hookSaw } = await sendWithPropertyLayers({}, { event: '$exception' })
+
+          expect(event.properties.$release_id).toBe('injected-release')
+          expect(hookSaw.properties.$release_id).toBe('injected-release')
+        })
+
+        it.each(SOURCES)('loses to the %s layer', async (source) => {
+          const { event } = await sendWithPropertyLayers({ [source]: { $release_id: 'mine' } }, { event: '$exception' })
+
+          expect(event.properties.$release_id).toBe('mine')
+        })
+
+        it('loses to captureException properties', async () => {
+          const event = await sendOne((client) =>
+            client.captureException(new Error('boom'), 'u', { $release_id: 'mine' })
+          )
+
+          expect(event.properties.$release_id).toBe('mine')
+        })
+      })
+    })
+
+    it('before_send sees the $bot_pageview rename and has the final say', async () => {
+      const seen: HookView[] = []
+      const event = await sendOne(
+        (client) =>
+          client.capture({
+            distinctId: 'u',
+            event: '$pageview',
+            properties: { $raw_user_agent: 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)' },
+          }),
+        {
+          __preview_capture_bot_pageviews: true,
+          before_send: (hookEvent) => {
+            seen.push(structuredClone({ event: hookEvent!.event, properties: hookEvent!.properties! }))
+            delete hookEvent!.properties!.$browser_type
+            return hookEvent
+          },
+        }
+      )
+
+      expect(seen[0].event).toBe('$bot_pageview')
+      expect(seen[0].properties.$browser_type).toBe('bot')
+      expect(event.event).toBe('$bot_pageview')
+      expect(event.properties).not.toHaveProperty('$browser_type')
+    })
+
+    it('before_send can remove every SDK value and nothing re-adds it', async () => {
+      const event = await sendOne(
+        (client) => client.capture({ distinctId: 'u', event: '$exception', flags: flagSnapshot() }),
+        {
+          before_send: (hookEvent) => {
+            hookEvent!.properties = {}
+            hookEvent!.options = {}
+            return hookEvent
+          },
+        }
+      )
+
+      expect(event.properties).toStrictEqual({})
+      expect(event.options).toStrictEqual({})
+    })
+
+    it('a minimal $feature_flag_called event keeps the properties that set options and session fields', async () => {
+      harness.fetch.mockImplementation(
+        apiImplementationV4({
+          flags: {
+            'test-flag': {
+              key: 'test-flag',
+              enabled: true,
+              variant: undefined,
+              reason: { code: 'condition_match', condition_index: 0, description: 'Matched' },
+              metadata: { id: 1, version: 1, payload: undefined, has_experiment: false },
+            },
+          },
+          errorsWhileComputingFlags: false,
+          minimalFlagCalledEvents: true,
+        } as any)
+      )
+      const event = await sendOne(async (client) => {
+        await client.register({
+          $cookieless_mode: true,
+          $ignore_sent_at: true,
+          $product_tour_id: 'tour',
+          $process_person_profile: false,
+          $window_id: 'window',
+          dropped: 'yes',
+        })
+        client.registerOptions({ future_option: 1 })
+        await client.withContext({ sessionId: 'session' }, () => client.getFeatureFlag('test-flag', 'u'))
+      })
+
+      expect(event.event).toBe('$feature_flag_called')
+      expect(event.options).toStrictEqual({
+        cookieless_mode: true,
+        disable_skew_correction: true,
+        product_tour_id: 'tour',
+        process_person_profile: false,
+        future_option: 1,
+      })
+      expect(event.session_id).toBe('session')
+      expect(event.window_id).toBe('window')
+      expect(event.properties).not.toHaveProperty('dropped')
+    })
+  })
+
+  describe('options', () => {
+    it.each<[string, Layers, JsonType]>([
+      [
+        'the event beats context and global',
+        { event: { k: 'event' }, context: { k: 'context' }, global: { k: 'global' } },
+        'event',
+      ],
+      ['context beats global', { context: { k: 'context' }, global: { k: 'global' } }, 'context'],
+      ['global fills alone', { global: { k: 'global' } }, 'global'],
+      ['a null event option is filled', { event: { k: null }, context: { k: 'context' } }, 'context'],
+      ['a null context option is filled', { context: { k: null }, global: { k: 'global' } }, 'global'],
+      ['a null option with nothing below stays null', { event: { k: null } }, null],
+    ])('%s', async (_label, layers, expected) => {
+      const event = await captureWithOptionLayers(layers)
+
+      expect(event.options).toStrictEqual({ k: expected })
+    })
+
+    it.each<[string, Layers, JsonType]>([
+      ['the personless option fills last', {}, false],
+      ['a context option beats the personless option', { context: { process_person_profile: true } }, true],
+      ['a global option beats the personless option', { global: { process_person_profile: true } }, true],
+    ])('%s', async (_label, layers, expected) => {
+      const event = await captureWithOptionLayers(layers, { distinctId: undefined })
+
+      expect(event.options.process_person_profile).toBe(expected)
+    })
+
+    it('a global option beats a legacy property on the event', async () => {
+      const event = await captureWithOptionLayers(
+        { global: { cookieless_mode: true } },
+        { properties: { $cookieless_mode: false } }
+      )
+
+      expect(event.options).toStrictEqual({ cookieless_mode: true })
+      expect(event.properties).not.toHaveProperty('$cookieless_mode')
+    })
+
+    it('before_send sees the filled options and can remove one', async () => {
+      const seen: EventMessage[] = []
+      const event = await sendOne(
+        (client) => {
+          client.registerOptions({ cookieless_mode: true, product_tour_id: 'tour' })
+          client.capture({ distinctId: 'u', event: 'e' })
+        },
+        {
+          before_send: (message) => {
+            seen.push(structuredClone(message))
+            delete message!.options!.product_tour_id
+            return message
+          },
+        }
+      )
+
+      expect(seen[0].options).toStrictEqual({ cookieless_mode: true, product_tour_id: 'tour' })
+      expect(event.options).toStrictEqual({ cookieless_mode: true })
+    })
+
+    describe('registerOptions', () => {
+      it('merges calls, and unregisterOptions removes one key', async () => {
+        const event = await sendOne((client) => {
+          client.registerOptions({ a: 1, b: 2 })
+          client.registerOptions({ b: 3, c: 4 })
+          client.unregisterOptions('a')
+          client.capture({ distinctId: 'u', event: 'e' })
+        })
+
+        expect(event.options).toStrictEqual({ b: 3, c: 4 })
+      })
+
+      it('an event keeps the options it read when it was captured', async () => {
+        const event = await sendOne((client) => {
+          client.registerOptions({ a: 1 })
+          client.capture({ distinctId: 'u', event: 'e' })
+          client.registerOptions({ a: 2 })
+          client.unregisterOptions('a')
+        })
+
+        expect(event.options).toStrictEqual({ a: 1 })
+      })
+
+      it.each<[string, unknown]>([
+        ['an array', ['a']],
+        ['a string', 'a'],
+        ['a number', 1],
+        ['null', null],
+      ])('logs one error for %s and ignores it', async (_label, value) => {
+        const event = await sendOne((client) => {
+          client.registerOptions({ kept: true })
+          client.registerOptions(value as Record<string, JsonType>)
+          client.capture({ distinctId: 'u', event: 'e' })
+        })
+
+        expect(event.options).toStrictEqual({ kept: true })
+        expect(console.error).toHaveBeenCalledTimes(1)
+        expect(console.error).toHaveBeenCalledWith('[PostHog] registerOptions takes an object; ignoring the value')
+      })
+    })
+
+    describe('context options', () => {
+      it.each<[string, boolean, Record<string, JsonType>]>([
+        ['a nested context inherits and overrides its parent', false, { a: 'outer', b: 'inner', c: 'inner' }],
+        ['a fresh context drops its parent', true, { b: 'inner', c: 'inner' }],
+      ])('%s', async (_label, fresh, expected) => {
+        const event = await sendOne((client) =>
+          client.withContext({ options: { a: 'outer', b: 'outer' } }, () =>
+            client.withContext(
+              { options: { b: 'inner', c: 'inner' } },
+              () => client.capture({ distinctId: 'u', event: 'e' }),
+              { fresh }
+            )
+          )
+        )
+
+        expect(event.options).toStrictEqual(expected)
+      })
+
+      it('enterContext sets options', async () => {
+        const event = await sendOne((client) =>
+          client.withContext({}, () => {
+            client.enterContext({ options: { a: 1 } })
+            client.capture({ distinctId: 'u', event: 'e' })
+          })
+        )
+
+        expect(event.options).toStrictEqual({ a: 1 })
+      })
+    })
+  })
+
+  describe('identity', () => {
+    /** Sends one event from `send`, inside a context when `context` is given. */
+    const sendInContext = (
+      send: (client: PostHog) => unknown,
+      context?: { distinctId?: string; sessionId?: string; properties?: Record<string, JsonType> }
+    ): Promise<any> => sendOne((client) => (context ? client.withContext(context, () => send(client)) : send(client)))
+
+    const BLANK_IDS: [string, string | undefined][] = [
+      ['missing', undefined],
+      ['empty', ''],
+      ['whitespace', ' \t '],
+    ]
+
+    it.each(BLANK_IDS)('a %s distinct id takes the context id', async (_label, distinctId) => {
+      const event = await sendInContext((client) => client.capture({ distinctId, event: 'e' }), { distinctId: 'ctx' })
+
+      expect(event.distinct_id).toBe('ctx')
+      expect(event.options).toStrictEqual({})
+    })
+
+    it.each(BLANK_IDS)('a %s distinct id with no context id becomes a personless v7 id', async (_label, distinctId) => {
+      const event = await sendInContext((client) => client.capture({ distinctId, event: 'e' }), { distinctId: '  ' })
+
+      expect(event.distinct_id).toMatch(UUID_V7)
+      expect(event.options).toStrictEqual({ process_person_profile: false })
+    })
+
+    it("the caller's process_person_profile beats the personless option", async () => {
+      const event = await sendInContext((client) =>
+        client.capture({ event: 'e', options: { process_person_profile: true } })
+      )
+
+      expect(event.distinct_id).toMatch(UUID_V7)
+      expect(event.options).toStrictEqual({ process_person_profile: true })
+    })
+
+    it.each<[string, Record<string, JsonType>, string | undefined]>([
+      ['fills an unset $session_id', {}, 'ctx-session'],
+      ["loses to the event's own $session_id", { $session_id: 'event-session' }, 'event-session'],
+      ['loses to a null $session_id', { $session_id: null }, undefined],
+    ])('the context session %s', async (_label, properties, expected) => {
+      const event = await sendInContext((client) => client.capture({ distinctId: 'u', event: 'e', properties }), {
+        sessionId: 'ctx-session',
+      })
+
+      expect(event.session_id).toBe(expected)
+    })
+
+    describe('groupIdentify', () => {
+      it.each<[string, string | undefined, string | undefined, string]>([
+        ["uses the caller's id", 'caller', 'ctx', 'caller'],
+        ['uses the context id when the caller gives a blank one', '  ', 'ctx', 'ctx'],
+        ['falls back to $<type>_<key>', undefined, undefined, '$company_acme'],
+      ])('%s', async (_label, distinctId, contextId, expected) => {
+        const event = await sendInContext(
+          (client) => client.groupIdentify({ groupType: 'company', groupKey: 'acme', distinctId }),
+          { distinctId: contextId, sessionId: 'ctx-session' }
+        )
+
+        expect(event.distinct_id).toBe(expected)
+        expect(event.options).toStrictEqual({})
+        expect(event).not.toHaveProperty('session_id')
+      })
+    })
+
+    describe('alias', () => {
+      it('never takes its target from context or register()', async () => {
+        const event = await sendOne(async (client) => {
+          await client.register({ alias: 'global-target' })
+          client.withContext({ properties: { alias: 'context-target' } }, () =>
+            client.alias({ distinctId: 'u', alias: undefined as unknown as string })
+          )
+        })
+
+        expect(event.properties).not.toHaveProperty('alias')
+      })
+
+      it('takes its own distinct id from context and reports it in properties', async () => {
+        const event = await sendInContext((client) => client.alias({ distinctId: '', alias: 'anon' }), {
+          distinctId: 'ctx',
+          sessionId: 'ctx-session',
+        })
+
+        expect(event.distinct_id).toBe('ctx')
+        expect(event.properties).toMatchObject({ distinct_id: 'ctx', alias: 'anon' })
+        expect(event.session_id).toBe('ctx-session')
+      })
+    })
+
+    describe('identify', () => {
+      it('puts context properties in the event properties, not in $set, and sends no empty $set_once', async () => {
+        const event = await sendInContext(
+          (client) => client.identify({ distinctId: 'u', properties: { plan: 'pro' } }),
+          { properties: { region: 'eu' } }
+        )
+
+        expect(event.properties.$set).toStrictEqual({ plan: 'pro' })
+        expect(event.properties.region).toBe('eu')
+        expect(event.properties).not.toHaveProperty('$set_once')
+      })
+
+      it('sends only $set and $set_once when the caller gives $set', async () => {
+        const event = await sendInContext((client) =>
+          client.identify({ distinctId: 'u', properties: { $set: { a: 1 }, $set_once: { b: 2 }, other: 3 } })
+        )
+
+        expect(event.properties).toMatchObject({ $set: { a: 1 }, $set_once: { b: 2 } })
+        expect(event.properties).not.toHaveProperty('other')
+      })
+    })
+  })
+
+  describe('layers reach every message type', () => {
+    it.each<[string, (client: PostHog) => unknown, string]>([
+      ['capture', (c) => c.capture({ distinctId: 'u', event: 'e' }), ANALYTICS_CAPTURE_PATH],
+      ['captureAi', (c) => c.captureAi({ distinctId: 'u', event: '$ai_span' }), AI_CAPTURE_PATH],
+      ['captureException', (c) => c.captureException(new Error('boom'), 'u'), ANALYTICS_CAPTURE_PATH],
+      ['identify', (c) => c.identify({ distinctId: 'u', properties: { a: 1 } }), ANALYTICS_CAPTURE_PATH],
+      ['identifyImmediate', (c) => c.identifyImmediate({ distinctId: 'u' }), ANALYTICS_CAPTURE_PATH],
+      ['alias', (c) => c.alias({ distinctId: 'u', alias: 'anon' }), ANALYTICS_CAPTURE_PATH],
+      ['aliasImmediate', (c) => c.aliasImmediate({ distinctId: 'u', alias: 'anon' }), ANALYTICS_CAPTURE_PATH],
+      ['groupIdentify', (c) => c.groupIdentify({ groupType: 'company', groupKey: 'acme' }), ANALYTICS_CAPTURE_PATH],
+      [
+        'setPersonProperties',
+        (c) => c.setPersonProperties({ distinctId: 'u', properties: { a: 1 } }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+      [
+        'unsetPersonProperties',
+        (c) => c.unsetPersonProperties({ distinctId: 'u', properties: ['a'] }),
+        ANALYTICS_CAPTURE_PATH,
+      ],
+    ])('%s', async (_method, send, path) => {
+      const event = await sendOne(
+        async (client) => {
+          await client.register({ global_prop: 'g' })
+          client.registerOptions({ global_option: 'g' })
+          return client.withContext({ properties: { context_prop: 'c' }, options: { context_option: 'c' } }, () =>
+            send(client)
+          )
+        },
+        undefined,
+        path
+      )
+
+      expect(event.properties).toMatchObject({ global_prop: 'g', context_prop: 'c', $is_server: true })
+      expect(event.options).toMatchObject({ global_option: 'g', context_option: 'c' })
+    })
+  })
+
+  describe('captureException properties', () => {
+    it.each([
+      '$exception_source',
+      '$debug_images',
+      '$exception_types',
+      '$exception_values',
+      '$exception_sources',
+      '$exception_functions',
+      '$exception_fingerprint_version',
+      '$exception_fingerprint_record',
+      '$exception_issue_id',
+      '$exception_release',
+      '$cymbal_errors',
+    ])('cannot set %s', async (key) => {
+      const event = await sendOne((client) => client.captureException(new Error('boom'), 'u', { [key]: 'caller' }))
+
+      expect(event.properties).not.toHaveProperty(key)
+    })
+
+    it('cannot replace $exception_list or $exception_level, and keep other properties', async () => {
+      const event = await sendOne((client) =>
+        client.captureException(new Error('boom'), 'u', {
+          $exception_list: 'caller',
+          $exception_level: 'fatal',
+          $exception_fingerprint: 'custom',
+          custom: 1,
+        })
+      )
+
+      expect(event.properties.$exception_list[0]).toMatchObject({ type: 'Error', value: 'boom' })
+      expect(event.properties.$exception_level).toBe('error')
+      expect(event.properties).toMatchObject({ $exception_fingerprint: 'custom', custom: 1 })
+    })
+  })
+})
diff --git a/packages/node/src/__tests__/evaluate-flags.spec.ts b/packages/node/src/__tests__/evaluate-flags.spec.ts
index b2bce426dd..45869b9247 100644
--- a/packages/node/src/__tests__/evaluate-flags.spec.ts
+++ b/packages/node/src/__tests__/evaluate-flags.spec.ts
@@ -573,8 +573,6 @@ describe('evaluateFlags', () => {
           '$feature_flag_request_id',
           '$feature_flag_evaluated_at',
           'locally_evaluated',
-          '$lib',
-          '$lib_version',
           '$is_server',
           '$geoip_disable',
         ].sort()
diff --git a/packages/node/src/__tests__/feature-flags.flags.spec.ts b/packages/node/src/__tests__/feature-flags.flags.spec.ts
index 2dbb446455..9a898c1de8 100644
--- a/packages/node/src/__tests__/feature-flags.flags.spec.ts
+++ b/packages/node/src/__tests__/feature-flags.flags.spec.ts
@@ -47,8 +47,6 @@ describe('flags v2', () => {
           $feature_flag_response: undefined,
           $feature_flag_request_id: '0152a345-295f-4fba-adac-2e6ea9c91082',
           $feature_flag_evaluated_at: expect.any(Number),
-          $lib: posthog.getLibraryId(),
-          $lib_version: posthog.getLibraryVersion(),
           locally_evaluated: false,
         },
       })
@@ -163,8 +161,6 @@ describe('flags v2', () => {
             $feature_flag_reason: expectedReason,
             $feature_flag_request_id: '0152a345-295f-4fba-adac-2e6ea9c91082',
             $feature_flag_evaluated_at: expect.any(Number),
-            $lib: posthog.getLibraryId(),
-            $lib_version: posthog.getLibraryVersion(),
             locally_evaluated: false,
           },
         })
@@ -346,8 +342,6 @@ describe('flags v1', () => {
           '$feature/non-existent-flag': undefined,
           $feature_flag: 'non-existent-flag',
           $feature_flag_response: undefined,
-          $lib: posthog.getLibraryId(),
-          $lib_version: posthog.getLibraryVersion(),
           locally_evaluated: false,
         },
       })
@@ -1376,8 +1370,6 @@ describe('minimal $feature_flag_called events', () => {
           '$feature_flag_evaluated_at',
           'locally_evaluated',
           '$groups',
-          '$lib',
-          '$lib_version',
           '$is_server',
           '$geoip_disable',
         ].sort()
@@ -1563,8 +1555,6 @@ describe('minimal $feature_flag_called events', () => {
           '$feature_flag_reason',
           '$feature_flag_evaluated_at',
           'locally_evaluated',
-          '$lib',
-          '$lib_version',
           '$is_server',
           '$geoip_disable',
         ].sort()
diff --git a/packages/node/src/__tests__/feature-flags.spec.ts b/packages/node/src/__tests__/feature-flags.spec.ts
index e7146a4cb4..05f1e3b622 100644
--- a/packages/node/src/__tests__/feature-flags.spec.ts
+++ b/packages/node/src/__tests__/feature-flags.spec.ts
@@ -3487,8 +3487,6 @@ describe('getFeatureFlag', () => {
           '$feature/complex-flag': true,
           $feature_flag: 'complex-flag',
           $feature_flag_response: true,
-          $lib: posthog.getLibraryId(),
-          $lib_version: posthog.getLibraryVersion(),
           locally_evaluated: true,
         },
       })
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index b7a4fa2085..36b310932a 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -500,6 +500,7 @@ describe('PostHog Node.js', () => {
         foo: 'bar',
         $lib: 'posthog-node',
         $lib_version: '1.2.3',
+        $geoip_disable: false,
         $is_server: true,
       })
     })
@@ -561,6 +562,7 @@ describe('PostHog Node.js', () => {
         foo: 'bar',
         $lib: 'posthog-node',
         $lib_version: '1.2.3',
+        $geoip_disable: false,
         $is_server: true,
       })
 
@@ -717,9 +719,10 @@ describe('PostHog Node.js', () => {
       expect(beforeSendFn).toHaveBeenCalledWith({
         distinctId: '123',
         event: 'test-event',
-        properties: { foo: 'bar' },
+        properties: { foo: 'bar', $geoip_disable: true, $is_server: true },
         options: {},
         groups: undefined,
+        flags: undefined,
         sendFeatureFlags: undefined,
         timestamp: undefined,
         disableGeoip: undefined,
@@ -996,6 +999,7 @@ describe('PostHog Node.js', () => {
           await waitForFlushTimer()
         },
         '$identify',
+        'session-123',
       ],
       [
         'groupIdentify',
@@ -1004,6 +1008,7 @@ describe('PostHog Node.js', () => {
           await waitForFlushTimer()
         },
         '$groupidentify',
+        undefined,
       ],
       [
         'alias',
@@ -1012,10 +1017,11 @@ describe('PostHog Node.js', () => {
           await waitForFlushTimer()
         },
         '$create_alias',
+        'session-123',
       ],
-    ] as Array<[string, (ph: PostHog) => Promise<void>, string]>)(
-      'should not add registered or context properties to %s',
-      async (_, send, expectedEvent) => {
+    ] as Array<[string, (ph: PostHog) => Promise<void>, string, string | undefined]>)(
+      'should add registered and context properties to %s',
+      async (_, send, expectedEvent, expectedSessionId) => {
         const ph = new PostHog('TEST_API_KEY', {
           host: 'http://example.com',
           fetchRetryCount: 0,
@@ -1030,9 +1036,11 @@ describe('PostHog Node.js', () => {
 
         const batchEvents = getLastBatchEvents()
         expect(batchEvents![0]).toMatchObject({ event: expectedEvent })
-        expect(batchEvents![0].properties).not.toHaveProperty('registered_prop')
-        expect(batchEvents![0].properties).not.toHaveProperty('context_prop')
-        expect(batchEvents![0].properties).not.toHaveProperty('$session_id')
+        expect(batchEvents![0].properties).toMatchObject({
+          registered_prop: 'registered_value',
+          context_prop: 'context_value',
+        })
+        expect(batchEvents![0].properties.$session_id).toBe(expectedSessionId)
       }
     )
 
@@ -1759,6 +1767,7 @@ describe('PostHog Node.js', () => {
         '$feature/feature-variant': 'variant',
         $lib: 'posthog-node',
         $lib_version: '1.2.3',
+        $geoip_disable: false,
         $is_server: true,
       })
 
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index bce9c6a3a1..e58e045529 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -2,6 +2,7 @@ import { version } from './version'
 
 import {
   allSettled,
+  ErrorTracking as CoreErrorTracking,
   FeatureFlagValue,
   isBlockedUA,
   isPlainObject,
@@ -78,6 +79,7 @@ import { type CaptureSettings, resolveCaptureSettings } from './capture-lane/set
 import { type CaptureCompressor, resolveCaptureCodec, webCompressor } from './capture-v1/compression'
 import { canonicalizeUuid } from './capture-v1/uuid'
 import { readEventOptions } from './capture-v1/transform'
+import { fillOptions, fillProperties, isUnsetProperty, snapshotLayer } from './event-defaults'
 import { AI_CAPTURE_ROUTE } from './ai-capture/routing'
 
 // Standard local evaluation rate limit is 600 per minute (10 per second),
@@ -134,6 +136,16 @@ function normalizeHost(value?: unknown): string {
   return normalizedValue || DEFAULT_NODE_HOST
 }
 
+/** Properties that set an option or a session field, kept on a minimal `$feature_flag_called` event. */
+const FLAG_CALLED_OPTION_SOURCE_PROPERTIES = [
+  '$cookieless_mode',
+  '$ignore_sent_at',
+  '$product_tour_id',
+  '$process_person_profile',
+  '$session_id',
+  '$window_id',
+]
+
 /**
  * A copy of the event for `before_send`, so a hook that mutates it cannot change the caller's
  * objects or the `register()` and context defaults. Plain objects and arrays are copied all the
@@ -180,6 +192,42 @@ function copyPlainValues(value: unknown, seen: WeakMap<object, unknown>): unknow
   return copy
 }
 
+/**
+ * The `$identify` properties: `$set` is the caller's `$set`, or every other property when there is
+ * none; `$set_once` only when the caller gave one.
+ */
+function identifyEventProperties(properties: Record<string | number, any>): PostHogEventProperties {
+  const { $set, $set_once, $anon_distinct_id, ...rest } = properties
+  return {
+    $set: $set || rest,
+    ...($set_once !== undefined && $set_once !== null ? { $set_once } : {}),
+    $anon_distinct_id: $anon_distinct_id ?? undefined,
+  }
+}
+
+/** How one message type resolves identity and which layers may set which keys. */
+type PrepareEventOptions = {
+  /** The distinct id when neither the call nor the context gives one; otherwise a personless id is generated. */
+  fallbackDistinctId?: string
+  /** Whether the context session id fills `$session_id`. */
+  contextSession?: boolean
+  /** Properties that only the call sets: no layer fills them. */
+  callOnlyProperties?: readonly string[]
+  /** Set the `distinct_id` property to the resolved distinct id. */
+  distinctIdProperty?: boolean
+}
+
+/** `alias` never takes its target from a context or default, and reports the resolved id. */
+const ALIAS_PREPARE_OPTIONS: PrepareEventOptions = { callOnlyProperties: ['alias'], distinctIdProperty: true }
+
+/** The id, or undefined when it is missing, empty or only whitespace. */
+function presentDistinctId(value: unknown): string | undefined {
+  if (value === undefined || value === null || (typeof value === 'string' && value.trim() === '')) {
+    return undefined
+  }
+  return value as string
+}
+
 function normalizeUnsetPersonProperties(value: string | string[]): string[] {
   const propertyNames = Array.isArray(value) ? value : [value]
   return propertyNames.filter(
@@ -229,6 +277,9 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   /** Whether PostHog AI integrations redact content: see `privacyMode` in `PostHogOptions`. */
   public readonly privacyMode: boolean
 
+  // Options from registerOptions(). Replaced, never mutated, so an event can keep the object it read.
+  private _globalOptions: Record<string, JsonType> = {}
+
   // Feature flag overrides for local testing/development
   private _flagOverrides?: Record<string, FeatureFlagValue>
   private _payloadOverrides?: Record<string, JsonType>
@@ -968,32 +1019,82 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   }
 
   /**
-   * Returns the common properties attached to every captured event.
-   *
-   * @remarks
-   * Extends the shared core properties (`$lib`, `$lib_version`) with
-   * `$is_server: true` so that events emitted from the server-side SDKs
-   * (posthog-node and posthog-edge, which both extend this class) are
-   * distinguishable from browser and react-native events. Browser and
-   * react-native clients do not extend `PostHogBackendClient`, so they
-   * never receive this property.
-   *
-   * This is controlled by the `isServer` option, which defaults to `true`.
-   * When `isServer` is `false` (e.g. when using the SDK as a client/CLI), the
-   * `$is_server` property is omitted entirely so the device OS is attributed
-   * normally.
-   *
-   * @returns The common event properties, including `$is_server: true` when
-   * the `isServer` option is enabled.
+   * The properties the SDK adds to an event: `$is_server` (unless the `isServer` option is
+   * `false`), `$geoip_disable` (when the `disableGeoip` option is on), feature flag properties,
+   * and for `$exception` events the active OpenTelemetry trace ids and the injected release id.
+   * They fill only the keys every other layer left unset.
    */
-  protected override getCommonEventProperties(): PostHogEventProperties {
-    const commonProperties = super.getCommonEventProperties()
-
+  private async _sdkEventProperties(
+    event: string,
+    properties: PostHogEventProperties,
+    distinctId: string,
+    flagInputs: Pick<EventMessage, 'groups' | 'flags' | 'sendFeatureFlags' | 'disableGeoip'>
+  ): Promise<PostHogEventProperties> {
+    const sdkProperties: PostHogEventProperties = await this._flagEventProperties(distinctId, flagInputs)
     if (this.options.isServer ?? true) {
-      commonProperties.$is_server = true
+      sdkProperties.$is_server = true
+    }
+    if (this.options.disableGeoip ?? true) {
+      sdkProperties.$geoip_disable = true
     }
+    if (event === '$exception') {
+      // Both ids or neither, so a trace id is never paired with another trace's span id.
+      if (isUnsetProperty(properties, '$trace_id') && isUnsetProperty(properties, '$span_id')) {
+        Object.assign(sdkProperties, await getActiveTraceProperties())
+      }
+      const releaseId = CoreErrorTracking.getInjectedReleaseId()
+      if (releaseId) {
+        sdkProperties.$release_id = releaseId
+      }
+    }
+    return sdkProperties
+  }
 
-    return commonProperties
+  /**
+   * `$feature/<key>` and `$active_feature_flags` from a `flags` snapshot or, when there is none,
+   * from `sendFeatureFlags`. Any failure gives no flag properties, and the event is still sent.
+   */
+  private async _flagEventProperties(
+    distinctId: string,
+    {
+      groups,
+      flags,
+      sendFeatureFlags,
+      disableGeoip,
+    }: Pick<EventMessage, 'groups' | 'flags' | 'sendFeatureFlags' | 'disableGeoip'>
+  ): Promise<PostHogEventProperties> {
+    try {
+      // An explicit `flags` snapshot always wins: the event carries the values the code branched
+      // on, with no additional network call.
+      if (flags) {
+        if (sendFeatureFlags) {
+          console.warn(
+            '[PostHog] Both `flags` and `sendFeatureFlags` were passed to capture(); using `flags` and ignoring `sendFeatureFlags`.'
+          )
+        }
+        return flags._getEventProperties()
+      }
+
+      if (sendFeatureFlags) {
+        emitDeprecationWarningOnce(
+          'sendFeatureFlags',
+          '`sendFeatureFlags` is deprecated and will be removed in a future major version. ' +
+            'Pass a `flags` snapshot from `posthog.evaluateFlags(...)` instead — it avoids a ' +
+            'second `/flags` request per capture and guarantees the event carries the exact ' +
+            'flag values your code branched on.'
+        )
+        // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
+        const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined
+        const flagValues = await this.getFeatureFlagsForEvent(distinctId, groups, disableGeoip, sendFeatureFlagsOptions)
+        return buildFlagEventProperties(flagValues)
+      }
+    } catch {
+      return {}
+    }
+
+    // $feature_flag_called events are not enriched with cached flags — the flags
+    // on that event should reflect the specific call, not a potentially stale snapshot.
+    return {}
   }
 
   /**
@@ -1073,7 +1174,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     type: string,
     props: EventMessage,
     immediate: boolean,
-    prepareOptions?: { includeContextProperties?: boolean },
+    prepareOptions?: PrepareEventOptions,
     explicitRoute?: string
   ): Promise<void> {
     const invalidUuidWarned = isInvalidUuid(props.uuid)
@@ -1086,17 +1187,15 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         .then(({ distinctId, event, properties, options, eventOptions }) => {
           const captureOptions: LaneCaptureOptions = {
             timestamp: options.timestamp,
-            disableGeoip: options.disableGeoip,
+            // `$geoip_disable` is already set before before_send; core must not add it after.
+            disableGeoip: false,
             uuid: options.uuid,
             _invalidUuidWarned: invalidUuidWarned,
           }
           const message = {
             distinctId,
             event,
-            properties: {
-              ...properties,
-              ...this.getCommonEventProperties(),
-            },
+            properties,
             ...(eventOptions !== undefined ? { options: eventOptions } : {}),
           }
           return immediate
@@ -1275,21 +1374,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @param data - The identify data containing distinctId and properties
    */
   identify({ distinctId, properties = {}, disableGeoip, options }: IdentifyMessage): void {
-    // Catch properties passed as $set and move them to the top level
-    const { $set, $set_once, $anon_distinct_id, ...rest } = properties
-    // if no $set is provided we assume all rest properties are $set
-    const setProps = $set || rest
-    const setOnceProps = $set_once || {}
-    const eventProperties = {
-      $set: setProps,
-      $set_once: setOnceProps,
-      $anon_distinct_id: $anon_distinct_id ?? undefined,
-    }
+    const eventProperties = identifyEventProperties(properties)
     this._sendPreparedEvent(
       'identify',
       { distinctId, event: '$identify', properties: eventProperties, disableGeoip, options },
-      false,
-      { includeContextProperties: false }
+      false
     )
   }
 
@@ -1314,21 +1403,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * @returns Promise that resolves when the identify is processed
    */
   async identifyImmediate({ distinctId, properties = {}, disableGeoip, options }: IdentifyMessage): Promise<void> {
-    // Catch properties passed as $set and move them to the top level
-    const { $set, $set_once, $anon_distinct_id, ...rest } = properties
-    // if no $set is provided we assume all rest properties are $set
-    const setProps = $set || rest
-    const setOnceProps = $set_once || {}
-    const eventProperties = {
-      $set: setProps,
-      $set_once: setOnceProps,
-      $anon_distinct_id: $anon_distinct_id ?? undefined,
-    }
+    const eventProperties = identifyEventProperties(properties)
     await this._sendPreparedEvent(
       'identify',
       { distinctId, event: '$identify', properties: eventProperties, disableGeoip, options },
-      true,
-      { includeContextProperties: false }
+      true
     )
   }
 
@@ -1415,12 +1494,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       {
         distinctId: data.distinctId,
         event: '$create_alias',
-        properties: { distinct_id: data.distinctId, alias: data.alias },
+        properties: { alias: data.alias },
         disableGeoip: data.disableGeoip,
         options: data.options,
       },
       false,
-      { includeContextProperties: false }
+      ALIAS_PREPARE_OPTIONS
     )
   }
 
@@ -1452,12 +1531,12 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       {
         distinctId: data.distinctId,
         event: '$create_alias',
-        properties: { distinct_id: data.distinctId, alias: data.alias },
+        properties: { alias: data.alias },
         disableGeoip: data.disableGeoip,
         options: data.options,
       },
       true,
-      { includeContextProperties: false }
+      ALIAS_PREPARE_OPTIONS
     )
   }
 
@@ -2747,7 +2826,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     this._sendPreparedEvent(
       'capture',
       {
-        distinctId: distinctId || `$${groupType}_${groupKey}`,
+        distinctId,
         event: '$groupidentify',
         properties: {
           $group_type: groupType,
@@ -2758,7 +2837,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         options,
       },
       false,
-      { includeContextProperties: false }
+      { fallbackDistinctId: `$${groupType}_${groupKey}`, contextSession: false }
     )
   }
 
@@ -2795,7 +2874,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     await this._sendPreparedEvent(
       'capture',
       {
-        distinctId: distinctId || `$${groupType}_${groupKey}`,
+        distinctId,
         event: '$groupidentify',
         properties: {
           $group_type: groupType,
@@ -2806,7 +2885,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
         options,
       },
       true,
-      { includeContextProperties: false }
+      { fallbackDistinctId: `$${groupType}_${groupKey}`, contextSession: false }
     )
   }
 
@@ -2945,6 +3024,80 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return false
   }
 
+  /**
+   * Register properties that every event sent by this client carries.
+   *
+   * @remarks
+   * Each event fills the keys it left unset in this order: the event's own values, then context
+   * properties, then these, then the values the SDK adds (such as `$is_server` and
+   * `$geoip_disable`). `before_send` sees the result and can change it.
+   *
+   * @example
+   * ```ts
+   * await client.register({ service: 'billing' })
+   * ```
+   *
+   * {@label Capture}
+   *
+   * @param properties - The properties to add to every event
+   */
+  override register(properties: PostHogEventProperties): Promise<void> {
+    return super.register(properties)
+  }
+
+  /**
+   * Remove a property added with `register()`.
+   *
+   * {@label Capture}
+   *
+   * @param property - The property name to remove
+   */
+  override unregister(property: string): Promise<void> {
+    return super.unregister(property)
+  }
+
+  /**
+   * Register options that every event sent by this client carries.
+   *
+   * @remarks
+   * Each event fills the options it left unset (missing or `null`) in this order: the event's own
+   * `options`, then context options, then these, then the options the SDK adds (such as
+   * `process_person_profile: false` for an event with no distinct id). `before_send` sees the
+   * result and can change it. Values are sent to capture unchanged. Capture drops an event whose
+   * option value it cannot read, so a bad value registered here drops every event. An option beats
+   * its legacy property, such as `$process_person_profile`, wherever either one was set.
+   *
+   * @example
+   * ```ts
+   * client.registerOptions({ cookieless_mode: true })
+   * ```
+   *
+   * {@label Capture}
+   *
+   * @param options - The options to add to every event
+   */
+  registerOptions(options: Record<string, JsonType>): void {
+    if (!isPlainObject(options)) {
+      // console.error, not this._logger: the logger only prints in debug mode, and the options are lost.
+      console.error('[PostHog] registerOptions takes an object; ignoring the value')
+      return
+    }
+    this._globalOptions = { ...this._globalOptions, ...options }
+  }
+
+  /**
+   * Remove an option added with `registerOptions()`.
+   *
+   * {@label Capture}
+   *
+   * @param key - The option name to remove
+   */
+  unregisterOptions(key: string): void {
+    const remaining = { ...this._globalOptions }
+    delete remaining[key]
+    this._globalOptions = remaining
+  }
+
   protected abstract initializeContext(): IPostHogContext | undefined
 
   /**
@@ -2953,6 +3106,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * Context properties like tags and sessionId will be automatically attached to all events.
    * By default, nested contexts inherit from parent contexts. Use `{ fresh: true }` to start with a clean context.
    *
+   * @remarks
+   * Context `properties` and `options` fill only what an event left unset: the event's own values
+   * win, and context values beat `register()` and `registerOptions()` values and the values the SDK
+   * adds. `before_send` sees the result and can change it.
+   *
    * @example
    * ```ts
    * posthog.withContext({ distinctId: 'user_123' }, () => {
@@ -2962,7 +3120,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * {@label Context}
    *
-   * @param data - Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
+   * @param data - Context data to apply (sessionId, distinctId, properties, options)
    * @param fn - Function to run with the context
    * @param options - Context options (fresh: true to start with clean context instead of inheriting)
    * @returns The return value of the function
@@ -3007,7 +3165,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * across unrelated work. Prefer `withContext()` when you can wrap code
    * in a callback — it creates an isolated scope that cleans up automatically.
    *
-   * @param data - Context data to apply (distinctId, sessionId, properties)
+   * @param data - Context data to apply (distinctId, sessionId, properties, options)
    * @param options - Context options (fresh: true to start with clean context instead of inheriting)
    */
   enterContext(data: Partial<ContextData>, options?: ContextOptions): void {
@@ -3300,7 +3458,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param error - The error to capture
    * @param distinctId - Optional user distinct ID
-   * @param additionalProperties - Optional additional properties to include
+   * @param additionalProperties - Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.
    * @param uuid - Optional event UUID
    * @param flags - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
    */
@@ -3357,7 +3515,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param error - The error to capture
    * @param distinctId - Optional user distinct ID
-   * @param additionalProperties - Optional additional properties to include
+   * @param additionalProperties - Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.
    * @param flags - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
    * @returns Promise that resolves when the error is captured
    */
@@ -3390,9 +3548,14 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     return this._prepareEventMessage(props)
   }
 
+  /**
+   * Build an event in the canonical order: identity, the call's own values, then the values it left
+   * unset from context, then `register()` / `registerOptions()`, then the SDK, then the minimal
+   * `$feature_flag_called` allowlist, then `before_send`, which has the final say.
+   */
   private async _prepareEventMessage(
     props: EventMessage,
-    options: { includeContextProperties?: boolean } = {}
+    prepareOptions: PrepareEventOptions = {}
   ): Promise<{
     distinctId: string
     event: string
@@ -3412,48 +3575,76 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       disableGeoip,
       uuid,
     }: EventMessage = props
-    let eventOptions = readEventOptions(props.options)
+    const callOptions = readEventOptions(props.options)
 
+    // Read every layer now, before the first await, so later changes never reach this event.
     const contextData = this.context?.get()
-    const includeContextProperties = options.includeContextProperties ?? true
+    const contextProperties = snapshotLayer(contextData?.properties)
+    const contextOptions = snapshotLayer(contextData?.options)
+    const globalProperties = snapshotLayer(this.props)
+    const globalOptions = this._globalOptions
 
-    let mergedDistinctId = distinctId || contextData?.distinctId
+    const resolvedDistinctId =
+      presentDistinctId(distinctId) ?? presentDistinctId(contextData?.distinctId) ?? prepareOptions.fallbackDistinctId
+    const eventDistinctId = resolvedDistinctId ?? uuidv7()
 
-    const mergedProperties = includeContextProperties
-      ? {
-          ...this.props,
-          ...(contextData?.properties || {}),
-          ...(properties || {}),
-        }
-      : { ...(properties || {}) }
-
-    if (event === '$exception' && !('$trace_id' in mergedProperties || '$span_id' in mergedProperties)) {
-      Object.assign(mergedProperties, await getActiveTraceProperties())
+    const eventProperties: PostHogEventProperties = { ...(properties || {}) }
+    if (prepareOptions.distinctIdProperty) {
+      eventProperties.distinct_id = eventDistinctId
     }
-
-    if (!mergedDistinctId) {
-      mergedDistinctId = uuidv7()
-      if (eventOptions?.process_person_profile === undefined || eventOptions.process_person_profile === null) {
-        eventOptions = { ...eventOptions, process_person_profile: false }
-      }
+    if (
+      (prepareOptions.contextSession ?? true) &&
+      contextData?.sessionId &&
+      isUnsetProperty(eventProperties, '$session_id')
+    ) {
+      eventProperties.$session_id = contextData.sessionId
     }
-
-    if (includeContextProperties && contextData?.sessionId && !mergedProperties.$session_id) {
-      mergedProperties.$session_id = contextData.sessionId
+    if (isPlainObject(groups) && Object.keys(groups).length > 0) {
+      const existingGroups = eventProperties.$groups
+      eventProperties.$groups = isPlainObject(existingGroups) ? { ...existingGroups, ...groups } : { ...groups }
+    }
+    if (disableGeoip !== undefined && disableGeoip !== null) {
+      fillProperties(eventProperties, [{ $geoip_disable: disableGeoip }])
     }
 
-    // Minimal $feature_flag_called events: rebuild from the strict allowlist before before_send
-    // runs, so a customer hook may deliberately re-add stripped properties. Everything the SDK
-    // itself adds after this point ($groups, $lib/$lib_version/$is_server, $geoip_disable) is
-    // allowlisted — no SDK enrichment may reintroduce stripped properties.
-    const finalProperties = this._shouldSendMinimalFlagCalledEvent(event, mergedProperties)
-      ? minimizeFlagCalledEventProperties(mergedProperties)
-      : mergedProperties
+    fillProperties(eventProperties, [contextProperties, globalProperties], prepareOptions.callOnlyProperties)
+    fillProperties(eventProperties, [
+      await this._sdkEventProperties(event, eventProperties, eventDistinctId, {
+        groups,
+        flags,
+        sendFeatureFlags,
+        disableGeoip,
+      }),
+    ])
+
+    const filledOptions: Record<string, JsonType> = { ...callOptions }
+    fillOptions(filledOptions, [
+      contextOptions,
+      globalOptions,
+      resolvedDistinctId !== undefined ? undefined : { process_person_profile: false },
+    ])
+    const eventOptions = callOptions !== undefined || Object.keys(filledOptions).length > 0 ? filledOptions : undefined
+
+    // Runs after every fill and before before_send, so no default can re-add a stripped property
+    // but a hook still can.
+    const finalProperties = this._shouldSendMinimalFlagCalledEvent(event, eventProperties)
+      ? minimizeFlagCalledEventProperties(eventProperties, FLAG_CALLED_OPTION_SOURCE_PROPERTIES)
+      : eventProperties
+
+    let finalEvent = event
+    if (
+      event === '$pageview' &&
+      this.options.__preview_capture_bot_pageviews &&
+      typeof finalProperties.$raw_user_agent === 'string' &&
+      isBlockedUA(finalProperties.$raw_user_agent, this.options.custom_blocked_useragents || [])
+    ) {
+      finalEvent = '$bot_pageview'
+      finalProperties.$browser_type = 'bot'
+    }
 
-    // Run before_send if configured
     const eventMessage = this._runBeforeSend({
-      distinctId: mergedDistinctId,
-      event,
+      distinctId: eventDistinctId,
+      event: finalEvent,
       properties: finalProperties,
       groups,
       flags,
@@ -3468,80 +3659,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       return Promise.reject(null)
     }
 
-    // :TRICKY: If we flush, or need to shut down, to not lose events we want this promise to resolve before we flush
-    const eventProperties = await Promise.resolve()
-      .then(async () => {
-        // Precedence: an explicit `flags` snapshot always wins, regardless of
-        // `sendFeatureFlags`. The snapshot guarantees the event carries the same
-        // values the developer branched on with no additional network call. The
-        // `sendFeatureFlags` path only runs when no snapshot is provided.
-        if (flags) {
-          if (sendFeatureFlags) {
-            console.warn(
-              '[PostHog] Both `flags` and `sendFeatureFlags` were passed to capture(); using `flags` and ignoring `sendFeatureFlags`.'
-            )
-          }
-          return flags._getEventProperties()
-        }
-
-        if (sendFeatureFlags) {
-          emitDeprecationWarningOnce(
-            'sendFeatureFlags',
-            '`sendFeatureFlags` is deprecated and will be removed in a future major version. ' +
-              'Pass a `flags` snapshot from `posthog.evaluateFlags(...)` instead — it avoids a ' +
-              'second `/flags` request per capture and guarantees the event carries the exact ' +
-              'flag values your code branched on.'
-          )
-          // If we are sending feature flags, we evaluate them locally if the user prefers it, otherwise we fall back to remote evaluation
-          const sendFeatureFlagsOptions = typeof sendFeatureFlags === 'object' ? sendFeatureFlags : undefined
-          const flagValues = await this.getFeatureFlagsForEvent(
-            eventMessage.distinctId!,
-            groups,
-            disableGeoip,
-            sendFeatureFlagsOptions
-          )
-          return buildFlagEventProperties(flagValues)
-        }
-
-        // $feature_flag_called events are not enriched with cached flags — the flags
-        // on that event should reflect the specific call, not a potentially stale snapshot.
-        return {}
-      })
-      .catch(() => {
-        // Something went wrong getting the flag info - we should capture the event anyways
-        return {}
-      })
-      .then((additionalProperties): PostHogEventProperties => {
-        // No matter what - capture the event
-        const resolvedGroups = eventMessage.groups || groups
-
-        return {
-          ...additionalProperties,
-          ...(eventMessage.properties || {}),
-          // Only stamp $groups from the top-level `groups` when present — otherwise a
-          // caller-provided properties.$groups would be clobbered with undefined (#3888).
-          ...(resolvedGroups !== undefined && Object.keys(resolvedGroups).length > 0
-            ? { $groups: resolvedGroups }
-            : {}),
-        }
-      })
-
-    // Handle bot pageview collection based on preview flag
-    if (
-      eventMessage.event === '$pageview' &&
-      this.options.__preview_capture_bot_pageviews &&
-      typeof eventProperties.$raw_user_agent === 'string'
-    ) {
-      if (isBlockedUA(eventProperties.$raw_user_agent, this.options.custom_blocked_useragents || [])) {
-        eventMessage.event = '$bot_pageview'
-        eventProperties.$browser_type = 'bot'
-      }
-    }
-
     return {
       distinctId: eventMessage.distinctId!,
       event: eventMessage.event,
-      properties: eventProperties,
+      properties: eventMessage.properties || {},
       options: {
         timestamp: eventMessage.timestamp,
         disableGeoip: eventMessage.disableGeoip,
diff --git a/packages/node/src/event-defaults.ts b/packages/node/src/event-defaults.ts
new file mode 100644
index 0000000000..8f7b10fcd2
--- /dev/null
+++ b/packages/node/src/event-defaults.ts
@@ -0,0 +1,75 @@
+import { isPlainObject, type JsonType, type PostHogEventProperties } from '@posthog/core'
+
+/** Properties that a default fills one level deep when the event's value and the default are both objects. */
+const NESTED_FILL_PROPERTIES: ReadonlySet<string> = new Set(['$set', '$set_once', '$groups', '$group_set'])
+
+/** One layer of default values, or nothing. */
+export type DefaultsLayer = Readonly<Record<string, unknown>> | undefined
+
+/** A property is unset when its key is missing or its value is `undefined`; `null` is a value. */
+export function isUnsetProperty(properties: PostHogEventProperties, key: string): boolean {
+  return properties[key] === undefined
+}
+
+/** An option is unset when its key is missing or its value is `undefined` or `null`. */
+export function isUnsetOption(options: Record<string, unknown>, key: string): boolean {
+  return options[key] === undefined || options[key] === null
+}
+
+/**
+ * Fill the properties the event left unset from each layer in turn, highest layer first, so a
+ * value from an earlier layer is never replaced. `$set`, `$set_once`, `$groups` and `$group_set`
+ * fill one level deep when both values are objects. Keys in `skipKeys` are never filled.
+ */
+export function fillProperties(
+  properties: PostHogEventProperties,
+  layers: readonly DefaultsLayer[],
+  skipKeys: readonly string[] = []
+): void {
+  for (const layer of layers) {
+    if (!layer) {
+      continue
+    }
+    for (const [key, value] of Object.entries(layer)) {
+      if (value === undefined || skipKeys.includes(key)) {
+        continue
+      }
+      const existing = properties[key]
+      if (existing === undefined) {
+        properties[key] = value as JsonType
+      } else if (NESTED_FILL_PROPERTIES.has(key) && isPlainObject(existing) && isPlainObject(value)) {
+        properties[key] = fillNested(existing, value)
+      }
+    }
+  }
+}
+
+/** Fill the options the event left unset from each layer in turn, highest layer first. */
+export function fillOptions(options: Record<string, JsonType>, layers: readonly DefaultsLayer[]): void {
+  for (const layer of layers) {
+    if (!layer) {
+      continue
+    }
+    for (const [key, value] of Object.entries(layer)) {
+      if (value !== undefined && isUnsetOption(options, key)) {
+        options[key] = value as JsonType
+      }
+    }
+  }
+}
+
+/** A new object: the event's inner values, plus the default's inner keys the event left unset. */
+function fillNested(existing: Record<string, unknown>, defaults: Record<string, unknown>): PostHogEventProperties {
+  const filled: Record<string, unknown> = { ...existing }
+  for (const [key, value] of Object.entries(defaults)) {
+    if (filled[key] === undefined && value !== undefined) {
+      filled[key] = value
+    }
+  }
+  return filled as PostHogEventProperties
+}
+
+/** A shallow copy of a layer read at capture time, or undefined when it is not an object. */
+export function snapshotLayer(layer: unknown): Record<string, unknown> | undefined {
+  return isPlainObject(layer) ? { ...layer } : undefined
+}
diff --git a/packages/node/src/extensions/context/context.ts b/packages/node/src/extensions/context/context.ts
index 044dbf9260..c2a7672e27 100644
--- a/packages/node/src/extensions/context/context.ts
+++ b/packages/node/src/extensions/context/context.ts
@@ -33,6 +33,10 @@ export class PostHogContext implements IPostHogContext {
         ...(current.properties || {}),
         ...(context.properties || {}),
       },
+      options: {
+        ...(current.options || {}),
+        ...(context.options || {}),
+      },
     }
   }
 }
diff --git a/packages/node/src/extensions/context/types.ts b/packages/node/src/extensions/context/types.ts
index f74d9da48c..08da3e7648 100644
--- a/packages/node/src/extensions/context/types.ts
+++ b/packages/node/src/extensions/context/types.ts
@@ -1,7 +1,15 @@
+import type { JsonType } from '@posthog/core'
+
 export interface ContextData {
   distinctId?: string
   sessionId?: string
+  /** Properties that fill the keys an event left unset. The event's own values win. */
   properties?: Record<string, any>
+  /**
+   * Options that fill the options an event left unset (missing or `null`). The event's own options
+   * win; these beat options from `registerOptions()`.
+   */
+  options?: Record<string, JsonType>
 }
 
 export interface ContextOptions {
diff --git a/packages/node/src/extensions/error-tracking/index.ts b/packages/node/src/extensions/error-tracking/index.ts
index 0573c10da9..baed69c0d8 100644
--- a/packages/node/src/extensions/error-tracking/index.ts
+++ b/packages/node/src/extensions/error-tracking/index.ts
@@ -8,6 +8,26 @@ import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
 
 const SHUTDOWN_TIMEOUT = 2000
 
+/**
+ * Exception properties that the SDK or PostHog owns (sdk-specs `exception-event-metadata`), so
+ * a caller's properties never set them.
+ */
+const RESERVED_EXCEPTION_PROPERTIES: ReadonlySet<string> = new Set([
+  '$exception_list',
+  '$exception_level',
+  '$exception_source',
+  '$debug_images',
+  '$exception_types',
+  '$exception_values',
+  '$exception_sources',
+  '$exception_functions',
+  '$exception_fingerprint_version',
+  '$exception_fingerprint_record',
+  '$exception_issue_id',
+  '$exception_release',
+  '$cymbal_errors',
+])
+
 export default class ErrorTracking {
   private client: PostHogBackendClient
   private _exceptionAutocaptureEnabled: boolean
@@ -49,20 +69,19 @@ export default class ErrorTracking {
     distinctId?: string,
     additionalProperties?: Record<string | number, any>
   ): Promise<EventMessage> {
-    const properties: EventMessage['properties'] = { ...additionalProperties }
+    const properties: EventMessage['properties'] = {}
+    for (const [key, value] of Object.entries(additionalProperties ?? {})) {
+      if (!RESERVED_EXCEPTION_PROPERTIES.has(key)) {
+        properties[key] = value
+      }
+    }
 
     const exceptionProperties = builder.buildFromUnknown(error, hint)
     exceptionProperties.$exception_list = await builder.modifyFrames(exceptionProperties.$exception_list)
 
-    const injectedReleaseId = CoreErrorTracking.getInjectedReleaseId()
-    if (injectedReleaseId) {
-      properties.$release_id = injectedReleaseId
-    }
-
     return {
       event: '$exception',
-      // Leave distinctId resolution to prepareEventMessage which checks request context
-      // and falls back to a random UUID with $process_person_profile = false
+      // The client resolves a missing id: the context id, else a personless id.
       distinctId: distinctId,
       properties: {
         ...exceptionProperties,
diff --git a/packages/node/src/types.ts b/packages/node/src/types.ts
index bf2419f12d..b62131bf5f 100644
--- a/packages/node/src/types.ts
+++ b/packages/node/src/types.ts
@@ -67,7 +67,11 @@ export type SendFeatureFlagsOptions = {
 }
 
 export type EventMessage = Omit<IdentifyMessage, 'distinctId'> & {
-  distinctId?: string // Optional - can be provided via context
+  /**
+   * The event's distinct id. When it is missing, empty or only whitespace, the context distinct id
+   * is used; without one, the event gets a generated id and `options.process_person_profile: false`.
+   */
+  distinctId?: string
   event: string
   groups?: Record<string, string | number> // Mapping of group type to group id
   /**
@@ -98,7 +102,11 @@ export type GroupIdentifyMessage = {
   groupType: string
   groupKey: string // Unique identifier for the group
   properties?: Record<string | number, any>
-  distinctId?: string // optional distinctId to associate message with a person
+  /**
+   * The event's distinct id. When it is missing, empty or only whitespace, the context distinct id
+   * is used, then `$<groupType>_<groupKey>`.
+   */
+  distinctId?: string
   disableGeoip?: boolean
   /**
    * Per-event options, sent to capture unchanged. Known keys today are `process_person_profile`,
@@ -201,6 +209,7 @@ export type BeforeSendFn = (event: EventMessage) => EventMessage | null
 export type PostHogOptions = Omit<
   PostHogCoreOptions,
   | 'before_send'
+  | 'disableGeoip'
   | 'flushInterval'
   | 'maxQueueSize'
   | 'fetchRetryCount'
@@ -209,6 +218,15 @@ export type PostHogOptions = Omit<
   | 'requestTimeout'
 > & {
   persistence?: 'memory'
+  /**
+   * Whether to disable GeoIP lookups for events and feature flag requests. When on, every event
+   * gets `$geoip_disable: true` unless the event, its context or `register()` sets
+   * `$geoip_disable`. A per-call `disableGeoip` argument sets it for that event, under the event's
+   * own `$geoip_disable` property.
+   *
+   * @default true
+   */
+  disableGeoip?: boolean
   /**
    * The interval in milliseconds between periodic flushes
    *
@@ -387,6 +405,14 @@ export type PostHogOptions = Omit<
    * Allows modification or dropping of events before they're sent to PostHog.
    * If an array is provided, the functions are run in order.
    * If a function returns null, the event will be dropped.
+   *
+   * @remarks
+   * The hook gets a copy of the finished event: the event's own values, then the values filled
+   * from context, `register()` and `registerOptions()`, then the values the SDK adds (such as
+   * `$is_server`, `$geoip_disable`, feature flag properties and `options.process_person_profile`).
+   * It has the final say: it can change or remove any of them, and nothing is added after it.
+   * Set `$geoip_disable` in `properties` to change GeoIP; the `disableGeoip` and `groups` fields
+   * are already applied to the properties it sees.
    */
   before_send?: BeforeSendFn | BeforeSendFn[]
   /**
@@ -487,7 +513,8 @@ export type PostHogOptions = Omit<
    * react-native events. Set this to `false` when running the SDK as a
    * client/CLI so the event is attributed to the device OS normally instead of
    * being marked as a server event. When `false`, the `$is_server` property is
-   * omitted entirely.
+   * omitted entirely. A `$is_server` value set on the event, in context or with
+   * `register()` wins over this setting.
    *
    * @default true
    * @example
@@ -726,7 +753,7 @@ export interface IPostHog {
    * @param distinctId the current unique id
    * @param alias the unique ID of the user before
    */
-  alias(data: { distinctId: string; alias: string; options?: Record<string, JsonType> }): void
+  alias(data: { distinctId: string; alias: string; disableGeoip?: boolean; options?: Record<string, JsonType> }): void
 
   /**
    * @description To marry up whatever a user does before they sign up or log in with what they do after you need to make an alias call.
@@ -734,7 +761,12 @@ export interface IPostHog {
    * @param distinctId the current unique id
    * @param alias the unique ID of the user before
    */
-  aliasImmediate(data: { distinctId: string; alias: string; options?: Record<string, JsonType> }): Promise<void>
+  aliasImmediate(data: {
+    distinctId: string
+    alias: string
+    disableGeoip?: boolean
+    options?: Record<string, JsonType>
+  }): Promise<void>
 
   /**
    * @description PostHog feature flags (https://posthog.com/docs/features/feature-flags)
@@ -981,7 +1013,7 @@ export interface IPostHog {
 
   /**
    * @description Run a function with specific context that will be applied to all events captured within that context.
-   * @param data Context data to apply (sessionId, distinctId, properties, enableExceptionAutocapture)
+   * @param data Context data to apply (sessionId, distinctId, properties, options)
    * @param fn Function to run with the context
    * @param options Context options (fresh)
    * @returns The return value of the function
@@ -992,7 +1024,7 @@ export interface IPostHog {
    * @description Set context without a callback wrapper. Must be called in the same
    * async scope that makes PostHog calls. Prefer `withContext()` when you can wrap
    * code in a callback.
-   * @param data Context data to apply (distinctId, sessionId, properties)
+   * @param data Context data to apply (distinctId, sessionId, properties, options)
    * @param options Context options (fresh)
    */
   enterContext(data: Partial<ContextData>, options?: ContextOptions): void

From 5a99b41ba4429860402ec58edc65aac525e279dc Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:22:59 -0700
Subject: [PATCH 11/20] feat(node)!: take an options object in captureException
 (#5417)

* feat(node)!: make registerOptions and unregisterOptions async

They return a promise, like register() and unregister().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: return a flat message from prepareEventMessage

The result has the same shape as the message passed in: `options` holds the event options, and
`uuid`, `timestamp` and `disableGeoip` are top-level fields.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(node)!: take an options object in captureException

captureException(error, { distinctId, properties, options, uuid, flags, level }) and the same for
captureExceptionImmediate. `level` sets `$exception_level` (default `error`). The 5.x positional
form still works and logs one deprecation error per process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(mcp): correct the comment on why the sink passes groups

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(examples): pass an options object to captureException

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): add changeset for the captureException options object

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(convex,next,nuxt): stay on posthog-node 5 until their own major

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(ai): pass captureException arguments in the form the client takes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(convex): declare the flag action return types

The build emits declarations, and with posthog-node 5 from the registry the
inferred types point into that package's own copy of @posthog/core.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: exempt posthog-node and @posthog/core from the release-age wait

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): normalize exception levels like Python, warn per method and on extra arguments, keep the release cooldown

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-ai-node-6.md               |   5 +
 .changeset/posthog-mcp-node-6.md              |   5 +
 .changeset/posthog-node-capture-api-shapes.md |   6 +
 .../example-cloudflare-hono-vite/src/index.ts |  12 +-
 examples/example-hono/src/index.ts            |  15 +-
 examples/example-nextjs/src/app/actions.ts    |   2 +-
 examples/example-node/server.ts               |   3 +-
 packages/ai/package.json                      |   2 +-
 packages/ai/src/captureAiGeneration.ts        |  25 +-
 packages/ai/tests/captureAiGeneration.test.ts |  30 ++-
 packages/convex/package.json                  |   2 +-
 packages/convex/src/component/lib.ts          |   5 +-
 packages/mcp/package.json                     |   2 +-
 packages/mcp/src/__tests__/sink.test.ts       |   6 +-
 packages/mcp/src/extensions/sink.ts           |   8 +-
 packages/next/package.json                    |   2 +-
 .../posthog-node-references-latest.json       | 162 +++++++-----
 .../src/__tests__/capture-v1/layers.spec.ts   | 231 ++++++++++++++----
 packages/node/src/__tests__/context.spec.ts   |   2 +-
 .../node/src/__tests__/evaluate-flags.spec.ts |   4 +-
 .../exception-trace-context.spec.ts           |   2 +-
 .../node/src/__tests__/posthog-node.spec.ts   |   2 +-
 .../__tests__/prepare-event-message.spec.ts   |  26 ++
 .../__tests__/server-wire-snapshots.spec.ts   |  11 +-
 .../src/__tests__/types/public-interface.ts   |   4 +-
 packages/node/src/client.ts                   | 195 +++++++++------
 .../src/extensions/error-tracking/index.ts    |  26 +-
 packages/node/src/extensions/nestjs.ts        |   4 +-
 packages/node/src/types.ts                    |  68 ++++--
 packages/nuxt/package.json                    |   2 +-
 pnpm-lock.yaml                                |  44 +++-
 31 files changed, 652 insertions(+), 261 deletions(-)
 create mode 100644 .changeset/posthog-ai-node-6.md
 create mode 100644 .changeset/posthog-mcp-node-6.md
 create mode 100644 .changeset/posthog-node-capture-api-shapes.md

diff --git a/.changeset/posthog-ai-node-6.md b/.changeset/posthog-ai-node-6.md
new file mode 100644
index 0000000000..7cbfd44556
--- /dev/null
+++ b/.changeset/posthog-ai-node-6.md
@@ -0,0 +1,5 @@
+---
+'@posthog/ai': patch
+---
+
+Supports posthog-node 6. Exception autocapture passes an options object to `captureException` when the client is posthog-node 6, and positional arguments for 5.x.
diff --git a/.changeset/posthog-mcp-node-6.md b/.changeset/posthog-mcp-node-6.md
new file mode 100644
index 0000000000..1c15915227
--- /dev/null
+++ b/.changeset/posthog-mcp-node-6.md
@@ -0,0 +1,5 @@
+---
+'@posthog/mcp': patch
+---
+
+Accepts posthog-node 6 as a peer dependency.
diff --git a/.changeset/posthog-node-capture-api-shapes.md b/.changeset/posthog-node-capture-api-shapes.md
new file mode 100644
index 0000000000..068e118999
--- /dev/null
+++ b/.changeset/posthog-node-capture-api-shapes.md
@@ -0,0 +1,6 @@
+---
+'posthog-node': major
+---
+
+`captureException()` and `captureExceptionImmediate()` take an options object (`distinctId`, `properties`, `options`, `uuid`, `flags`, `level`); the old positional form still works in 6.x and logs a deprecation error once per method. `level` is read case-insensitively, with the same aliases as posthog-python (`critical` → `fatal`, `warn` → `warning`); an unknown level keeps `error`.
+`registerOptions()` and `unregisterOptions()` return a promise, and `prepareEventMessage()` returns a flat message with top-level `options`, `uuid`, `timestamp` and `disableGeoip`.
diff --git a/examples/example-cloudflare-hono-vite/src/index.ts b/examples/example-cloudflare-hono-vite/src/index.ts
index 14d1c09a9d..58aee860bd 100644
--- a/examples/example-cloudflare-hono-vite/src/index.ts
+++ b/examples/example-cloudflare-hono-vite/src/index.ts
@@ -3,17 +3,13 @@ import { PostHog } from 'posthog-node'
 
 const app = new Hono()
 
-const posthog = new PostHog(
-  process.env.POSTHOG_PROJECT_API_KEY!,
-  { host: process.env.POSTHOG_API_HOST! }
-)
+const posthog = new PostHog(process.env.POSTHOG_PROJECT_API_KEY!, { host: process.env.POSTHOG_API_HOST! })
 
 app.get('/', async (c) => {
+    const error = new Error('test from cloudflare')
+    await posthog.captureExceptionImmediate(error, { distinctId: 'cloudflare-user-id' })
 
-  const error = new Error('test from cloudflare')
-  await posthog.captureExceptionImmediate(error, 'cloudflare-user-id')
-
-  return c.json({ success: true, message: 'Exception captured!' })
+    return c.json({ success: true, message: 'Exception captured!' })
 })
 
 export default app
diff --git a/examples/example-hono/src/index.ts b/examples/example-hono/src/index.ts
index f730f660d8..2f3901be18 100644
--- a/examples/example-hono/src/index.ts
+++ b/examples/example-hono/src/index.ts
@@ -10,12 +10,15 @@ const posthog = new PostHog(process.env.POSTHOG_PROJECT_API_KEY!, {
 })
 
 app.onError(async (err, c) => {
-    posthog.captureException(new Error(err.message, { cause: err }), 'user_distinct_id_with_err_rethrow', {
-        path: c.req.path,
-        method: c.req.method,
-        url: c.req.url,
-        headers: c.req.header(),
-        // ... other properties
+    posthog.captureException(new Error(err.message, { cause: err }), {
+        distinctId: 'user_distinct_id_with_err_rethrow',
+        properties: {
+            path: c.req.path,
+            method: c.req.method,
+            url: c.req.url,
+            headers: c.req.header(),
+            // ... other properties
+        },
     })
     // TIP: On program exit, call flush to stop pending pollers and flush any remaining events
     await posthog.flush()
diff --git a/examples/example-nextjs/src/app/actions.ts b/examples/example-nextjs/src/app/actions.ts
index a9e92fbfba..f01aa60e15 100644
--- a/examples/example-nextjs/src/app/actions.ts
+++ b/examples/example-nextjs/src/app/actions.ts
@@ -7,5 +7,5 @@ const posthog = new PostHog(process.env.NEXT_PUBLIC_POSTHOG_PROJECT_API_KEY!, {
 })
 
 export async function captureServerError() {
-    await posthog.captureExceptionImmediate(new Error('Server Exception'), 'distinct_id')
+    await posthog.captureExceptionImmediate(new Error('Server Exception'), { distinctId: 'distinct_id' })
 }
diff --git a/examples/example-node/server.ts b/examples/example-node/server.ts
index c73aafc6fc..8e3fc58984 100644
--- a/examples/example-node/server.ts
+++ b/examples/example-node/server.ts
@@ -1,4 +1,3 @@
-
 import express from 'express'
 import { PostHog, setupExpressErrorHandler } from 'posthog-node'
 // import undici from 'undici'
@@ -37,7 +36,7 @@ app.get('/unhandled-error', () => {
 
 app.get('/error', (req, res) => {
     const error = new Error('example error')
-    posthog.captureException(error, 'EXAMPLE_APP_GLOBAL')
+    posthog.captureException(error, { distinctId: 'EXAMPLE_APP_GLOBAL' })
     res.send({ status: 'error!!' })
 })
 
diff --git a/packages/ai/package.json b/packages/ai/package.json
index 3b24c7289c..b24448db90 100644
--- a/packages/ai/package.json
+++ b/packages/ai/package.json
@@ -84,7 +84,7 @@
     "@ai-sdk/provider": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "@openai/agents": "^0.8.0",
     "langchain": ">=1.5.5 <2.0.0",
-    "posthog-node": "^5.0.0"
+    "posthog-node": "^5.0.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/sdk": {
diff --git a/packages/ai/src/captureAiGeneration.ts b/packages/ai/src/captureAiGeneration.ts
index 1f626789f8..b3a5a57a90 100644
--- a/packages/ai/src/captureAiGeneration.ts
+++ b/packages/ai/src/captureAiGeneration.ts
@@ -90,6 +90,29 @@ export interface CaptureAiGenerationOptions {
   onError?: (error: unknown) => void
 }
 
+/**
+ * posthog-node 6 takes an options object; 5.x, which has no `registerOptions`, takes positional
+ * arguments. The 6.x positional fallback works too, but logs a deprecation error in the app.
+ */
+const captureAiException = (
+  client: PostHog,
+  error: unknown,
+  properties: Record<string, unknown>,
+  uuid: string
+): void => {
+  if (typeof client.registerOptions === 'function') {
+    client.captureException(error, { properties, uuid })
+    return
+  }
+  const captureLegacy = client.captureException as (
+    error: unknown,
+    distinctId?: string,
+    properties?: Record<string, unknown>,
+    uuid?: string
+  ) => void
+  captureLegacy.call(client, error, undefined, properties, uuid)
+}
+
 /**
  * Capture an `$ai_generation` (or `$ai_embedding`) event to PostHog.
  *
@@ -151,7 +174,7 @@ export const captureAiGeneration = async (client: PostHog, options: CaptureAiGen
         // so the global and framework handlers skip the rethrown error too.
         if (!shouldRedact) {
           exceptionId = uuidv7()
-          client.captureException(options.error, undefined, { $ai_trace_id: traceId }, exceptionId)
+          captureAiException(client, options.error, { $ai_trace_id: traceId }, exceptionId)
         }
         if (typeof options.error === 'object') {
           ;(options.error as CoreErrorTracking.PreviouslyCapturedError).__posthog_previously_captured_error = true
diff --git a/packages/ai/tests/captureAiGeneration.test.ts b/packages/ai/tests/captureAiGeneration.test.ts
index 5b3a5b48b8..2fef0fffa3 100644
--- a/packages/ai/tests/captureAiGeneration.test.ts
+++ b/packages/ai/tests/captureAiGeneration.test.ts
@@ -426,19 +426,37 @@ describe('captureAiGeneration', () => {
     expect((error as any).__posthog_previously_captured_error).toBe(true)
   })
 
-  it('runs exception autocapture and tags the trace when enabled', async () => {
+  it.each([
+    {
+      name: 'positional arguments for posthog-node 5',
+      registerOptions: undefined,
+      readCall: (args: unknown[]) => ({ error: args[0], properties: args[2], uuid: args[3], argCount: args.length }),
+    },
+    {
+      name: 'an options object for posthog-node 6',
+      registerOptions: vi.fn(),
+      readCall: (args: any[]) => ({
+        error: args[0],
+        properties: args[1].properties,
+        uuid: args[1].uuid,
+        argCount: args.length,
+      }),
+    },
+  ])('runs exception autocapture and tags the trace with $name', async ({ registerOptions, readCall }) => {
     const client = buildClient({ enableExceptionAutocapture: true })
+    ;(client as any).registerOptions = registerOptions
     const error = new Error('boom')
 
     await captureAiGeneration(client, { ...baseRequiredOptions, error })
 
     expect(client.captureException).toHaveBeenCalledTimes(1)
-    const [capturedError, , properties, exceptionId] = (client.captureException as vi.Mock).mock.calls[0]
-    expect(capturedError).toBe(error)
-    expect(properties).toEqual({ $ai_trace_id: expect.any(String) })
-    expect(typeof exceptionId).toBe('string')
+    const call = readCall((client.captureException as vi.Mock).mock.calls[0])
+    expect(call.error).toBe(error)
+    expect(call.properties).toEqual({ $ai_trace_id: expect.any(String) })
+    expect(typeof call.uuid).toBe('string')
+    expect(call.argCount).toBe(registerOptions ? 2 : 4)
 
-    expect(lastCaptureProperties(client).$exception_event_id).toBe(exceptionId)
+    expect(lastCaptureProperties(client).$exception_event_id).toBe(call.uuid)
     expect((error as any).__posthog_previously_captured_error).toBe(true)
   })
 
diff --git a/packages/convex/package.json b/packages/convex/package.json
index 18d076a98b..87d96f5382 100644
--- a/packages/convex/package.json
+++ b/packages/convex/package.json
@@ -65,7 +65,7 @@
   "module": "./dist/client/index.js",
   "dependencies": {
     "@posthog/core": "workspace:^",
-    "posthog-node": "workspace:^"
+    "posthog-node": "^5.56.0"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",
diff --git a/packages/convex/src/component/lib.ts b/packages/convex/src/component/lib.ts
index 410c80d999..a31e015b31 100644
--- a/packages/convex/src/component/lib.ts
+++ b/packages/convex/src/component/lib.ts
@@ -1,3 +1,4 @@
+import type { FeatureFlagValue, JsonType } from '@posthog/core'
 import { PostHog as PostHogEdge } from 'posthog-node/edge'
 import { action, env, internalMutation, internalQuery, query, type MutationCtx } from './_generated/server.js'
 import { api, internal } from './_generated/api.js'
@@ -233,7 +234,7 @@ function remoteFlagsOptions(args: {
 
 export const evaluateFlag = action({
   args: { ...remoteFlagsArgs, key: v.string() },
-  handler: async (_ctx, args) => {
+  handler: async (_ctx, args): Promise<FeatureFlagValue | null> => {
     const { projectToken, host } = readConfig()
     if (!projectToken) return null
     const client = getClient(projectToken, host)
@@ -251,7 +252,7 @@ export const evaluateFlag = action({
 
 export const evaluateFlagPayload = action({
   args: { ...remoteFlagsArgs, key: v.string() },
-  handler: async (_ctx, args) => {
+  handler: async (_ctx, args): Promise<JsonType | null> => {
     const { projectToken, host } = readConfig()
     if (!projectToken) return null
     const client = getClient(projectToken, host)
diff --git a/packages/mcp/package.json b/packages/mcp/package.json
index a609885e26..bbd06764fd 100644
--- a/packages/mcp/package.json
+++ b/packages/mcp/package.json
@@ -79,7 +79,7 @@
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.26.0",
     "@modelcontextprotocol/server": ">=2.0.0",
-    "posthog-node": "^5.0.0"
+    "posthog-node": "^5.0.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/sdk": {
diff --git a/packages/mcp/src/__tests__/sink.test.ts b/packages/mcp/src/__tests__/sink.test.ts
index 89645b0518..8478044ff6 100644
--- a/packages/mcp/src/__tests__/sink.test.ts
+++ b/packages/mcp/src/__tests__/sink.test.ts
@@ -11,9 +11,9 @@ import type { McpEvent } from '../types'
  * actually handed to posthog-node. These tests spy on a fake client instead.
  *
  * Regression guard for https://github.com/PostHog/posthog-js/issues/3888:
- * posthog-node's `prepareEventMessage` overwrites the outgoing `$groups`
- * property with the top-level `groups` field, so the group must be forwarded as
- * a first-class `groups` field — not only inside `properties.$groups`.
+ * posthog-node before 5.38.6 replaces the outgoing `$groups` property with the
+ * top-level `groups` field, so the group must be forwarded as a first-class
+ * `groups` field — not only inside `properties.$groups`.
  */
 describe('McpEventSink groups forwarding', () => {
   function spyClient(): { posthog: PostHog; calls: EventMessage[] } {
diff --git a/packages/mcp/src/extensions/sink.ts b/packages/mcp/src/extensions/sink.ts
index fe33c0c67b..e514babaa5 100644
--- a/packages/mcp/src/extensions/sink.ts
+++ b/packages/mcp/src/extensions/sink.ts
@@ -118,12 +118,8 @@ export class McpEventSink {
     const { event: fullEvent, captures } = result
     try {
       for (const captureEvent of captures) {
-        // `$groups` is written into `properties` by `buildPostHogCaptureEvents`,
-        // but posthog-node's `prepareEventMessage` overwrites the outgoing
-        // `$groups` property with the top-level `groups` field
-        // (`$groups: eventMessage.groups || groups`). Without passing `groups`
-        // here the group association would be silently dropped. See
-        // https://github.com/PostHog/posthog-js/issues/3888.
+        // posthog-node before 5.38.6 replaces `properties.$groups` with the top-level `groups`
+        // field, so pass both (https://github.com/PostHog/posthog-js/issues/3888).
         const groups = captureEvent.properties.$groups as Record<string, string> | undefined
 
         this.posthog.capture({
diff --git a/packages/next/package.json b/packages/next/package.json
index 31ad5b1582..a579cc57bc 100644
--- a/packages/next/package.json
+++ b/packages/next/package.json
@@ -70,7 +70,7 @@
         "@posthog/core": "workspace:^",
         "@posthog/react": "workspace:^",
         "posthog-js": "workspace:^",
-        "posthog-node": "workspace:^",
+        "posthog-node": "^5.56.0",
         "server-only": "^0.0.1"
     },
     "devDependencies": {
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index 2aa4fb144c..05a1aa63ee 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -223,7 +223,7 @@
         {
           "category": "Error tracking",
           "description": "Capture an error exception as an event.",
-          "details": null,
+          "details": "The 5.x positional form `captureException(error, distinctId, properties, uuid, flags)` still works in 6.x but logs a deprecation error once per process, and will be removed in the next major version.",
           "id": "captureException",
           "showDocs": true,
           "title": "captureException",
@@ -231,12 +231,12 @@
             {
               "id": "capture_an_error_with_user_id",
               "name": "Capture an error with user ID",
-              "code": "\n\n// Capture an error with user ID\ntry {\n  // Some risky operation\n  riskyOperation()\n} catch (error) {\n  client.captureException(error, 'user_123')\n}\n\n\n"
+              "code": "\n\n// Capture an error with user ID\ntry {\n  // Some risky operation\n  riskyOperation()\n} catch (error) {\n  client.captureException(error, { distinctId: 'user_123' })\n}\n\n\n"
             },
             {
-              "id": "capture_with_additional_properties",
-              "name": "Capture with additional properties",
-              "code": "\n\n// Capture with additional properties\ntry {\n  apiCall()\n} catch (error) {\n  client.captureException(error, 'user_123', {\n    endpoint: '/api/users',\n    method: 'POST',\n    status_code: 500\n  })\n}\n\n\n\n"
+              "id": "capture_with_additional_properties_and_a_level",
+              "name": "Capture with additional properties and a level",
+              "code": "\n\n// Capture with additional properties and a level\ntry {\n  apiCall()\n} catch (error) {\n  client.captureException(error, {\n    distinctId: 'user_123',\n    properties: { endpoint: '/api/users', method: 'POST', status_code: 500 },\n    level: 'warning',\n  })\n}\n\n\n\n"
             }
           ],
           "releaseTag": "public",
@@ -248,28 +248,10 @@
               "name": "error"
             },
             {
-              "description": "Optional user distinct ID",
+              "description": "Optional distinct id, properties, options, uuid, flags snapshot and level",
               "isOptional": true,
-              "type": "string",
-              "name": "distinctId"
-            },
-            {
-              "description": "Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.",
-              "isOptional": true,
-              "type": "Record<string | number, any>",
-              "name": "additionalProperties"
-            },
-            {
-              "description": "Optional event UUID",
-              "isOptional": true,
-              "type": "EventMessage['uuid']",
-              "name": "uuid"
-            },
-            {
-              "description": "Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events",
-              "isOptional": true,
-              "type": "FeatureFlagEvaluations",
-              "name": "flags"
+              "type": "CaptureExceptionOptions",
+              "name": "options"
             }
           ],
           "returnType": {
@@ -281,7 +263,7 @@
         {
           "category": "Error tracking",
           "description": "Capture an error exception as an event immediately (synchronously).",
-          "details": null,
+          "details": "The 5.x positional form `captureExceptionImmediate(error, distinctId, properties, flags)` still works in 6.x but logs a deprecation error once per process, and will be removed in the next major version.",
           "id": "captureExceptionImmediate",
           "showDocs": true,
           "title": "captureExceptionImmediate",
@@ -289,12 +271,12 @@
             {
               "id": "capture_an_error_immediately_with_user_id",
               "name": "Capture an error immediately with user ID",
-              "code": "\n\n// Capture an error immediately with user ID\ntry {\n  // Some risky operation\n  riskyOperation()\n} catch (error) {\n  await client.captureExceptionImmediate(error, 'user_123')\n}\n\n\n"
+              "code": "\n\n// Capture an error immediately with user ID\ntry {\n  // Some risky operation\n  riskyOperation()\n} catch (error) {\n  await client.captureExceptionImmediate(error, { distinctId: 'user_123' })\n}\n\n\n"
             },
             {
               "id": "capture_with_additional_properties",
               "name": "Capture with additional properties",
-              "code": "\n\n// Capture with additional properties\ntry {\n  apiCall()\n} catch (error) {\n  await client.captureExceptionImmediate(error, 'user_123', {\n    endpoint: '/api/users',\n    method: 'POST',\n    status_code: 500\n  })\n}\n\n\n\n"
+              "code": "\n\n// Capture with additional properties\ntry {\n  apiCall()\n} catch (error) {\n  await client.captureExceptionImmediate(error, {\n    distinctId: 'user_123',\n    properties: { endpoint: '/api/users', method: 'POST', status_code: 500 },\n  })\n}\n\n\n\n"
             }
           ],
           "releaseTag": "public",
@@ -306,22 +288,10 @@
               "name": "error"
             },
             {
-              "description": "Optional user distinct ID",
-              "isOptional": true,
-              "type": "string",
-              "name": "distinctId"
-            },
-            {
-              "description": "Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.",
-              "isOptional": true,
-              "type": "Record<string | number, any>",
-              "name": "additionalProperties"
-            },
-            {
-              "description": "Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events",
+              "description": "Optional distinct id, properties, options, uuid, flags snapshot and level",
               "isOptional": true,
-              "type": "FeatureFlagEvaluations",
-              "name": "flags"
+              "type": "CaptureExceptionOptions",
+              "name": "options"
             }
           ],
           "returnType": {
@@ -1231,30 +1201,31 @@
           "path": "src/entrypoints/index.node.ts"
         },
         {
-          "category": "",
-          "details": null,
+          "category": "Capture",
+          "description": "Build an event as `capture()` would send it, without sending it.",
+          "details": "The result has the same shape as the message passed in: `options` holds the event's options after every layer filled them, and `uuid`, `timestamp` and `disableGeoip` are top-level fields. Rejects with `null` when `before_send` drops the event.",
           "id": "prepareEventMessage",
           "showDocs": true,
           "title": "prepareEventMessage",
           "examples": [
             {
-              "id": "prepareeventmessage",
-              "name": "Generated example for prepareEventMessage",
-              "code": "// Generated example for prepareEventMessage\nposthog.prepareEventMessage();"
+              "id": "",
+              "name": "",
+              "code": "\n\nconst message = await client.prepareEventMessage({ distinctId: 'user_123', event: 'button_clicked' })\nconsole.log(message.properties.$is_server, message.options)\n\n\n\n"
             }
           ],
           "releaseTag": "public",
           "params": [
             {
-              "description": "",
+              "description": "The event to build",
               "isOptional": false,
               "type": "EventMessage",
               "name": "props"
             }
           ],
           "returnType": {
-            "id": "Promise<{\n        distinctId: string;\n        event: string;\n        properties: PostHogEventProperties;\n        options: PostHogCaptureOptions;\n    }>",
-            "name": "Promise<{\n        distinctId: string;\n        event: string;\n        properties: PostHogEventProperties;\n        options: PostHogCaptureOptions;\n    }>"
+            "id": "Promise<PreparedEventMessage>",
+            "name": "Promise<PreparedEventMessage>"
           },
           "path": "src/entrypoints/index.node.ts"
         },
@@ -1298,7 +1269,7 @@
             {
               "id": "",
               "name": "",
-              "code": "\n\nclient.registerOptions({ cookieless_mode: true })\n\n\n\n"
+              "code": "\n\nawait client.registerOptions({ cookieless_mode: true })\n\n\n\n"
             }
           ],
           "releaseTag": "public",
@@ -1311,8 +1282,8 @@
             }
           ],
           "returnType": {
-            "id": "void",
-            "name": "void"
+            "id": "Promise<void>",
+            "name": "Promise<void>"
           },
           "path": "src/entrypoints/index.node.ts"
         },
@@ -1506,8 +1477,8 @@
             }
           ],
           "returnType": {
-            "id": "void",
-            "name": "void"
+            "id": "Promise<void>",
+            "name": "Promise<void>"
           },
           "path": "src/entrypoints/index.node.ts"
         },
@@ -2162,6 +2133,43 @@
       ],
       "path": "../core/src/types.ts"
     },
+    {
+      "id": "CaptureExceptionOptions",
+      "name": "CaptureExceptionOptions",
+      "properties": [
+        {
+          "description": "The event's distinct id. Without one, the context distinct id is used, else a personless id.",
+          "type": "string",
+          "name": "distinctId"
+        },
+        {
+          "description": "Properties to add to the event. Exception properties the SDK or PostHog owns, such as\n`$exception_list` and `$exception_level`, are ignored: use `level` to set the level.",
+          "type": "Record<string | number, any>",
+          "name": "properties"
+        },
+        {
+          "description": "Per-event options, as in `capture()`.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
+        },
+        {
+          "description": "Overrides the generated event UUID. Must be a valid UUID.",
+          "type": "string",
+          "name": "uuid"
+        },
+        {
+          "description": "A `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events.",
+          "type": "FeatureFlagEvaluations",
+          "name": "flags"
+        },
+        {
+          "description": "The exception's severity, sent as `$exception_level`. An unknown value is ignored.",
+          "type": "\"fatal\" | \"error\" | \"warning\" | \"log\" | \"info\" | \"debug\"",
+          "name": "level"
+        }
+      ],
+      "path": "src/types.ts"
+    },
     {
       "id": "ChunkIdMapType",
       "name": "ChunkIdMapType",
@@ -3599,7 +3607,7 @@
           "name": "signal"
         },
         {
-          "type": "\"follow\" | \"manual\" | \"error\"",
+          "type": "\"error\" | \"follow\" | \"manual\"",
           "name": "redirect"
         }
       ],
@@ -4185,6 +4193,42 @@
       ],
       "path": "../core/src/types.ts"
     },
+    {
+      "id": "PreparedEventMessage",
+      "name": "PreparedEventMessage",
+      "properties": [
+        {
+          "type": "string",
+          "name": "distinctId"
+        },
+        {
+          "type": "string",
+          "name": "event"
+        },
+        {
+          "type": "PostHogEventProperties",
+          "name": "properties"
+        },
+        {
+          "description": "The event's options, sent to capture unchanged.",
+          "type": "Record<string, JsonType>",
+          "name": "options"
+        },
+        {
+          "type": "string",
+          "name": "uuid"
+        },
+        {
+          "type": "Date",
+          "name": "timestamp"
+        },
+        {
+          "type": "boolean",
+          "name": "disableGeoip"
+        }
+      ],
+      "path": "src/types.ts"
+    },
     {
       "id": "PreviouslyCapturedError",
       "name": "PreviouslyCapturedError",
@@ -4432,7 +4476,7 @@
           "name": "prefix"
         },
         {
-          "type": "(\"error\" | \"fatal\" | \"warning\" | \"log\" | \"info\" | \"debug\")[] | \"*\"",
+          "type": "(\"fatal\" | \"error\" | \"warning\" | \"log\" | \"info\" | \"debug\")[] | \"*\"",
           "name": "severityAllowList"
         },
         {
diff --git a/packages/node/src/__tests__/capture-v1/layers.spec.ts b/packages/node/src/__tests__/capture-v1/layers.spec.ts
index 3392ff6a15..7da5ce69ca 100644
--- a/packages/node/src/__tests__/capture-v1/layers.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/layers.spec.ts
@@ -1,6 +1,7 @@
 import type { JsonType } from '@posthog/core'
 
-import { EventMessage, PostHog, PostHogOptions } from '@/entrypoints/index.node'
+import { _resetDeprecationWarningsForTests } from '@/client'
+import { CaptureExceptionOptions, EventMessage, PostHog, PostHogOptions } from '@/entrypoints/index.node'
 import { FeatureFlagEvaluations } from '@/feature-flag-evaluations'
 import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, apiImplementationV4, captureEvents } from '../utils'
 import { V1WiringHarness } from '../utils/v1-wiring'
@@ -82,9 +83,9 @@ describe('layered event values', () => {
 
   /** Captures one event with options from the event, a context and `registerOptions()`. */
   const captureWithOptionLayers = (layers: Layers, message: Partial<EventMessage> = {}) =>
-    sendOne((client) => {
+    sendOne(async (client) => {
       if (layers.global) {
-        client.registerOptions(layers.global)
+        await client.registerOptions(layers.global)
       }
       const capture = (): void =>
         client.capture({ distinctId: 'u', event: 'e', ...message, options: layers.event ?? message.options })
@@ -303,7 +304,7 @@ describe('layered event values', () => {
 
         it('loses to captureException properties', async () => {
           const event = await sendOne((client) =>
-            client.captureException(new Error('boom'), 'u', { $release_id: 'mine' })
+            client.captureException(new Error('boom'), { distinctId: 'u', properties: { $release_id: 'mine' } })
           )
 
           expect(event.properties.$release_id).toBe('mine')
@@ -377,7 +378,7 @@ describe('layered event values', () => {
           $window_id: 'window',
           dropped: 'yes',
         })
-        client.registerOptions({ future_option: 1 })
+        await client.registerOptions({ future_option: 1 })
         await client.withContext({ sessionId: 'session' }, () => client.getFeatureFlag('test-flag', 'u'))
       })
 
@@ -436,8 +437,8 @@ describe('layered event values', () => {
     it('before_send sees the filled options and can remove one', async () => {
       const seen: EventMessage[] = []
       const event = await sendOne(
-        (client) => {
-          client.registerOptions({ cookieless_mode: true, product_tour_id: 'tour' })
+        async (client) => {
+          await client.registerOptions({ cookieless_mode: true, product_tour_id: 'tour' })
           client.capture({ distinctId: 'u', event: 'e' })
         },
         {
@@ -455,10 +456,10 @@ describe('layered event values', () => {
 
     describe('registerOptions', () => {
       it('merges calls, and unregisterOptions removes one key', async () => {
-        const event = await sendOne((client) => {
-          client.registerOptions({ a: 1, b: 2 })
-          client.registerOptions({ b: 3, c: 4 })
-          client.unregisterOptions('a')
+        const event = await sendOne(async (client) => {
+          await expect(client.registerOptions({ a: 1, b: 2 })).resolves.toBeUndefined()
+          await client.registerOptions({ b: 3, c: 4 })
+          await expect(client.unregisterOptions('a')).resolves.toBeUndefined()
           client.capture({ distinctId: 'u', event: 'e' })
         })
 
@@ -466,11 +467,11 @@ describe('layered event values', () => {
       })
 
       it('an event keeps the options it read when it was captured', async () => {
-        const event = await sendOne((client) => {
-          client.registerOptions({ a: 1 })
+        const event = await sendOne(async (client) => {
+          await client.registerOptions({ a: 1 })
           client.capture({ distinctId: 'u', event: 'e' })
-          client.registerOptions({ a: 2 })
-          client.unregisterOptions('a')
+          await client.registerOptions({ a: 2 })
+          await client.unregisterOptions('a')
         })
 
         expect(event.options).toStrictEqual({ a: 1 })
@@ -482,9 +483,9 @@ describe('layered event values', () => {
         ['a number', 1],
         ['null', null],
       ])('logs one error for %s and ignores it', async (_label, value) => {
-        const event = await sendOne((client) => {
-          client.registerOptions({ kept: true })
-          client.registerOptions(value as Record<string, JsonType>)
+        const event = await sendOne(async (client) => {
+          await client.registerOptions({ kept: true })
+          await client.registerOptions(value as Record<string, JsonType>)
           client.capture({ distinctId: 'u', event: 'e' })
         })
 
@@ -641,7 +642,7 @@ describe('layered event values', () => {
     it.each<[string, (client: PostHog) => unknown, string]>([
       ['capture', (c) => c.capture({ distinctId: 'u', event: 'e' }), ANALYTICS_CAPTURE_PATH],
       ['captureAi', (c) => c.captureAi({ distinctId: 'u', event: '$ai_span' }), AI_CAPTURE_PATH],
-      ['captureException', (c) => c.captureException(new Error('boom'), 'u'), ANALYTICS_CAPTURE_PATH],
+      ['captureException', (c) => c.captureException(new Error('boom'), { distinctId: 'u' }), ANALYTICS_CAPTURE_PATH],
       ['identify', (c) => c.identify({ distinctId: 'u', properties: { a: 1 } }), ANALYTICS_CAPTURE_PATH],
       ['identifyImmediate', (c) => c.identifyImmediate({ distinctId: 'u' }), ANALYTICS_CAPTURE_PATH],
       ['alias', (c) => c.alias({ distinctId: 'u', alias: 'anon' }), ANALYTICS_CAPTURE_PATH],
@@ -661,7 +662,7 @@ describe('layered event values', () => {
       const event = await sendOne(
         async (client) => {
           await client.register({ global_prop: 'g' })
-          client.registerOptions({ global_option: 'g' })
+          await client.registerOptions({ global_option: 'g' })
           return client.withContext({ properties: { context_prop: 'c' }, options: { context_option: 'c' } }, () =>
             send(client)
           )
@@ -675,38 +676,178 @@ describe('layered event values', () => {
     })
   })
 
-  describe('captureException properties', () => {
-    it.each([
-      '$exception_source',
-      '$debug_images',
-      '$exception_types',
-      '$exception_values',
-      '$exception_sources',
-      '$exception_functions',
-      '$exception_fingerprint_version',
-      '$exception_fingerprint_record',
-      '$exception_issue_id',
-      '$exception_release',
-      '$cymbal_errors',
-    ])('cannot set %s', async (key) => {
-      const event = await sendOne((client) => client.captureException(new Error('boom'), 'u', { [key]: 'caller' }))
-
-      expect(event.properties).not.toHaveProperty(key)
+  describe('captureException', () => {
+    const EXCEPTION_UUID = '0191c0a2-6f3c-7a8e-9b1d-2c3e4f5a6b7c'
+    const DEPRECATION_ERROR = (method: string): string =>
+      `[PostHog] ${method}(error, distinctId, properties) is deprecated: pass an object instead, e.g. ` +
+      `${method}(error, { distinctId, properties }). The old form will be removed in the next major version.`
+
+    /** The client typed with the 5.x positional signatures, which only work at runtime. */
+    const legacy = (
+      client: PostHog
+    ): {
+      captureException(error: unknown, ...args: unknown[]): void
+      captureExceptionImmediate(error: unknown, ...args: unknown[]): Promise<void>
+    } => client as any
+
+    beforeEach(() => {
+      _resetDeprecationWarningsForTests()
     })
 
-    it('cannot replace $exception_list or $exception_level, and keep other properties', async () => {
+    it.each<[string, (client: PostHog, options: CaptureExceptionOptions) => unknown]>([
+      ['captureException', (c, options) => c.captureException(new Error('boom'), options)],
+      ['captureExceptionImmediate', (c, options) => c.captureExceptionImmediate(new Error('boom'), options)],
+    ])('%s sends every field of the options object', async (_method, send) => {
       const event = await sendOne((client) =>
-        client.captureException(new Error('boom'), 'u', {
-          $exception_list: 'caller',
-          $exception_level: 'fatal',
-          $exception_fingerprint: 'custom',
-          custom: 1,
+        send(client, {
+          distinctId: 'u',
+          properties: { custom: 1 },
+          options: { product_tour_id: 'tour' },
+          uuid: EXCEPTION_UUID,
+          flags: flagSnapshot(),
+          level: 'warning',
         })
       )
 
+      expect(event).toMatchObject({ event: '$exception', distinct_id: 'u', uuid: EXCEPTION_UUID })
+      expect(event.options).toStrictEqual({ product_tour_id: 'tour' })
+      expect(event.properties).toMatchObject({
+        custom: 1,
+        '$feature/x': 'v',
+        $active_feature_flags: ['x'],
+        $exception_level: 'warning',
+      })
       expect(event.properties.$exception_list[0]).toMatchObject({ type: 'Error', value: 'boom' })
-      expect(event.properties.$exception_level).toBe('error')
-      expect(event.properties).toMatchObject({ $exception_fingerprint: 'custom', custom: 1 })
+      expect(console.error).not.toHaveBeenCalled()
+    })
+
+    it.each<[string, CaptureExceptionOptions | undefined, string]>([
+      ['no options', undefined, 'error'],
+      ['no level', { distinctId: 'u' }, 'error'],
+      ['level fatal', { level: 'fatal' }, 'fatal'],
+      ['level debug', { level: 'debug' }, 'debug'],
+      ['an alias of fatal', { level: 'critical' as CaptureExceptionOptions['level'] }, 'fatal'],
+      ['an upper-case level', { level: 'WARNING' as CaptureExceptionOptions['level'] }, 'warning'],
+      ['an alias of warning', { level: 'warn' as CaptureExceptionOptions['level'] }, 'warning'],
+      ['an unknown level', { level: 'bogus' as CaptureExceptionOptions['level'] }, 'error'],
+      ['level with a $exception_level property', { level: 'info', properties: { $exception_level: 'fatal' } }, 'info'],
+    ])('sends $exception_level for %s', async (_label, options, expected) => {
+      const event = await sendOne((client) => client.captureException(new Error('boom'), options))
+
+      expect(event.properties.$exception_level).toBe(expected)
+    })
+
+    it('an event with no distinct id is personless', async () => {
+      const event = await sendOne((client) => client.captureException(new Error('boom'), { properties: { a: 1 } }))
+
+      expect(event.distinct_id).toMatch(UUID_V7)
+      expect(event.options).toStrictEqual({ process_person_profile: false })
+      expect(event.properties.a).toBe(1)
+    })
+
+    describe('the 5.x positional form', () => {
+      it('captureException(error, distinctId, properties, uuid, flags) still sends every value', async () => {
+        const event = await sendOne((client) =>
+          legacy(client).captureException(new Error('boom'), 'u', { custom: 1 }, EXCEPTION_UUID, flagSnapshot())
+        )
+
+        expect(event).toMatchObject({ distinct_id: 'u', uuid: EXCEPTION_UUID })
+        expect(event.properties).toMatchObject({ custom: 1, '$feature/x': 'v', $exception_level: 'error' })
+        expect(console.error).toHaveBeenCalledTimes(1)
+        expect(console.error).toHaveBeenCalledWith(DEPRECATION_ERROR('captureException'))
+      })
+
+      it('captureExceptionImmediate(error, distinctId, properties, flags) still sends every value', async () => {
+        const event = await sendOne((client) =>
+          legacy(client).captureExceptionImmediate(new Error('boom'), 'u', { custom: 1 }, flagSnapshot())
+        )
+
+        expect(event.distinct_id).toBe('u')
+        expect(event.properties).toMatchObject({ custom: 1, '$feature/x': 'v' })
+        expect(console.error).toHaveBeenCalledWith(DEPRECATION_ERROR('captureExceptionImmediate'))
+      })
+
+      it('an undefined distinct id with properties still sends the properties', async () => {
+        const event = await sendOne((client) =>
+          legacy(client).captureException(new Error('boom'), undefined, { custom: 1 })
+        )
+
+        expect(event.distinct_id).toMatch(UUID_V7)
+        expect(event.properties.custom).toBe(1)
+        expect(console.error).toHaveBeenCalledTimes(1)
+      })
+
+      it('logs the deprecation error once per method per process', async () => {
+        const client = harness.makeClient()
+        legacy(client).captureException(new Error('one'), 'u')
+        legacy(client).captureException(new Error('two'), 'u', { a: 1 })
+        await legacy(client).captureExceptionImmediate(new Error('three'), 'u')
+        await legacy(client).captureExceptionImmediate(new Error('four'), 'u')
+        await client.flush()
+
+        expect(wireEvents()).toHaveLength(4)
+        expect((console.error as vi.Mock).mock.calls).toEqual([
+          [DEPRECATION_ERROR('captureException')],
+          [DEPRECATION_ERROR('captureExceptionImmediate')],
+        ])
+      })
+
+      it('warns once when arguments follow the options object, and ignores them', async () => {
+        const client = harness.makeClient()
+        legacy(client).captureException(new Error('one'), { distinctId: 'u' }, { ignored: 1 })
+        legacy(client).captureException(new Error('two'), { distinctId: 'u' }, { ignored: 2 })
+        await client.flush()
+
+        const events = wireEvents()
+        expect(events.map((event) => event.distinct_id)).toEqual(['u', 'u'])
+        expect(events.every((event) => !('ignored' in event.properties))).toBe(true)
+        expect(console.warn).toHaveBeenCalledWith(
+          '[PostHog] captureException(error, options) ignores the arguments after the options object.'
+        )
+        expect(
+          (console.warn as vi.Mock).mock.calls.filter((call) => String(call[0]).includes('ignores the arguments'))
+        ).toHaveLength(1)
+      })
+    })
+
+    describe('reserved properties', () => {
+      it.each([
+        '$exception_source',
+        '$debug_images',
+        '$exception_types',
+        '$exception_values',
+        '$exception_sources',
+        '$exception_functions',
+        '$exception_fingerprint_version',
+        '$exception_fingerprint_record',
+        '$exception_issue_id',
+        '$exception_release',
+        '$cymbal_errors',
+      ])('cannot set %s', async (key) => {
+        const event = await sendOne((client) =>
+          client.captureException(new Error('boom'), { distinctId: 'u', properties: { [key]: 'caller' } })
+        )
+
+        expect(event.properties).not.toHaveProperty(key)
+      })
+
+      it('cannot replace $exception_list or $exception_level, and keep other properties', async () => {
+        const event = await sendOne((client) =>
+          client.captureException(new Error('boom'), {
+            distinctId: 'u',
+            properties: {
+              $exception_list: 'caller',
+              $exception_level: 'fatal',
+              $exception_fingerprint: 'custom',
+              custom: 1,
+            },
+          })
+        )
+
+        expect(event.properties.$exception_list[0]).toMatchObject({ type: 'Error', value: 'boom' })
+        expect(event.properties.$exception_level).toBe('error')
+        expect(event.properties).toMatchObject({ $exception_fingerprint: 'custom', custom: 1 })
+      })
     })
   })
 })
diff --git a/packages/node/src/__tests__/context.spec.ts b/packages/node/src/__tests__/context.spec.ts
index 909d3e2581..eb31efceb8 100644
--- a/packages/node/src/__tests__/context.spec.ts
+++ b/packages/node/src/__tests__/context.spec.ts
@@ -475,7 +475,7 @@ describe('PostHog Context', () => {
   ])(
     'captureException $label',
     async ({ contextDistinctId, explicitDistinctId, expectedDistinctId, expectedProcessPersonProfile }) => {
-      const run = () => posthog.captureException(new Error('test error'), explicitDistinctId)
+      const run = () => posthog.captureException(new Error('test error'), { distinctId: explicitDistinctId })
       contextDistinctId ? posthog.withContext({ distinctId: contextDistinctId }, run) : run()
 
       // captureException uses addPendingPromise around an async buildEventMessage that
diff --git a/packages/node/src/__tests__/evaluate-flags.spec.ts b/packages/node/src/__tests__/evaluate-flags.spec.ts
index 45869b9247..1e3c601eec 100644
--- a/packages/node/src/__tests__/evaluate-flags.spec.ts
+++ b/packages/node/src/__tests__/evaluate-flags.spec.ts
@@ -464,7 +464,7 @@ describe('evaluateFlags', () => {
       const flags = await posthog.evaluateFlags('user-1')
       flags.isEnabled('boolean-flag')
 
-      posthog.captureException(new Error('boom'), 'user-1', undefined, undefined, flags.onlyAccessed())
+      posthog.captureException(new Error('boom'), { distinctId: 'user-1', flags: flags.onlyAccessed() })
 
       await posthog.flush()
 
@@ -484,7 +484,7 @@ describe('evaluateFlags', () => {
       const filtered = flags.only(['boolean-flag'])
       const spy = vi.spyOn(posthog, 'captureImmediate').mockResolvedValue(undefined)
 
-      await posthog.captureExceptionImmediate(new Error('boom'), 'user-1', undefined, filtered)
+      await posthog.captureExceptionImmediate(new Error('boom'), { distinctId: 'user-1', flags: filtered })
       await waitForPromises()
 
       expect(spy).toHaveBeenCalledTimes(1)
diff --git a/packages/node/src/__tests__/extensions/exception-trace-context.spec.ts b/packages/node/src/__tests__/extensions/exception-trace-context.spec.ts
index c140febc59..fb59571724 100644
--- a/packages/node/src/__tests__/extensions/exception-trace-context.spec.ts
+++ b/packages/node/src/__tests__/extensions/exception-trace-context.spec.ts
@@ -121,7 +121,7 @@ describe('exception trace context', () => {
     client.on('capture', (event) => events.push(event))
 
     await withSpan({ traceId, spanId, traceFlags: TraceFlags.SAMPLED }, async () => {
-      client.captureException(new Error('boom'), 'user-1')
+      client.captureException(new Error('boom'), { distinctId: 'user-1' })
       await client.flush()
     })
 
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index 36b310932a..beaebf8249 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -127,7 +127,7 @@ describe('PostHog Node.js', () => {
       })
 
       try {
-        posthog.captureException(new Error('boom'), 'user-1')
+        posthog.captureException(new Error('boom'), { distinctId: 'user-1' })
         const flushPromise = posthog.flush()
         expect(mockedFetch).not.toHaveBeenCalled()
 
diff --git a/packages/node/src/__tests__/prepare-event-message.spec.ts b/packages/node/src/__tests__/prepare-event-message.spec.ts
index 20df725610..1c24261992 100644
--- a/packages/node/src/__tests__/prepare-event-message.spec.ts
+++ b/packages/node/src/__tests__/prepare-event-message.spec.ts
@@ -13,6 +13,32 @@ describe('PostHog.prepareEventMessage', () => {
     await posthog.shutdown()
   })
 
+  it('returns the message shape, with the filled options and top-level uuid, timestamp and disableGeoip', async () => {
+    const timestamp = new Date('2026-01-02T03:04:05Z')
+    const uuid = '0191c0a2-6f3c-7a8e-9b1d-2c3e4f5a6b7c'
+    await posthog.registerOptions({ cookieless_mode: true })
+
+    const message = await posthog.prepareEventMessage({
+      distinctId: 'user_1',
+      event: 'test_event',
+      properties: { plan: 'pro' },
+      options: { product_tour_id: 'tour' },
+      uuid,
+      timestamp,
+      disableGeoip: false,
+    })
+
+    expect(message).toStrictEqual({
+      distinctId: 'user_1',
+      event: 'test_event',
+      properties: { plan: 'pro', $geoip_disable: false, $is_server: true },
+      options: { product_tour_id: 'tour', cookieless_mode: true },
+      uuid,
+      timestamp,
+      disableGeoip: false,
+    })
+  })
+
   it('should NOT include $groups if groups is undefined', async () => {
     const message = await posthog.prepareEventMessage({
       distinctId: 'user_1',
diff --git a/packages/node/src/__tests__/server-wire-snapshots.spec.ts b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
index 4e790bff0e..780967f323 100644
--- a/packages/node/src/__tests__/server-wire-snapshots.spec.ts
+++ b/packages/node/src/__tests__/server-wire-snapshots.spec.ts
@@ -155,16 +155,15 @@ describe('server wire snapshots', () => {
       '    at handler (service/src/handler.ts:12:5)',
     ].join('\n')
 
-    posthog.captureException(
-      error,
-      'person-exception',
-      {
+    posthog.captureException(error, {
+      distinctId: 'person-exception',
+      properties: {
         endpoint: '/v1/orders',
         request: { method: 'POST', tags: ['checkout', 'priority'] },
         status_code: 503,
       },
-      FIXED_EVENT_UUID
-    )
+      uuid: FIXED_EVENT_UUID,
+    })
     await (posthog as any).promiseQueue.join()
     await posthog.flush()
 
diff --git a/packages/node/src/__tests__/types/public-interface.ts b/packages/node/src/__tests__/types/public-interface.ts
index 14a88a62c4..41e7f0c409 100644
--- a/packages/node/src/__tests__/types/public-interface.ts
+++ b/packages/node/src/__tests__/types/public-interface.ts
@@ -3,8 +3,10 @@ import type { IPostHog, PostHog } from '../../entrypoints/index.node'
 export function checkPublicInterface(posthog: PostHog): Promise<void> {
   const client: IPostHog = posthog
   client.metrics.count('jobs.processed', 1)
+  client.captureException(new Error('queued exception'), { distinctId: 'user', level: 'warning' })
+  // @ts-expect-error The 5.x positional form only works at runtime.
   client.captureException(new Error('queued exception'), 'user')
   client.alias({ distinctId: 'user', alias: 'anonymous', options: { cookieless_mode: true } })
   void client.aliasImmediate({ distinctId: 'user', alias: 'anonymous', options: { cookieless_mode: true } })
-  return client.captureExceptionImmediate(new Error('immediate exception'), 'user')
+  return client.captureExceptionImmediate(new Error('immediate exception'), { distinctId: 'user' })
 }
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index e58e045529..6efda2ff9f 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -38,6 +38,7 @@ import type {
 } from '@posthog/core'
 import {
   AllFlagsOptions,
+  CaptureExceptionOptions,
   EventMessage,
   FeatureFlagError,
   FeatureFlagErrorType,
@@ -50,6 +51,7 @@ import {
   IPostHog,
   OverrideFeatureFlagsOptions,
   PostHogOptions,
+  PreparedEventMessage,
   SendFeatureFlagsOptions,
   SetPersonPropertiesMessage,
   UnsetPersonPropertiesMessage,
@@ -96,12 +98,12 @@ const DEFAULT_NODE_HOST = 'https://us.i.posthog.com'
 // method in a loop would spam logs. Matches Python's `warnings.warn` default-dedup behavior.
 const _emittedDeprecations = new Set<string>()
 
-function emitDeprecationWarningOnce(id: string, message: string): void {
+function emitDeprecationWarningOnce(id: string, message: string, log: (message: string) => void = console.warn): void {
   if (_emittedDeprecations.has(id)) {
     return
   }
   _emittedDeprecations.add(id)
-  console.warn(`[PostHog] ${message}`)
+  log(`[PostHog] ${message}`)
 }
 
 /**
@@ -146,6 +148,43 @@ const FLAG_CALLED_OPTION_SOURCE_PROPERTIES = [
   '$window_id',
 ]
 
+/**
+ * The options of a `captureException()` or `captureExceptionImmediate()` call. A string second
+ * argument, or extra arguments after one that is not an object, is the 5.x positional form
+ * `(error, distinctId, properties, uuid, flags)` (no `uuid` for the immediate variant): it still
+ * works and logs one deprecation error per process.
+ */
+function readCaptureExceptionArgs(
+  method: string,
+  second: unknown,
+  rest: unknown[],
+  legacyHasUuid: boolean
+): CaptureExceptionOptions {
+  if (typeof second !== 'string' && (rest.length === 0 || isPlainObject(second))) {
+    if (rest.length > 0) {
+      emitDeprecationWarningOnce(
+        `${method} extra arguments`,
+        `${method}(error, options) ignores the arguments after the options object.`
+      )
+    }
+    return isPlainObject(second) ? (second as CaptureExceptionOptions) : {}
+  }
+  emitDeprecationWarningOnce(
+    `${method} positional arguments`,
+    `${method}(error, distinctId, properties) is deprecated: pass an object instead, e.g. ` +
+      `${method}(error, { distinctId, properties }). The old form will be removed in the next major version.`,
+    console.error
+  )
+  const [properties, ...tail] = rest
+  const [uuid, flags] = legacyHasUuid ? tail : [undefined, tail[0]]
+  return {
+    distinctId: (second ?? undefined) as string | undefined,
+    properties: properties as CaptureExceptionOptions['properties'],
+    uuid: uuid as string | undefined,
+    flags: flags as FeatureFlagEvaluations | undefined,
+  }
+}
+
 /**
  * A copy of the event for `before_send`, so a hook that mutates it cannot change the caller's
  * objects or the `register()` and context defaults. Plain objects and arrays are copied all the
@@ -1184,19 +1223,19 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     }
     return this.addPendingPromise(
       this._prepareEventMessage(props, prepareOptions)
-        .then(({ distinctId, event, properties, options, eventOptions }) => {
+        .then(({ distinctId, event, properties, options, uuid, timestamp }) => {
           const captureOptions: LaneCaptureOptions = {
-            timestamp: options.timestamp,
+            timestamp,
             // `$geoip_disable` is already set before before_send; core must not add it after.
             disableGeoip: false,
-            uuid: options.uuid,
+            uuid,
             _invalidUuidWarned: invalidUuidWarned,
           }
           const message = {
             distinctId,
             event,
             properties,
-            ...(eventOptions !== undefined ? { options: eventOptions } : {}),
+            ...(options !== undefined ? { options } : {}),
           }
           return immediate
             ? this.sendImmediate(type, message, captureOptions, explicitRoute)
@@ -3069,14 +3108,14 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @example
    * ```ts
-   * client.registerOptions({ cookieless_mode: true })
+   * await client.registerOptions({ cookieless_mode: true })
    * ```
    *
    * {@label Capture}
    *
    * @param options - The options to add to every event
    */
-  registerOptions(options: Record<string, JsonType>): void {
+  async registerOptions(options: Record<string, JsonType>): Promise<void> {
     if (!isPlainObject(options)) {
       // console.error, not this._logger: the logger only prints in debug mode, and the options are lost.
       console.error('[PostHog] registerOptions takes an object; ignoring the value')
@@ -3092,7 +3131,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *
    * @param key - The option name to remove
    */
-  unregisterOptions(key: string): void {
+  async unregisterOptions(key: string): Promise<void> {
     const remaining = { ...this._globalOptions }
     delete remaining[key]
     this._globalOptions = remaining
@@ -3429,6 +3468,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   /**
    * Capture an error exception as an event.
    *
+   * @remarks
+   * The 5.x positional form `captureException(error, distinctId, properties, uuid, flags)` still
+   * works in 6.x but logs a deprecation error once per process, and will be removed in the next
+   * major version.
+   *
    * @example
    * ```ts
    * // Capture an error with user ID
@@ -3436,20 +3480,20 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *   // Some risky operation
    *   riskyOperation()
    * } catch (error) {
-   *   client.captureException(error, 'user_123')
+   *   client.captureException(error, { distinctId: 'user_123' })
    * }
    * ```
    *
    * @example
    * ```ts
-   * // Capture with additional properties
+   * // Capture with additional properties and a level
    * try {
    *   apiCall()
    * } catch (error) {
-   *   client.captureException(error, 'user_123', {
-   *     endpoint: '/api/users',
-   *     method: 'POST',
-   *     status_code: 500
+   *   client.captureException(error, {
+   *     distinctId: 'user_123',
+   *     properties: { endpoint: '/api/users', method: 'POST', status_code: 500 },
+   *     level: 'warning',
    *   })
    * }
    * ```
@@ -3457,28 +3501,17 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * {@label Error tracking}
    *
    * @param error - The error to capture
-   * @param distinctId - Optional user distinct ID
-   * @param additionalProperties - Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.
-   * @param uuid - Optional event UUID
-   * @param flags - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
+   * @param options - Optional distinct id, properties, options, uuid, flags snapshot and level
    */
-  captureException(
-    error: unknown,
-    distinctId?: string,
-    additionalProperties?: Record<string | number, any>,
-    uuid?: EventMessage['uuid'],
-    flags?: FeatureFlagEvaluations
-  ): void {
+  captureException(error: unknown, options?: CaptureExceptionOptions): void
+  captureException(error: unknown, options?: unknown, ...legacyArgs: unknown[]): void {
+    const exceptionOptions = readCaptureExceptionArgs('captureException', options, legacyArgs, true)
     if (!ErrorTracking.isPreviouslyCapturedError(error)) {
       const syntheticException = new Error('PostHog syntheticException')
       this.addPendingPromise(
-        ErrorTracking.buildEventMessage(
-          this.getErrorPropertiesBuilder(),
-          error,
-          { syntheticException },
-          distinctId,
-          additionalProperties
-        ).then((msg) => this._capturePreparedEvent({ ...msg, uuid, flags }, false))
+        this._buildExceptionEvent(error, syntheticException, exceptionOptions).then((msg) =>
+          this._capturePreparedEvent(msg, false)
+        )
       )
     }
   }
@@ -3486,6 +3519,11 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   /**
    * Capture an error exception as an event immediately (synchronously).
    *
+   * @remarks
+   * The 5.x positional form `captureExceptionImmediate(error, distinctId, properties, flags)` still
+   * works in 6.x but logs a deprecation error once per process, and will be removed in the next
+   * major version.
+   *
    * @example
    * ```ts
    * // Capture an error immediately with user ID
@@ -3493,7 +3531,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    *   // Some risky operation
    *   riskyOperation()
    * } catch (error) {
-   *   await client.captureExceptionImmediate(error, 'user_123')
+   *   await client.captureExceptionImmediate(error, { distinctId: 'user_123' })
    * }
    * ```
    *
@@ -3503,10 +3541,9 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * try {
    *   apiCall()
    * } catch (error) {
-   *   await client.captureExceptionImmediate(error, 'user_123', {
-   *     endpoint: '/api/users',
-   *     method: 'POST',
-   *     status_code: 500
+   *   await client.captureExceptionImmediate(error, {
+   *     distinctId: 'user_123',
+   *     properties: { endpoint: '/api/users', method: 'POST', status_code: 500 },
    *   })
    * }
    * ```
@@ -3514,37 +3551,56 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    * {@label Error tracking}
    *
    * @param error - The error to capture
-   * @param distinctId - Optional user distinct ID
-   * @param additionalProperties - Optional additional properties to include. Exception properties the SDK or PostHog owns, such as `$exception_list` and `$exception_level`, are ignored.
-   * @param flags - Optional `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events
+   * @param options - Optional distinct id, properties, options, uuid, flags snapshot and level
    * @returns Promise that resolves when the error is captured
    */
-  async captureExceptionImmediate(
-    error: unknown,
-    distinctId?: string,
-    additionalProperties?: Record<string | number, any>,
-    flags?: FeatureFlagEvaluations
-  ): Promise<void> {
+  captureExceptionImmediate(error: unknown, options?: CaptureExceptionOptions): Promise<void>
+  async captureExceptionImmediate(error: unknown, options?: unknown, ...legacyArgs: unknown[]): Promise<void> {
+    const exceptionOptions = readCaptureExceptionArgs('captureExceptionImmediate', options, legacyArgs, false)
     if (!ErrorTracking.isPreviouslyCapturedError(error)) {
       const syntheticException = new Error('PostHog syntheticException')
       return this.addPendingPromise(
-        ErrorTracking.buildEventMessage(
-          this.getErrorPropertiesBuilder(),
-          error,
-          { syntheticException },
-          distinctId,
-          additionalProperties
-        ).then((msg) => this.captureImmediate({ ...msg, flags }))
+        this._buildExceptionEvent(error, syntheticException, exceptionOptions).then((msg) => this.captureImmediate(msg))
       )
     }
   }
 
-  public async prepareEventMessage(props: EventMessage): Promise<{
-    distinctId: string
-    event: string
-    properties: PostHogEventProperties
-    options: PostHogCaptureOptions
-  }> {
+  private async _buildExceptionEvent(
+    error: unknown,
+    syntheticException: Error,
+    { distinctId, properties, options, uuid, flags, level }: CaptureExceptionOptions
+  ): Promise<EventMessage> {
+    const msg = await ErrorTracking.buildEventMessage(
+      this.getErrorPropertiesBuilder(),
+      error,
+      { syntheticException },
+      distinctId,
+      properties,
+      level
+    )
+    return { ...msg, options, uuid, flags }
+  }
+
+  /**
+   * Build an event as `capture()` would send it, without sending it.
+   *
+   * @remarks
+   * The result has the same shape as the message passed in: `options` holds the event's options
+   * after every layer filled them, and `uuid`, `timestamp` and `disableGeoip` are top-level fields.
+   * Rejects with `null` when `before_send` drops the event.
+   *
+   * @example
+   * ```ts
+   * const message = await client.prepareEventMessage({ distinctId: 'user_123', event: 'button_clicked' })
+   * console.log(message.properties.$is_server, message.options)
+   * ```
+   *
+   * {@label Capture}
+   *
+   * @param props - The event to build
+   * @returns The event with its properties and options filled, after `before_send`
+   */
+  public async prepareEventMessage(props: EventMessage): Promise<PreparedEventMessage> {
     return this._prepareEventMessage(props)
   }
 
@@ -3556,14 +3612,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   private async _prepareEventMessage(
     props: EventMessage,
     prepareOptions: PrepareEventOptions = {}
-  ): Promise<{
-    distinctId: string
-    event: string
-    properties: PostHogEventProperties
-    options: PostHogCaptureOptions
-    /** The event's `options` map, sent to capture unchanged. */
-    eventOptions?: Record<string, JsonType>
-  }> {
+  ): Promise<PreparedEventMessage> {
     const {
       distinctId,
       event,
@@ -3663,12 +3712,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       distinctId: eventMessage.distinctId!,
       event: eventMessage.event,
       properties: eventMessage.properties || {},
-      options: {
-        timestamp: eventMessage.timestamp,
-        disableGeoip: eventMessage.disableGeoip,
-        uuid: eventMessage.uuid,
-      },
-      eventOptions: eventMessage.options,
+      options: eventMessage.options,
+      uuid: eventMessage.uuid,
+      timestamp: eventMessage.timestamp,
+      disableGeoip: eventMessage.disableGeoip,
     }
   }
 
diff --git a/packages/node/src/extensions/error-tracking/index.ts b/packages/node/src/extensions/error-tracking/index.ts
index baed69c0d8..f0269be657 100644
--- a/packages/node/src/extensions/error-tracking/index.ts
+++ b/packages/node/src/extensions/error-tracking/index.ts
@@ -28,6 +28,25 @@ const RESERVED_EXCEPTION_PROPERTIES: ReadonlySet<string> = new Set([
   '$cymbal_errors',
 ])
 
+/**
+ * The `$exception_level` values a caller may set (sdk-specs `exception-event-metadata`), read
+ * case-insensitively with the same aliases as posthog-python. Any other value keeps the default.
+ */
+const EXCEPTION_LEVELS: ReadonlyMap<string, CoreErrorTracking.SeverityLevel> = new Map([
+  ['fatal', 'fatal'],
+  ['critical', 'fatal'],
+  ['alert', 'fatal'],
+  ['emergency', 'fatal'],
+  ['error', 'error'],
+  ['warning', 'warning'],
+  ['warn', 'warning'],
+  ['log', 'log'],
+  ['notice', 'info'],
+  ['info', 'info'],
+  ['trace', 'debug'],
+  ['debug', 'debug'],
+])
+
 export default class ErrorTracking {
   private client: PostHogBackendClient
   private _exceptionAutocaptureEnabled: boolean
@@ -67,7 +86,8 @@ export default class ErrorTracking {
     error: unknown,
     hint: CoreErrorTracking.EventHint,
     distinctId?: string,
-    additionalProperties?: Record<string | number, any>
+    additionalProperties?: Record<string | number, any>,
+    level?: CoreErrorTracking.SeverityLevel
   ): Promise<EventMessage> {
     const properties: EventMessage['properties'] = {}
     for (const [key, value] of Object.entries(additionalProperties ?? {})) {
@@ -78,6 +98,10 @@ export default class ErrorTracking {
 
     const exceptionProperties = builder.buildFromUnknown(error, hint)
     exceptionProperties.$exception_list = await builder.modifyFrames(exceptionProperties.$exception_list)
+    const exceptionLevel = typeof level === 'string' ? EXCEPTION_LEVELS.get(level.toLowerCase()) : undefined
+    if (exceptionLevel !== undefined) {
+      exceptionProperties.$exception_level = exceptionLevel
+    }
 
     return {
       event: '$exception',
diff --git a/packages/node/src/extensions/nestjs.ts b/packages/node/src/extensions/nestjs.ts
index cc6d601042..26dc692360 100644
--- a/packages/node/src/extensions/nestjs.ts
+++ b/packages/node/src/extensions/nestjs.ts
@@ -112,9 +112,9 @@ export class PostHogInterceptor implements NestInterceptor {
                   return throwError(() => exception)
                 }
                 const responseStatus = status ?? response?.statusCode
-                const additionalProperties: Record<string, any> | undefined =
+                const properties: Record<string, any> | undefined =
                   responseStatus !== undefined ? { $response_status_code: responseStatus } : undefined
-                this.posthog.captureException(exception, distinctId, additionalProperties)
+                this.posthog.captureException(exception, { distinctId, properties })
                 return throwError(() => exception)
               })
             )
diff --git a/packages/node/src/types.ts b/packages/node/src/types.ts
index b62131bf5f..e6d07ee84a 100644
--- a/packages/node/src/types.ts
+++ b/packages/node/src/types.ts
@@ -1,4 +1,5 @@
 import type {
+  ErrorTracking,
   PostHogCoreOptions,
   ExceptionRateLimiterConfig,
   FeatureFlagValue,
@@ -7,6 +8,7 @@ import type {
   MetricsConfig,
   PostHogFetchOptions,
   PostHogFetchResponse,
+  PostHogEventProperties,
   PostHogFlagsAndPayloadsResponse,
   Properties,
   Span,
@@ -98,6 +100,44 @@ export type EventMessage = Omit<IdentifyMessage, 'distinctId'> & {
   _originatedFromCaptureException?: boolean
 }
 
+/** Options for `captureException()` and `captureExceptionImmediate()`. */
+export type CaptureExceptionOptions = {
+  /** The event's distinct id. Without one, the context distinct id is used, else a personless id. */
+  distinctId?: string
+  /**
+   * Properties to add to the event. Exception properties the SDK or PostHog owns, such as
+   * `$exception_list` and `$exception_level`, are ignored: use `level` to set the level.
+   */
+  properties?: Record<string | number, any>
+  /** Per-event options, as in `capture()`. */
+  options?: Record<string, JsonType>
+  /** Overrides the generated event UUID. Must be a valid UUID. */
+  uuid?: string
+  /** A `FeatureFlagEvaluations` snapshot to attach the same flag context as your other events. */
+  flags?: FeatureFlagEvaluations
+  /**
+   * The exception's severity, sent as `$exception_level`. An unknown value is ignored.
+   *
+   * @default 'error'
+   */
+  level?: ErrorTracking.SeverityLevel
+}
+
+/**
+ * An event as `prepareEventMessage()` builds it: the shape of `EventMessage`, with the distinct id
+ * resolved and the properties and options filled from every layer, after `before_send`.
+ */
+export type PreparedEventMessage = {
+  distinctId: string
+  event: string
+  properties: PostHogEventProperties
+  /** The event's options, sent to capture unchanged. */
+  options?: Record<string, JsonType>
+  uuid?: string
+  timestamp?: Date
+  disableGeoip?: boolean
+}
+
 export type GroupIdentifyMessage = {
   groupType: string
   groupKey: string // Unique identifier for the group
@@ -651,32 +691,16 @@ export interface IPostHog {
   /**
    * @description Capture an exception as a $exception event.
    * @param error The error to capture.
-   * @param distinctId Optional user distinct ID.
-   * @param additionalProperties Optional additional properties to include.
-   * @param uuid Optional event UUID.
-   * @param flags Optional `FeatureFlagEvaluations` snapshot to attach to the event.
-   */
-  captureException(
-    error: unknown,
-    distinctId?: string,
-    additionalProperties?: Record<string | number, any>,
-    uuid?: EventMessage['uuid'],
-    flags?: FeatureFlagEvaluations
-  ): void
+   * @param options Optional distinct id, properties, options, uuid, flags snapshot and level.
+   */
+  captureException(error: unknown, options?: CaptureExceptionOptions): void
 
   /**
    * @description Capture an exception as a $exception event immediately.
    * @param error The error to capture.
-   * @param distinctId Optional user distinct ID.
-   * @param additionalProperties Optional additional properties to include.
-   * @param flags Optional `FeatureFlagEvaluations` snapshot to attach to the event.
-   */
-  captureExceptionImmediate(
-    error: unknown,
-    distinctId?: string,
-    additionalProperties?: Record<string | number, any>,
-    flags?: FeatureFlagEvaluations
-  ): Promise<void>
+   * @param options Optional distinct id, properties, options, uuid, flags snapshot and level.
+   */
+  captureExceptionImmediate(error: unknown, options?: CaptureExceptionOptions): Promise<void>
 
   /**
    * @description Capture an AI event on the dedicated AI capture endpoint.
diff --git a/packages/nuxt/package.json b/packages/nuxt/package.json
index ab49e5ef29..c1d223d127 100644
--- a/packages/nuxt/package.json
+++ b/packages/nuxt/package.json
@@ -36,7 +36,7 @@
   "dependencies": {
     "@posthog/cli": "catalog:",
     "@nuxt/kit": ">=3.7.0",
-    "posthog-node": "workspace:^",
+    "posthog-node": "^5.56.0",
     "@posthog/core": "workspace:^",
     "@posthog/plugin-utils": "workspace:^",
     "posthog-js": "workspace:^"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 15c4636cf0..0aa035803f 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -574,8 +574,8 @@ importers:
         specifier: workspace:^
         version: link:../core
       posthog-node:
-        specifier: workspace:^
-        version: link:../node
+        specifier: ^5.56.0
+        version: 5.56.2(@opentelemetry/api@1.9.0)(rxjs@7.8.2)
     devDependencies:
       '@edge-runtime/vm':
         specifier: ^5.0.0
@@ -718,8 +718,8 @@ importers:
         specifier: workspace:^
         version: link:../browser
       posthog-node:
-        specifier: workspace:^
-        version: link:../node
+        specifier: ^5.56.0
+        version: 5.56.2(@opentelemetry/api@1.9.0)(rxjs@7.8.2)
       server-only:
         specifier: ^0.0.1
         version: 0.0.1
@@ -865,8 +865,8 @@ importers:
         specifier: workspace:^
         version: link:../browser
       posthog-node:
-        specifier: workspace:^
-        version: link:../node
+        specifier: ^5.56.0
+        version: 5.56.2(@opentelemetry/api@1.9.0)(rxjs@7.8.2)
     devDependencies:
       '@nuxt/devtools':
         specifier: ^3.3.1
@@ -5850,6 +5850,7 @@ packages:
   '@opentelemetry/sdk-trace-node@2.10.0':
     resolution: {integrity: sha512-GZK/G6oZyBLGlH1pUgeDch7D91KoHd2uotUGIkWCPi9GI5T9X0p4L7nNAMDR1BQjkRYoDqo+ddfVx9t5Uhys+Q==}
     engines: {node: ^18.19.0 || >=20.6.0}
+    deprecated: Use @opentelemetry/sdk-trace package
     peerDependencies:
       '@opentelemetry/api': '>=1.0.0 <1.10.0'
 
@@ -6616,9 +6617,15 @@ packages:
   '@posthog/core@1.58.0':
     resolution: {integrity: sha512-vluXIlVF6WGeHoQbsQK8Y1ywXZlJDU7YHEKiXAArQU38yFBpgxxfD0kInbYHtura4Fr7Z7H8WiDFvtMpCGehGg==}
 
+  '@posthog/core@1.59.1':
+    resolution: {integrity: sha512-P39YgzQVDh6oz6wAzQXEnoHgTYpM7gifonmVKq1scAJco79h31XmmNVurRq9tTmmyIrr1uX8FHT0riCsyfV9AQ==}
+
   '@posthog/types@1.415.2':
     resolution: {integrity: sha512-BIIHPyXcPZuNTImrR1qLqLKFw7j9o8co6LG/9OpLtpWJ3RT0y89Lx6VCtd37N9/dkr/qW7y0uPjJxAxjsALHtw==}
 
+  '@posthog/types@1.416.0':
+    resolution: {integrity: sha512-0/9+02s/0uDyrH4G/qUg1yyl6gXUg8Uuxw/PlDad3KLzo9FFS9zS/kAQaEshx/saVGupj1aAy/4EUBxWisBogw==}
+
   '@protobufjs/aspromise@1.1.2':
     resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
 
@@ -15692,6 +15699,18 @@ packages:
       react:
         optional: true
 
+  posthog-node@5.56.2:
+    resolution: {integrity: sha512-1/qYFNuHkDJJuDHjAvozN/fH/+XdqzlIZ0WCsCYrhUgGNxDBw5M3kZaJaRX0YSPi9tn7PnZFD5eTXg2Z7m5LeQ==}
+    engines: {node: ^20.20.0 || >=22.22.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.2.0
+      rxjs: ^7.0.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      rxjs:
+        optional: true
+
   posthog-react-native-session-replay@1.6.0:
     resolution: {integrity: sha512-OCaei77mtgg7JT+TgHSCgpWeKq2XXENUOPNxGbjhXZa/aJpptOW5VsBqjtH4BPzM2c1veS1DK4/Fb/uV4Rb3cg==}
     peerDependencies:
@@ -25376,8 +25395,14 @@ snapshots:
     dependencies:
       '@posthog/types': 1.415.2
 
+  '@posthog/core@1.59.1':
+    dependencies:
+      '@posthog/types': 1.416.0
+
   '@posthog/types@1.415.2': {}
 
+  '@posthog/types@1.416.0': {}
+
   '@protobufjs/aspromise@1.1.2': {}
 
   '@protobufjs/base64@1.1.2': {}
@@ -36920,6 +36945,13 @@ snapshots:
       '@types/react': 19.2.17
       react: 19.2.7
 
+  posthog-node@5.56.2(@opentelemetry/api@1.9.0)(rxjs@7.8.2):
+    dependencies:
+      '@posthog/core': 1.59.1
+    optionalDependencies:
+      '@opentelemetry/api': 1.9.0
+      rxjs: 7.8.2
+
   posthog-react-native-session-replay@1.6.0(react-native@0.69.12(@babel/core@7.28.5)(@babel/preset-env@7.28.5(@babel/core@7.28.5))(react@18.2.0))(react@18.2.0):
     dependencies:
       react: 18.2.0

From 971007c0254346bdd26121f7d5b834694eeeb0b6 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:23:53 -0700
Subject: [PATCH 12/20] feat(node)!: disable on personal keys, keep event
 content out of logs, add captureTracingHeaders (#5457)

* feat(node)!: disable on personal keys, keep event content out of logs, add captureTracingHeaders

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): regenerate the public API references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): qualify the debug log note for server response text

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-core-debug-payload.md      |  5 +++
 .changeset/posthog-node-capture-hardening.md  |  7 ++++
 packages/core/src/posthog-core-stateless.ts   |  9 ++++-
 .../posthog-node-references-latest.json       |  5 +++
 .../src/__tests__/extensions/express.spec.ts  | 22 ++++++++++
 .../node/src/__tests__/posthog-node.spec.ts   | 35 +++++++++++++++-
 packages/node/src/client.ts                   | 40 ++++++++++++++++++-
 packages/node/src/extensions/express.ts       |  4 +-
 packages/node/src/extensions/nestjs.ts        |  4 +-
 .../node/src/extensions/tracing-headers.ts    |  8 ++++
 packages/node/src/types.ts                    |  8 ++++
 11 files changed, 140 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/posthog-core-debug-payload.md
 create mode 100644 .changeset/posthog-node-capture-hardening.md

diff --git a/.changeset/posthog-core-debug-payload.md b/.changeset/posthog-core-debug-payload.md
new file mode 100644
index 0000000000..53ccba17e9
--- /dev/null
+++ b/.changeset/posthog-core-debug-payload.md
@@ -0,0 +1,5 @@
+---
+'@posthog/core': patch
+---
+
+Debug mode logs an emitted event's payload through an overridable `describeDebugPayload`, so an SDK can log a summary instead. The default is unchanged.
diff --git a/.changeset/posthog-node-capture-hardening.md b/.changeset/posthog-node-capture-hardening.md
new file mode 100644
index 0000000000..7b13fdb3bb
--- /dev/null
+++ b/.changeset/posthog-node-capture-hardening.md
@@ -0,0 +1,7 @@
+---
+'posthog-node': major
+---
+
+A personal API key (`phx_...`) passed as the project API key now disables the client, like a missing key, and either case logs one error that never includes the key.
+Debug mode logs event names, uuids and counts instead of whole events, and a `before_send` function that throws is logged with the error's type instead of its message. In debug mode, a capture error can still include the server or proxy response text.
+The Express and NestJS integrations take a new `captureTracingHeaders` option (default `true`): set it to `false` to stop reading the `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` request headers into the request context.
diff --git a/packages/core/src/posthog-core-stateless.ts b/packages/core/src/posthog-core-stateless.ts
index 3f27677a03..116e384495 100644
--- a/packages/core/src/posthog-core-stateless.ts
+++ b/packages/core/src/posthog-core-stateless.ts
@@ -539,7 +539,9 @@ export abstract class PostHogCoreStateless {
     this.removeDebugCallback?.()
 
     if (enabled) {
-      const removeDebugCallback = this.on('*', (event, payload) => this._logger.info(event, payload))
+      const removeDebugCallback = this.on('*', (event, payload) =>
+        this._logger.info(event, this.describeDebugPayload(payload))
+      )
       this.removeDebugCallback = () => {
         removeDebugCallback()
         this.removeDebugCallback = undefined
@@ -551,6 +553,11 @@ export abstract class PostHogCoreStateless {
     return !!this.removeDebugCallback
   }
 
+  /** What debug mode logs for an emitted event's payload. SDKs whose events can carry sensitive data log a summary instead. */
+  protected describeDebugPayload(payload: any): any {
+    return payload
+  }
+
   get isDisabled(): boolean {
     return this.disabled
   }
diff --git a/packages/node/references/posthog-node-references-latest.json b/packages/node/references/posthog-node-references-latest.json
index 05a1aa63ee..a7b5c10cf6 100644
--- a/packages/node/references/posthog-node-references-latest.json
+++ b/packages/node/references/posthog-node-references-latest.json
@@ -3854,6 +3854,11 @@
           "type": "number",
           "name": "maxQueueSize"
         },
+        {
+          "description": "Whether the Express and NestJS integrations read the `X-POSTHOG-DISTINCT-ID` and\n`X-POSTHOG-SESSION-ID` request headers into the request context. A distinct id or session id\nyou pass explicitly always wins over these headers, and they are never used for authentication.",
+          "type": "boolean",
+          "name": "captureTracingHeaders"
+        },
         {
           "description": "How many times a capture request is retried after its first attempt, on both capture lanes.\nWaits start at 100 ms and double each retry, with jitter, up to 30 seconds; a `Retry-After`\nheader can raise a wait. Only HTTP 404, 408, 429, 500, 502, 503 and 504 and network errors are retried.\nWhen not set, `fetchRetryCount` is used.",
           "type": "number",
diff --git a/packages/node/src/__tests__/extensions/express.spec.ts b/packages/node/src/__tests__/extensions/express.spec.ts
index 83e78e40cd..736a2b1b22 100644
--- a/packages/node/src/__tests__/extensions/express.spec.ts
+++ b/packages/node/src/__tests__/extensions/express.spec.ts
@@ -127,6 +127,28 @@ describe('Express extension', () => {
       expect(event.properties.$ip).toBe('10.0.0.1')
     })
 
+    it('ignores the tracing headers when captureTracingHeaders is false', async () => {
+      await posthog.shutdown()
+      posthog = createPostHog({ captureTracingHeaders: false })
+      const middleware = createRequestContextMiddleware(posthog)
+      const req = createMockRequest({
+        headers: { 'x-posthog-session-id': 'session-123', 'x-posthog-distinct-id': 'user-456' },
+        originalUrl: '/api/test',
+        method: 'GET',
+        path: '/api/test',
+      })
+
+      middleware(req, createMockResponse(), () => {
+        posthog.capture({ event: 'handler_event' })
+      })
+      await waitForFlushTimer(posthog)
+
+      const event = getLastBatchEvents()!.find((e: any) => e.event === 'handler_event')
+      expect(event.distinct_id).not.toBe('user-456')
+      expect(event.properties.$session_id).toBeUndefined()
+      expect(event.properties.$request_path).toBe('/api/test')
+    })
+
     it.each([
       {
         name: 'strips request path search and preserves URL hash by default',
diff --git a/packages/node/src/__tests__/posthog-node.spec.ts b/packages/node/src/__tests__/posthog-node.spec.ts
index beaebf8249..320383c6d8 100644
--- a/packages/node/src/__tests__/posthog-node.spec.ts
+++ b/packages/node/src/__tests__/posthog-node.spec.ts
@@ -624,6 +624,18 @@ describe('PostHog Node.js', () => {
       expect(batchEvents?.[0].properties).not.toHaveProperty('remove_me')
     })
 
+    it('logs event names, never event content, in debug mode', async () => {
+      const infoSpy = vi.spyOn((posthog as any)._logger, 'info').mockImplementation(() => {})
+      posthog.debug(true)
+      posthog.capture({ distinctId: 'user', event: 'debug-event', properties: { secret: 'SECRET-VALUE' } })
+      await waitForFlushTimer()
+
+      const logged = JSON.stringify(infoSpy.mock.calls)
+      expect(logged).toContain('flush')
+      expect(logged).not.toContain('SECRET-VALUE')
+      infoSpy.mockRestore()
+    })
+
     it('should warn if capture is called with a string', () => {
       posthog.debug(true)
       // @ts-expect-error - Testing the warning when passing a string instead of an object
@@ -822,7 +834,8 @@ describe('PostHog Node.js', () => {
       await waitForFlushTimer()
 
       expect(sentinel).not.toHaveBeenCalled()
-      expect(loggerSpy).toHaveBeenCalledWith("Error in before_send function for event 'test-event':", error)
+      expect(loggerSpy).toHaveBeenCalledWith("Error in before_send function for event 'test-event' (Error)")
+      expect(JSON.stringify(loggerSpy.mock.calls)).not.toContain(error.message)
       expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
       loggerSpy.mockRestore()
     })
@@ -1616,6 +1629,26 @@ describe('PostHog Node.js', () => {
       expect(posthog.options.personalApiKey).toEqual('TEST_SECRET_KEY')
     })
 
+    it.each([
+      ['an empty key', '  ', 'No project API key was passed'],
+      ['a personal key', 'phx_SECRET_PERSONAL_KEY', 'A personal API key ("phx_...") was passed'],
+    ])('disables the client and logs one error for %s', async (_name, apiKey, reason) => {
+      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      mockedFetch.mockClear()
+
+      posthog = new PostHog(apiKey, { host: 'http://example.com', flushAt: 1, flushInterval: 0 })
+      posthog.capture({ distinctId: 'user', event: 'disabled-event' })
+      await waitForPromises()
+
+      expect(posthog.isDisabled).toBe(true)
+      expect(mockedFetch).not.toHaveBeenCalledWith(anyCaptureUrl, expect.anything())
+      const keyErrors = errorSpy.mock.calls.filter(([line]) => String(line).includes('so the client is disabled'))
+      expect(keyErrors).toHaveLength(1)
+      expect(keyErrors[0][0]).toContain(reason)
+      expect(JSON.stringify(errorSpy.mock.calls)).not.toContain('SECRET_PERSONAL_KEY')
+      errorSpy.mockRestore()
+    })
+
     it('should not start local evaluation polling or fetch flags when api key is missing', async () => {
       mockedFetch.mockClear()
 
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index 6efda2ff9f..d820e86864 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -117,6 +117,32 @@ function normalizeApiKey(value?: unknown): string {
   return typeof value === 'string' ? value.trim() : ''
 }
 
+/** Why a project API key disables the client, or undefined when it is usable. Never includes the key. */
+function apiKeyProblem(apiKey: string): string | undefined {
+  if (!apiKey) {
+    return 'No project API key was passed'
+  }
+  if (apiKey.startsWith('phx_')) {
+    return 'A personal API key ("phx_...") was passed where the project API key ("phc_...") belongs'
+  }
+  return undefined
+}
+
+/** A content-free summary of an emitted event's payload for debug logs: names, uuids and counts only. */
+function summarizeForDebugLog(payload: unknown): unknown {
+  if (Array.isArray(payload)) {
+    return `${payload.length} item(s)`
+  }
+  if (payload instanceof Error) {
+    return `${payload.name}: ${payload.message}`
+  }
+  if (payload && typeof payload === 'object' && typeof (payload as { event?: unknown }).event === 'string') {
+    const { event, uuid } = payload as { event: string; uuid?: unknown }
+    return uuid === undefined ? { event } : { event, uuid }
+  }
+  return undefined
+}
+
 function normalizePersonalApiKey(value?: unknown): string | undefined {
   const normalizedValue = typeof value === 'string' ? value.trim() : ''
   return normalizedValue || undefined
@@ -385,8 +411,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
    */
   constructor(apiKey: string, options: PostHogOptions = {}) {
     const normalizedApiKey = normalizeApiKey(apiKey)
+    const keyProblem = apiKeyProblem(normalizedApiKey)
     const normalizedOptions = {
       ...options,
+      disabled: options.disabled || keyProblem !== undefined,
       // Node's default is higher than the shared core default (1000) because backend
       // workloads are more likely to burst-enqueue synchronously ahead of a flush.
       // Applied after the spread with a nullish fallback so a wrapper forwarding
@@ -400,6 +428,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     super(normalizedApiKey, normalizedOptions)
 
     this.options = normalizedOptions
+    if (keyProblem) {
+      // console.error, not this._logger: the logger only prints in debug mode, and the client sends nothing.
+      console.error(`[PostHog] ${keyProblem}, so the client is disabled.`)
+    }
     this.warnIfCaptureModeSet()
     // console.error, not this._logger: the logger only prints in debug mode, and a bad option changes delivery.
     this._captureSettings = resolveCaptureSettings(normalizedOptions, (message) =>
@@ -1196,6 +1228,10 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     this.featureFlagsPoller?.debug(enabled)
   }
 
+  protected describeDebugPayload(payload: unknown): unknown {
+    return summarizeForDebugLog(payload)
+  }
+
   private _warnIfInvalidCapture(
     props: EventMessage,
     stringArgumentWarning: string,
@@ -3740,7 +3776,9 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
           this._logger.warn(message)
         }
       } catch (error) {
-        this._logger.error(`Error in before_send function for event '${eventMessage.event}':`, error)
+        // The error's message can carry the data the hook was redacting, so only its type is logged.
+        const errorType = error instanceof Error ? error.name : typeof error
+        this._logger.error(`Error in before_send function for event '${eventMessage.event}' (${errorType})`)
         return null
       }
     }
diff --git a/packages/node/src/extensions/express.ts b/packages/node/src/extensions/express.ts
index 694095467b..4fa41b822a 100644
--- a/packages/node/src/extensions/express.ts
+++ b/packages/node/src/extensions/express.ts
@@ -1,7 +1,7 @@
 import ErrorTracking from './error-tracking'
 import { PostHogBackendClient } from '../client'
 import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
-import { addProperty, getFirstHeaderValue, getPostHogTracingHeaderValues } from './tracing-headers'
+import { addProperty, getFirstHeaderValue, readPostHogTracingHeaders } from './tracing-headers'
 import { normalizeRequestCurrentUrl, normalizeRequestPath } from './url-utils'
 import type { Request, Response } from 'express'
 import type { ContextData } from './context/types'
@@ -34,7 +34,7 @@ function getClientIp(req: Request): string | undefined {
 }
 
 function buildRequestContextData(posthog: PostHogBackendClient, req: Request): Partial<ContextData> {
-  const { sessionId, distinctId } = getPostHogTracingHeaderValues(req.headers)
+  const { sessionId, distinctId } = readPostHogTracingHeaders(posthog.options, req.headers)
   const properties: Record<string, any> = {}
   const disableCaptureUrlHashes = posthog.options.disable_capture_url_hashes === true
 
diff --git a/packages/node/src/extensions/nestjs.ts b/packages/node/src/extensions/nestjs.ts
index 26dc692360..ae0a155696 100644
--- a/packages/node/src/extensions/nestjs.ts
+++ b/packages/node/src/extensions/nestjs.ts
@@ -3,7 +3,7 @@ import { Observable, throwError } from 'rxjs'
 import { catchError } from 'rxjs/operators'
 
 import ErrorTracking from './error-tracking'
-import { addProperty, getFirstHeaderValue, getPostHogTracingHeaderValues } from './tracing-headers'
+import { addProperty, getFirstHeaderValue, readPostHogTracingHeaders } from './tracing-headers'
 import { normalizeRequestCurrentUrl, normalizeRequestPath } from './url-utils'
 import { PostHogBackendClient } from '../client'
 
@@ -75,7 +75,7 @@ export class PostHogInterceptor implements NestInterceptor {
     const response = httpHost.getResponse()
 
     const headers = (request?.headers ?? {}) as IncomingHttpHeaders
-    const { sessionId, distinctId } = getPostHogTracingHeaderValues(headers)
+    const { sessionId, distinctId } = readPostHogTracingHeaders(this.posthog.options, headers)
 
     const properties: Record<string, any> = {}
     const disableCaptureUrlHashes = this.posthog.options.disable_capture_url_hashes === true
diff --git a/packages/node/src/extensions/tracing-headers.ts b/packages/node/src/extensions/tracing-headers.ts
index bee180698c..544b7bc591 100644
--- a/packages/node/src/extensions/tracing-headers.ts
+++ b/packages/node/src/extensions/tracing-headers.ts
@@ -50,6 +50,14 @@ export function sanitizeTracingHeaderValue(value: HeaderValue): string | undefin
   return sanitized.length > TRACING_HEADER_MAX_LENGTH ? sanitized.slice(0, TRACING_HEADER_MAX_LENGTH) : sanitized
 }
 
+/** The tracing header values, or none when the client's `captureTracingHeaders` is `false`. */
+export function readPostHogTracingHeaders(
+  options: { captureTracingHeaders?: boolean },
+  headers?: IncomingHttpHeaders
+): PostHogTracingHeaderValues {
+  return options.captureTracingHeaders === false ? {} : getPostHogTracingHeaderValues(headers)
+}
+
 export function getPostHogTracingHeaderValues(headers?: IncomingHttpHeaders): PostHogTracingHeaderValues {
   if (!headers) {
     return {}
diff --git a/packages/node/src/types.ts b/packages/node/src/types.ts
index e6d07ee84a..e8d8853600 100644
--- a/packages/node/src/types.ts
+++ b/packages/node/src/types.ts
@@ -281,6 +281,14 @@ export type PostHogOptions = Omit<
    * @default 10000
    */
   maxQueueSize?: number
+  /**
+   * Whether the Express and NestJS integrations read the `X-POSTHOG-DISTINCT-ID` and
+   * `X-POSTHOG-SESSION-ID` request headers into the request context. A distinct id or session id
+   * you pass explicitly always wins over these headers, and they are never used for authentication.
+   *
+   * @default true
+   */
+  captureTracingHeaders?: boolean
   /**
    * How many times a capture request is retried after its first attempt, on both capture lanes.
    * Waits start at 100 ms and double each retry, with jitter, up to 30 seconds; a `Retry-After`

From 3f74998313e43009740ed64f5416d80454594b80 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:24:59 -0700
Subject: [PATCH 13/20] feat(node)!: drop events with invalid names or ids
 before sending, repair lone surrogates in properties (#5458)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../posthog-node-capture-wire-checks.md       |  6 +++
 .../src/__tests__/capture-lane/lane.spec.ts   | 25 ++++++++++++
 .../__tests__/capture-v1/serialize.spec.ts    | 38 ++++++++++++++++++-
 .../__tests__/capture-v1/transform.spec.ts    |  6 ++-
 packages/node/src/capture-lane/lane.ts        | 35 +++++++++++++----
 packages/node/src/capture-v1/serialize.ts     | 29 +++++++++++++-
 packages/node/src/capture-v1/transform.ts     | 10 ++++-
 7 files changed, 135 insertions(+), 14 deletions(-)
 create mode 100644 .changeset/posthog-node-capture-wire-checks.md

diff --git a/.changeset/posthog-node-capture-wire-checks.md b/.changeset/posthog-node-capture-wire-checks.md
new file mode 100644
index 0000000000..ac537c2669
--- /dev/null
+++ b/.changeset/posthog-node-capture-wire-checks.md
@@ -0,0 +1,6 @@
+---
+'posthog-node': major
+---
+
+An event whose name is missing, empty or not a string, or whose name, distinct id, session id or window id is not well-formed Unicode (a lone surrogate), is dropped before sending and reported through the `'error'` event, instead of being sent and failing at capture (an object name was sent as `"[object Object]"`). Lone surrogates in property strings are replaced with U+FFFD, so one bad character no longer fails the whole request.
+An unparseable event timestamp is still replaced with the current time, and now logs a warning that never includes the value.
diff --git a/packages/node/src/__tests__/capture-lane/lane.spec.ts b/packages/node/src/__tests__/capture-lane/lane.spec.ts
index bfa3b59aab..060a8f7f3c 100644
--- a/packages/node/src/__tests__/capture-lane/lane.spec.ts
+++ b/packages/node/src/__tests__/capture-lane/lane.spec.ts
@@ -171,6 +171,31 @@ describe('CaptureLane', () => {
       expect(localDrops.map((error) => error.drops)).toEqual([[{ uuid: 'uover', details: 'event too large' }]])
     })
 
+    it.each([
+      ['an empty name', { ...msg('bad'), event: '' }],
+      ['a malformed distinct id', { ...msg('bad'), distinct_id: 'user\ud800' }],
+    ])('drops a queued event with %s and reports it without sending', async (_name, bad) => {
+      const { lane, batches, localDrops } = makeLane()
+
+      lane.enqueue(bad)
+      lane.enqueue(msg('good'))
+      await lane.flush()
+
+      expect(batches).toEqual([['ugood']])
+      expect(localDrops).toHaveLength(1)
+      expect(localDrops[0].drops).toEqual([{ uuid: 'ubad', details: 'invalid event' }])
+      expect(localDrops[0].message).toContain('1 with a missing, empty or malformed event name or id')
+    })
+
+    it('drops an immediate event with an empty name and reports it without sending', async () => {
+      const { lane, send, localDrops } = makeLane()
+
+      await lane.sendImmediate({ ...msg(1), event: '' })
+
+      expect(send).not.toHaveBeenCalled()
+      expect(localDrops[0].drops).toEqual([{ uuid: 'u1', details: 'invalid event' }])
+    })
+
     it('drops an oversized immediate event and reports it without sending', async () => {
       const { lane, send, localDrops } = makeLane({ maxEventBytes: 100 })
 
diff --git a/packages/node/src/__tests__/capture-v1/serialize.spec.ts b/packages/node/src/__tests__/capture-v1/serialize.spec.ts
index d06e5610e7..c3c8afce6e 100644
--- a/packages/node/src/__tests__/capture-v1/serialize.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/serialize.spec.ts
@@ -1,6 +1,6 @@
 import { type PostHogEventProperties, safeJsonStringify } from '@posthog/core'
 
-import { buildV1Body, serializeV1Event } from '@/capture-v1/serialize'
+import { buildV1Body, serializeV1Event, wireProblem } from '@/capture-v1/serialize'
 import { buildV1Event } from '@/capture-v1/transform'
 
 const utf8Bytes = (value: string): number => Buffer.byteLength(value, 'utf8')
@@ -25,7 +25,7 @@ const MESSAGES: [string, PostHogEventProperties][] = [
       properties: { $session_id: 's1', $window_id: 'w1', $cookieless_mode: true, nested: { a: [1, 2] } },
     }),
   ],
-  ['multibyte characters', message({ event: 'café ☕', properties: { emoji: '🦔🦔', euro: '€', lone: '\ud800' } })],
+  ['multibyte characters', message({ event: 'café ☕', properties: { emoji: '🦔🦔', euro: '€' } })],
 ]
 
 describe('serializeV1Event', () => {
@@ -41,6 +41,23 @@ describe('serializeV1Event', () => {
     expect(serialized.propertiesBytes).toBe(utf8Bytes(safeJsonStringify(buildV1Event(input).properties)))
   })
 
+  it('repairs lone surrogates in property strings to U+FFFD and leaves pairs and escaped backslashes alone', () => {
+    const serialized = serializeV1Event(
+      message({
+        properties: { lone: 'a\ud800b', low: '\udc00', pair: '🦔', text: '\\ud800', nested: { x: ['\udbff'] } },
+      })
+    )
+
+    expect(JSON.parse(serialized.json).properties).toEqual({
+      lone: 'a\ufffdb',
+      low: '\ufffd',
+      pair: '🦔',
+      text: '\\ud800',
+      nested: { x: ['\ufffd'] },
+    })
+    expect(serialized.bytes).toBe(utf8Bytes(serialized.json))
+  })
+
   it('counts bytes, not UTF-16 code units', () => {
     const serialized = serializeV1Event(message({ properties: { emoji: '🦔'.repeat(10) } }))
 
@@ -72,3 +89,20 @@ describe('buildV1Body', () => {
     })
   })
 })
+
+describe('wireProblem', () => {
+  it.each<[string, PostHogEventProperties, boolean]>([
+    ['a valid event', message(), false],
+    ['an empty name', message({ event: '' }), true],
+    ['a missing name', message({ event: undefined }), true],
+    ['a non-string name', message({ event: { name: 'x' } as unknown as string }), true],
+    ['a lone surrogate in the name', message({ event: 'e\ud800' }), true],
+    ['a lone surrogate in the distinct id', message({ distinct_id: '\udc00user' }), true],
+    ['a lone surrogate in the session id', message({ properties: { $session_id: 's\ud800' } }), true],
+    ['a lone surrogate in the window id', message({ properties: { $window_id: 'w\ud800' } }), true],
+    ['a lone surrogate in another property', message({ properties: { other: '\ud800' } }), false],
+    ['a valid surrogate pair in the name', message({ event: 'hog 🦔' }), false],
+  ])('%s', (_name, input, invalid) => {
+    expect(wireProblem(input) !== undefined).toBe(invalid)
+  })
+})
diff --git a/packages/node/src/__tests__/capture-v1/transform.spec.ts b/packages/node/src/__tests__/capture-v1/transform.spec.ts
index 91632d2992..95f260a4ff 100644
--- a/packages/node/src/__tests__/capture-v1/transform.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/transform.spec.ts
@@ -315,9 +315,13 @@ describe('capture v1 transform', () => {
       expect(event.timestamp).toMatch(ISO_RE)
     })
 
-    it('falls back to a valid ISO string when a string timestamp is unparseable', () => {
+    it('falls back to a valid ISO string when a string timestamp is unparseable, and warns without the value', () => {
+      const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
       const event = buildV1Event(baseMessage({ timestamp: 'not-a-date' }))
       expect(event.timestamp).toMatch(ISO_RE)
+      expect(warn).toHaveBeenCalledWith('[PostHog] replacing an unparseable event timestamp with the current time')
+      expect(JSON.stringify(warn.mock.calls)).not.toContain('not-a-date')
+      warn.mockRestore()
     })
 
     it('falls back to a valid ISO string when the timestamp is an invalid Date instance', () => {
diff --git a/packages/node/src/capture-lane/lane.ts b/packages/node/src/capture-lane/lane.ts
index 30bd4ea5a1..07e1b9f59a 100644
--- a/packages/node/src/capture-lane/lane.ts
+++ b/packages/node/src/capture-lane/lane.ts
@@ -2,7 +2,7 @@ import { type Logger, type PostHogEventProperties, safeSetTimeout } from '@posth
 
 import { CaptureError, CaptureLossTally, type CaptureDroppedEvent, describeCaptureLoss } from '../capture-v1/errors'
 import type { V1SendOptions } from '../capture-v1/sender'
-import { type SerializedV1Event, serializeV1Event } from '../capture-v1/serialize'
+import { type SerializedV1Event, serializeV1Event, wireProblem } from '../capture-v1/serialize'
 import type { CaptureEndpoint } from '../capture-v1/types'
 
 /** Upper bound on the uuids one local-drop report lists; the message still carries the full count. */
@@ -51,13 +51,22 @@ interface QueuedEvent extends SerializedV1Event {
   message: PostHogEventProperties
 }
 
+type LocalDropReason = 'queueFull' | 'tooLarge' | 'invalid'
+
 interface LocalDropTally {
   queueFull: number
   tooLarge: number
+  invalid: number
   sample: CaptureDroppedEvent[]
 }
 
-const emptyTally = (): LocalDropTally => ({ queueFull: 0, tooLarge: 0, sample: [] })
+const emptyTally = (): LocalDropTally => ({ queueFull: 0, tooLarge: 0, invalid: 0, sample: [] })
+
+const LOCAL_DROP_DETAILS: Record<LocalDropReason, string> = {
+  queueFull: 'queue full',
+  tooLarge: 'event too large',
+  invalid: 'invalid event',
+}
 
 /**
  * One capture endpoint's in-memory queue, flush timer, `flushAt` trigger, batching and
@@ -96,6 +105,11 @@ export class CaptureLane {
 
   enqueue(message: PostHogEventProperties): void {
     const event: QueuedEvent = { ...serializeV1Event(message), message }
+    if (wireProblem(message)) {
+      this.recordLocalDrop(event, 'invalid')
+      this.armFlushTimer()
+      return
+    }
     if (this.isTooLarge(event)) {
       this.recordLocalDrop(event, 'tooLarge')
       // Nothing may follow to flush, and the flush cycle is what reports the drop.
@@ -117,9 +131,10 @@ export class CaptureLane {
   /** Sends one event now, without queueing. Delivery failures are reported, not thrown. */
   async sendImmediate(message: PostHogEventProperties): Promise<void> {
     const event = serializeV1Event(message)
-    if (this.isTooLarge(event)) {
+    const reason = wireProblem(message) ? 'invalid' : this.isTooLarge(event) ? 'tooLarge' : undefined
+    if (reason) {
       const tally = emptyTally()
-      this.addToTally(tally, event, 'tooLarge')
+      this.addToTally(tally, event, reason)
       this.reportTally(tally)
       return
     }
@@ -264,14 +279,14 @@ export class CaptureLane {
     return bytes > this.config.maxEventBytes
   }
 
-  private recordLocalDrop(event: SerializedV1Event, reason: 'queueFull' | 'tooLarge'): void {
+  private recordLocalDrop(event: SerializedV1Event, reason: LocalDropReason): void {
     this.addToTally(this.localDrops, event, reason)
   }
 
-  private addToTally(tally: LocalDropTally, event: SerializedV1Event, reason: 'queueFull' | 'tooLarge'): void {
+  private addToTally(tally: LocalDropTally, event: SerializedV1Event, reason: LocalDropReason): void {
     tally[reason]++
     if (tally.sample.length < MAX_REPORTED_LOCAL_DROPS) {
-      tally.sample.push({ uuid: event.uuid, details: reason === 'queueFull' ? 'queue full' : 'event too large' })
+      tally.sample.push({ uuid: event.uuid, details: LOCAL_DROP_DETAILS[reason] })
     }
   }
 
@@ -297,7 +312,7 @@ export class CaptureLane {
       errors.push(error)
       loss.add('still queued when shutdown ended', leftovers.length)
     }
-    const total = tally.queueFull + tally.tooLarge
+    const total = tally.queueFull + tally.tooLarge + tally.invalid
     if (total > 0) {
       const { maxQueueSize, maxEventBytes, maxEventBytesOf } = this.config
       const reasons: string[] = []
@@ -308,12 +323,16 @@ export class CaptureLane {
         const measured = maxEventBytesOf === 'properties' ? 'properties larger' : 'larger'
         reasons.push(`${tally.tooLarge} with ${measured} than ${maxEventBytes} bytes`)
       }
+      if (tally.invalid > 0) {
+        reasons.push(`${tally.invalid} with a missing, empty or malformed event name or id`)
+      }
       const error = new CaptureError({ endpoint, requestId: '', drops: tally.sample, retryExhausted: [] })
       error.message = `Dropped ${total} event(s) for ${endpoint} before sending: ${reasons.join(', ')}`
       errors.push(error)
       loss.add(`dropped because the queue was full (${maxQueueSize} events)`, tally.queueFull)
       const measured = maxEventBytesOf === 'properties' ? 'their properties were' : 'they were'
       loss.add(`dropped because ${measured} larger than ${maxEventBytes} bytes`, tally.tooLarge)
+      loss.add('dropped because the event name or an id was missing, empty or malformed', tally.invalid)
     }
     if (errors.length > 0) {
       this.safely(() => this.hooks.onLocalDrops(errors, describeCaptureLoss(endpoint, loss)))
diff --git a/packages/node/src/capture-v1/serialize.ts b/packages/node/src/capture-v1/serialize.ts
index 1ac2fae6ff..2500b650d2 100644
--- a/packages/node/src/capture-v1/serialize.ts
+++ b/packages/node/src/capture-v1/serialize.ts
@@ -18,10 +18,37 @@ export interface SerializedV1Event {
   propertiesBytes: number
 }
 
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/
+// JSON.stringify writes a lone surrogate as a `\udXXX` escape (a valid pair stays raw), which capture rejects for the whole
+// request. The lookbehind skips an escaped backslash followed by literal "udXXX" text.
+const LONE_SURROGATE_ESCAPE = /(?<!\\)((?:\\\\)*)\\u[dD][89a-fA-F][0-9a-fA-F]{2}/g
+
+/**
+ * Why capture would reject this event, or undefined when it can be sent. A name must be a non-empty string, and the
+ * name and ids must be well-formed Unicode: a broken id is never repaired, because two broken ids could collapse into one.
+ */
+export function wireProblem(message: PostHogEventProperties): string | undefined {
+  const { event, distinct_id: distinctId, properties } = message
+  if (typeof event !== 'string' || event === '') {
+    return 'event name is missing, empty or not a string'
+  }
+  const props = (properties ?? {}) as Record<string, unknown>
+  const ids = [event, distinctId, props.$session_id, props.$window_id]
+  if (ids.some((value) => typeof value === 'string' && LONE_SURROGATE.test(value))) {
+    return 'event name or id is not well-formed Unicode'
+  }
+  return undefined
+}
+
 export function serializeV1Event(message: PostHogEventProperties): SerializedV1Event {
   const { properties, ...rest } = buildV1Event(message)
   const restJson = safeJsonStringify(rest)
-  const propertiesJson = safeJsonStringify(properties)
+  const rawPropertiesJson = safeJsonStringify(properties)
+  // Property strings are repaired to U+FFFD rather than dropping the event.
+  const propertiesJson =
+    rawPropertiesJson.includes('\\ud') || rawPropertiesJson.includes('\\uD')
+      ? rawPropertiesJson.replace(LONE_SURROGATE_ESCAPE, '$1\\ufffd')
+      : rawPropertiesJson
   const propertiesBytes = encoder.encode(propertiesJson).length
   return {
     uuid: rest.uuid,
diff --git a/packages/node/src/capture-v1/transform.ts b/packages/node/src/capture-v1/transform.ts
index d81e0714b5..94684460e7 100644
--- a/packages/node/src/capture-v1/transform.ts
+++ b/packages/node/src/capture-v1/transform.ts
@@ -48,11 +48,17 @@ export function readEventOptions(value: unknown): V1EventOptions | undefined {
  * caller passed one); numbers are treated as epoch milliseconds. Invalid values
  * fall back to "now" so a bad timestamp never rejects the whole batch.
  */
+function replaceUnparseableTimestamp(): string {
+  // console.warn, not the client logger: the logger only prints in debug mode, and the event's time changes. Never logs the value.
+  console.warn('[PostHog] replacing an unparseable event timestamp with the current time')
+  return new Date().toISOString()
+}
+
 function toRfc3339(timestamp: unknown): string {
   if (typeof timestamp === 'string') {
     const asDate = new Date(timestamp)
     if (Number.isNaN(asDate.getTime())) {
-      return new Date().toISOString()
+      return replaceUnparseableTimestamp()
     }
 
     const normalized = asDate.toISOString()
@@ -62,7 +68,7 @@ function toRfc3339(timestamp: unknown): string {
       : normalized
   }
   if (timestamp instanceof Date) {
-    return Number.isNaN(timestamp.getTime()) ? new Date().toISOString() : timestamp.toISOString()
+    return Number.isNaN(timestamp.getTime()) ? replaceUnparseableTimestamp() : timestamp.toISOString()
   }
   const asDate = timestamp == null ? new Date() : new Date(timestamp as string | number)
   return Number.isNaN(asDate.getTime()) ? new Date().toISOString() : asDate.toISOString()

From 60502364cf26cb648548f38607133d24f6aa4c2c Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:26:02 -0700
Subject: [PATCH 14/20] feat(node)!: generate event uuids from
 crypto.getRandomValues (#5459)

* feat(node)!: generate event uuids from crypto.getRandomValues

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): generate a missing event uuid from the crypto-backed generator too

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-core-v7-generator.md       |  5 +++
 .../posthog-node-capture-crypto-uuids.md      |  5 +++
 packages/core/src/index.ts                    |  2 +-
 .../src/__tests__/capture-v1/uuid.spec.ts     | 45 ++++++++++++++++++-
 packages/node/src/capture-v1/uuid.ts          | 33 ++++++++++++++
 packages/node/src/client.ts                   | 14 +++---
 6 files changed, 95 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/posthog-core-v7-generator.md
 create mode 100644 .changeset/posthog-node-capture-crypto-uuids.md

diff --git a/.changeset/posthog-core-v7-generator.md b/.changeset/posthog-core-v7-generator.md
new file mode 100644
index 0000000000..b34e1b9cff
--- /dev/null
+++ b/.changeset/posthog-core-v7-generator.md
@@ -0,0 +1,5 @@
+---
+'@posthog/core': patch
+---
+
+Export `V7Generator`, so an SDK can generate v7 uuids from its own random source.
diff --git a/.changeset/posthog-node-capture-crypto-uuids.md b/.changeset/posthog-node-capture-crypto-uuids.md
new file mode 100644
index 0000000000..5e4b91b5e9
--- /dev/null
+++ b/.changeset/posthog-node-capture-crypto-uuids.md
@@ -0,0 +1,5 @@
+---
+'posthog-node': major
+---
+
+Generated event uuids and personless distinct ids take their random bits from `crypto.getRandomValues` instead of `Math.random`.
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index b43143f3c3..7b1767c77e 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -108,7 +108,7 @@ export type {
   StartSpanOptions,
   TracesConfig,
 } from './traces/types'
-export { uuidv7 } from './vendor/uuidv7'
+export { uuidv7, V7Generator } from './vendor/uuidv7'
 export * from './cookie'
 export * from './posthog-core'
 export * from './posthog-core-stateless'
diff --git a/packages/node/src/__tests__/capture-v1/uuid.spec.ts b/packages/node/src/__tests__/capture-v1/uuid.spec.ts
index 4cded9a07b..d4ace79292 100644
--- a/packages/node/src/__tests__/capture-v1/uuid.spec.ts
+++ b/packages/node/src/__tests__/capture-v1/uuid.spec.ts
@@ -1,10 +1,15 @@
-import { canonicalizeUuid } from '@/capture-v1/uuid'
+import { canonicalizeUuid, eventUuidv7 } from '@/capture-v1/uuid'
 import type { PostHogOptions } from '@/entrypoints/index.node'
 
 import { AI_CAPTURE_PATH, ANALYTICS_CAPTURE_PATH, captureEvents } from '../utils'
 import { V1WiringHarness } from '../utils/v1-wiring'
 
 vi.mock('../../version', () => ({ version: '1.2.3' }))
+// A pass-through spy, so the tests below see which uuids the crypto-backed generator produced.
+vi.mock('@/capture-v1/uuid', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@/capture-v1/uuid')>()
+  return { ...actual, eventUuidv7: vi.fn(actual.eventUuidv7) }
+})
 
 const CANONICAL = '0198c0de-1234-7abc-8def-0123456789ab'
 const WARNING = '[PostHog] Replaced an invalid event uuid with a generated one; uuids must be RFC 4122 strings'
@@ -141,6 +146,26 @@ describe('event uuids on the client', () => {
     expect(uuidWarnings()).toEqual(warnings)
   })
 
+  it.each(['capture', 'captureImmediate'] as const)(
+    '%s takes a missing uuid from the crypto-backed generator',
+    async (method) => {
+      const generated = vi.mocked(eventUuidv7)
+      generated.mockClear()
+      const posthog = harness.makeClient()
+
+      if (method === 'capture') {
+        posthog.capture({ distinctId: 'u', event: 'plain', properties: {} })
+      } else {
+        await posthog.captureImmediate({ distinctId: 'u', event: 'plain', properties: {} })
+      }
+      await posthog.flush()
+
+      const [uuid] = captureEvents(harness.fetch, ANALYTICS_CAPTURE_PATH).map((event) => event.uuid)
+      expect(uuid).toMatch(UUID_V7)
+      expect(generated.mock.results.map((result) => result.value)).toContain(uuid)
+    }
+  )
+
   it('warns once per bad call', async () => {
     const posthog = harness.makeClient()
 
@@ -151,3 +176,21 @@ describe('event uuids on the client', () => {
     expect(uuidWarnings()).toEqual([[WARNING], [WARNING]])
   })
 })
+
+describe('eventUuidv7', () => {
+  it('takes its random bits from crypto.getRandomValues, never Math.random', () => {
+    const cryptoSpy = vi.spyOn(globalThis.crypto, 'getRandomValues')
+    const mathSpy = vi.spyOn(Math, 'random')
+
+    const uuids = Array.from({ length: 50 }, () => eventUuidv7())
+
+    expect(cryptoSpy).toHaveBeenCalled()
+    expect(mathSpy).not.toHaveBeenCalled()
+    expect(new Set(uuids).size).toBe(uuids.length)
+    for (const uuid of uuids) {
+      expect(uuid).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/)
+    }
+    cryptoSpy.mockRestore()
+    mathSpy.mockRestore()
+  })
+})
diff --git a/packages/node/src/capture-v1/uuid.ts b/packages/node/src/capture-v1/uuid.ts
index ec2967dc8c..5474059781 100644
--- a/packages/node/src/capture-v1/uuid.ts
+++ b/packages/node/src/capture-v1/uuid.ts
@@ -1,3 +1,5 @@
+import { V7Generator } from '@posthog/core'
+
 const HYPHENATED = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 const HEX_32 = /^[0-9a-f]{32}$/i
 const URN_PREFIX = 'urn:uuid:'
@@ -18,3 +20,34 @@ export function canonicalizeUuid(value: string): string | undefined {
   }
   return HYPHENATED.test(hyphenated) ? hyphenated.toLowerCase() : undefined
 }
+
+type CryptoLike = { getRandomValues(array: Uint32Array): Uint32Array }
+
+/** 32-bit words from the platform's cryptographic source, filled eight at a time to keep the per-uuid cost low. */
+class CryptoRandom {
+  private readonly words = new Uint32Array(8)
+  private cursor = this.words.length
+
+  constructor(private readonly crypto: CryptoLike) {}
+
+  nextUint32(): number {
+    if (this.cursor >= this.words.length) {
+      this.crypto.getRandomValues(this.words)
+      this.cursor = 0
+    }
+    return this.words[this.cursor++]
+  }
+}
+
+function cryptoRandom(): CryptoRandom | undefined {
+  const crypto = (globalThis as { crypto?: Partial<CryptoLike> }).crypto
+  return typeof crypto?.getRandomValues === 'function' ? new CryptoRandom(crypto as CryptoLike) : undefined
+}
+
+// Without a crypto source (none in supported Node and edge runtimes), the core generator's Math.random source is used.
+const generator = new V7Generator(cryptoRandom())
+
+/** A v7 uuid for an event or a personless distinct id, with random bits from `crypto.getRandomValues`. */
+export function eventUuidv7(): string {
+  return generator.generate().toString()
+}
diff --git a/packages/node/src/client.ts b/packages/node/src/client.ts
index d820e86864..c65db9c251 100644
--- a/packages/node/src/client.ts
+++ b/packages/node/src/client.ts
@@ -26,7 +26,6 @@ import {
   raceWithTimeout,
   safeSetTimeout,
   SyncSpanContextManager,
-  uuidv7,
 } from '@posthog/core'
 import type {
   Metrics,
@@ -79,7 +78,7 @@ import { CaptureLane, type CaptureLaneConfig } from './capture-lane/lane'
 import { AI_MAX_PROPERTIES_BYTES, ANALYTICS_MAX_EVENT_BYTES, CAPTURE_BATCH_TARGET_BYTES } from './capture-lane/limits'
 import { type CaptureSettings, resolveCaptureSettings } from './capture-lane/settings'
 import { type CaptureCompressor, resolveCaptureCodec, webCompressor } from './capture-v1/compression'
-import { canonicalizeUuid } from './capture-v1/uuid'
+import { canonicalizeUuid, eventUuidv7 } from './capture-v1/uuid'
 import { readEventOptions } from './capture-v1/transform'
 import { fillOptions, fillProperties, isUnsetProperty, snapshotLayer } from './event-defaults'
 import { AI_CAPTURE_ROUTE } from './ai-capture/routing'
@@ -549,7 +548,8 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
   private _prepareLaneMessage(message: any, options?: PostHogCaptureOptions): PostHogEventProperties | null {
     const { _invalidUuidWarned, ...captureOptions } = (options ?? {}) as LaneCaptureOptions
     // before_send already ran, so this is the hook's uuid; check it again, warning at most once per call.
-    const uuid = this._canonicalEventUuid(captureOptions.uuid, !_invalidUuidWarned)
+    // A missing uuid is generated here, not by core's generator.
+    const uuid = this._canonicalEventUuid(captureOptions.uuid, !_invalidUuidWarned) ?? eventUuidv7()
     const prepared = this.processBeforeEnqueue(this.prepareMessage(message, { ...captureOptions, uuid }))
     return prepared === null ? null : this.normalizeMessage(prepared)
   }
@@ -570,7 +570,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
       // console.warn, not this._logger: the logger only prints in debug mode, and the event loses its uuid.
       console.warn('[PostHog] Replaced an invalid event uuid with a generated one; uuids must be RFC 4122 strings')
     }
-    return uuidv7()
+    return eventUuidv7()
   }
 
   /**
@@ -1384,7 +1384,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (this.disabled) {
       return undefined
     }
-    const uuid = this._canonicalEventUuid(props.uuid) ?? uuidv7()
+    const uuid = this._canonicalEventUuid(props.uuid) ?? eventUuidv7()
     void this._sendPreparedAiEvent({ ...props, uuid }, false)
     return uuid
   }
@@ -1403,7 +1403,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
     if (this.disabled) {
       return undefined
     }
-    const uuid = this._canonicalEventUuid(props.uuid) ?? uuidv7()
+    const uuid = this._canonicalEventUuid(props.uuid) ?? eventUuidv7()
     await this._sendPreparedAiEvent({ ...props, uuid }, true)
     return uuid
   }
@@ -3671,7 +3671,7 @@ export abstract class PostHogBackendClient extends PostHogCoreStateless implemen
 
     const resolvedDistinctId =
       presentDistinctId(distinctId) ?? presentDistinctId(contextData?.distinctId) ?? prepareOptions.fallbackDistinctId
-    const eventDistinctId = resolvedDistinctId ?? uuidv7()
+    const eventDistinctId = resolvedDistinctId ?? eventUuidv7()
 
     const eventProperties: PostHogEventProperties = { ...(properties || {}) }
     if (prepareOptions.distinctIdProperty) {

From abc9e9104ac94455ebde4c4d99974b0fc6a1a486 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:28:00 -0700
Subject: [PATCH 15/20] feat(ai): send AI events through captureAi on
 posthog-node 6 (#5460)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-ai-capture-ai-node-6.md |  5 +++++
 packages/ai/src/captureAiEvent.ts          | 17 +++++++++++++++--
 packages/ai/tests/captureAiEvent.test.ts   | 16 ++++++++++++++++
 3 files changed, 36 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/posthog-ai-capture-ai-node-6.md

diff --git a/.changeset/posthog-ai-capture-ai-node-6.md b/.changeset/posthog-ai-capture-ai-node-6.md
new file mode 100644
index 0000000000..b4ddbe432e
--- /dev/null
+++ b/.changeset/posthog-ai-capture-ai-node-6.md
@@ -0,0 +1,5 @@
+---
+'@posthog/ai': minor
+---
+
+With posthog-node 6, every AI event is sent through `captureAi` on the capture v1 AI lane, and `enableFullAiCapture` only controls truncation and media redaction. With posthog-node 5, nothing changes: AI events use `capture` unless `enableFullAiCapture` is set.
diff --git a/packages/ai/src/captureAiEvent.ts b/packages/ai/src/captureAiEvent.ts
index 6743f0befc..bfc2d1ce3f 100644
--- a/packages/ai/src/captureAiEvent.ts
+++ b/packages/ai/src/captureAiEvent.ts
@@ -11,6 +11,7 @@ export interface AiLaneCapableClient extends FullAiCaptureGate {
   captureImmediate(props: EventMessage): Promise<void>
   captureAi?(props: EventMessage): string | undefined
   captureAiImmediate?(props: EventMessage): Promise<string | undefined>
+  getLibraryVersion?(): string
 }
 
 /** @internal */
@@ -18,9 +19,21 @@ export function isFullAiCaptureEnabled(client?: FullAiCaptureGate): boolean {
   return client?.enableFullAiCapture === true
 }
 
+/**
+ * posthog-node 6 sends every AI event on its capture v1 AI lane; `enableFullAiCapture` then only
+ * controls truncation and media redaction. posthog-node 5 keeps the opt-in, so an `@posthog/ai`
+ * upgrade never changes how a 5.x client sends.
+ *
+ * @internal
+ */
+export function usesAiLane(client: AiLaneCapableClient): boolean {
+  const major = Number.parseInt(client.getLibraryVersion?.() ?? '', 10)
+  return major >= 6 || isFullAiCaptureEnabled(client)
+}
+
 /** @internal */
 export function captureAiEvent(client: AiLaneCapableClient, event: EventMessage): void {
-  if (isFullAiCaptureEnabled(client) && typeof client.captureAi === 'function') {
+  if (usesAiLane(client) && typeof client.captureAi === 'function') {
     client.captureAi(event)
     return
   }
@@ -29,7 +42,7 @@ export function captureAiEvent(client: AiLaneCapableClient, event: EventMessage)
 
 /** @internal */
 export async function captureAiEventImmediate(client: AiLaneCapableClient, event: EventMessage): Promise<void> {
-  if (isFullAiCaptureEnabled(client) && typeof client.captureAiImmediate === 'function') {
+  if (usesAiLane(client) && typeof client.captureAiImmediate === 'function') {
     await client.captureAiImmediate(event)
     return
   }
diff --git a/packages/ai/tests/captureAiEvent.test.ts b/packages/ai/tests/captureAiEvent.test.ts
index 7d0f9f1ff9..95a4619d34 100644
--- a/packages/ai/tests/captureAiEvent.test.ts
+++ b/packages/ai/tests/captureAiEvent.test.ts
@@ -38,6 +38,22 @@ describe('captureAiEvent routing', () => {
     expect(client.capture).toHaveBeenCalledWith(event)
   })
 
+  it.each([
+    ['6.0.0', true],
+    ['6.2.1', true],
+    ['7.0.0-beta.1', true],
+    ['5.57.1', false],
+    ['not-a-version', false],
+  ])('posthog-node %s uses the AI lane without the opt-in: %s', async (version, aiLane) => {
+    const client = makeClient({ getLibraryVersion: () => version })
+    captureAiEvent(client, event)
+    await captureAiEventImmediate(client, event)
+    expect(client.captureAi).toHaveBeenCalledTimes(aiLane ? 1 : 0)
+    expect(client.captureAiImmediate).toHaveBeenCalledTimes(aiLane ? 1 : 0)
+    expect(client.capture).toHaveBeenCalledTimes(aiLane ? 0 : 1)
+    expect(client.captureImmediate).toHaveBeenCalledTimes(aiLane ? 0 : 1)
+  })
+
   it('immediate variant mirrors the routing', async () => {
     const optedIn = makeClient({ enableFullAiCapture: true })
     await captureAiEventImmediate(optedIn, event)

From 91c75a28048e8da9fe39d1d1a17c8200c0b1da6c Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:28:53 -0700
Subject: [PATCH 16/20] chore(node): run the YAML compliance harness against
 capture v1 (#5456)

* chore(node): run the YAML compliance harness against capture v1

Rewrite the YAML adapter for capture v1 only: pass options and caller uuids
unchanged, pick one codec per process, and declare the capture_ai_v1,
event_options and harness 1.23.0 capabilities. Add a CI job per codec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): support the harness reported_drops, log_capture, generated_payloads, property_layers and fail_open features

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(node): name each reported drop once and size padding markers in bytes in the compliance adapter

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): run the compliance harness from release 1.25.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(node): expect $geoip_disable: false from a per-call disableGeoip: false in the v2 adapter test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): run the compliance harness from release 1.26.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): run the Gherkin harness from release 1.26.0

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(node): pin the YAML harness image by digest and reuse the parsed attempt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../sdk-compliance-tests-node-v2.yml          |   4 +-
 .../workflows/sdk-compliance-tests-node.yml   | 106 +++++
 .oxlintrc.json                                |   3 +-
 compliance/node/Dockerfile                    |   4 +-
 compliance/node/Dockerfile.v1                 |  42 --
 compliance/node/README.md                     |  14 +-
 compliance/node/adapter.js                    | 324 ---------------
 compliance/node/adapter.mjs                   | 381 ++++++++++++++++++
 compliance/node/docker-compose.yml            |   9 +-
 compliance/node/v2/server.test.mjs            |   3 +-
 10 files changed, 506 insertions(+), 384 deletions(-)
 create mode 100644 .github/workflows/sdk-compliance-tests-node.yml
 delete mode 100644 compliance/node/Dockerfile.v1
 delete mode 100644 compliance/node/adapter.js
 create mode 100644 compliance/node/adapter.mjs

diff --git a/.github/workflows/sdk-compliance-tests-node-v2.yml b/.github/workflows/sdk-compliance-tests-node-v2.yml
index 463d257823..82bac7310c 100644
--- a/.github/workflows/sdk-compliance-tests-node-v2.yml
+++ b/.github/workflows/sdk-compliance-tests-node-v2.yml
@@ -51,8 +51,8 @@ jobs:
                 shell: bash
         env:
             NODE_IMAGE: node:24.21.0-bookworm-slim@sha256:0e0ff40c39bc087845bfb27465a0df4ea419520094bc35842ff83dd8cbe6f9b6
-            # Harness release 1.16.0; pin the published multi-platform image index.
-            HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness-v2@sha256:14c539d87c758a8798d3681d26e081cd156b739052d4fdefc51065f92e7cd2f2
+            # Harness release 1.26.0; pin the published multi-platform image index.
+            HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness-v2@sha256:74dae248b19cc6030d803e2904b08d3bd1036b5c215414636a42d090ac27cba0
         steps:
             # Test the PR head or the triggering commit for push/manual runs.
             - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
diff --git a/.github/workflows/sdk-compliance-tests-node.yml b/.github/workflows/sdk-compliance-tests-node.yml
new file mode 100644
index 0000000000..8428a35c9e
--- /dev/null
+++ b/.github/workflows/sdk-compliance-tests-node.yml
@@ -0,0 +1,106 @@
+name: Node SDK compliance
+
+on:
+    workflow_dispatch:
+    push:
+        branches: [main]
+        paths:
+            - 'packages/node/**'
+            - 'packages/core/**'
+            - 'packages/types/**'
+            - 'tooling/**'
+            - 'compliance/node/adapter.mjs'
+            - 'compliance/node/Dockerfile'
+            - '.github/workflows/sdk-compliance-tests-node.yml'
+            - 'pnpm-lock.yaml'
+            - 'pnpm-workspace.yaml'
+            - 'patches/**'
+    pull_request:
+        paths:
+            - 'packages/node/**'
+            - 'packages/core/**'
+            - 'packages/types/**'
+            - 'tooling/**'
+            - 'compliance/node/adapter.mjs'
+            - 'compliance/node/Dockerfile'
+            - '.github/workflows/sdk-compliance-tests-node.yml'
+            - 'pnpm-lock.yaml'
+            - 'pnpm-workspace.yaml'
+            - 'patches/**'
+
+permissions: {}
+
+jobs:
+    compliance:
+        # The harness has one enable_compression flag but a test per codec, so each
+        # job runs the adapter with one codec. The SDK has no brotli support.
+        name: Node SDK compliance (${{ matrix.compression }})
+        runs-on: ubuntu-24.04
+        timeout-minutes: 30
+        permissions:
+            contents: read
+        strategy:
+            fail-fast: false
+            matrix:
+                compression: [gzip, deflate, zstd]
+        concurrency:
+            group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}-${{ matrix.compression }}
+            cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+        env:
+            HARNESS_IMAGE: ghcr.io/posthog/sdk-test-harness:1.26.0@sha256:9db022b5729dcf1557b9e622a36b6d6afa42e1b42653f031b0da6d73ca5d77fe
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  persist-credentials: false
+
+            - name: Pull test harness
+              run: docker pull "$HARNESS_IMAGE"
+
+            - name: Build SDK adapter
+              run: docker build -f compliance/node/Dockerfile -t sdk-adapter:test .
+
+            - name: Start SDK adapter
+              env:
+                  COMPRESSION: ${{ matrix.compression }}
+              run: |
+                  docker network create test-network
+                  docker run -d --name sdk-adapter --network test-network -e COMPRESSION="$COMPRESSION" sdk-adapter:test
+
+            - name: Run compliance suites
+              run: |
+                  mkdir -p report
+                  docker run --rm \
+                    --name test-harness \
+                    --network test-network \
+                    -v "${GITHUB_WORKSPACE}/report:/report" \
+                    "$HARNESS_IMAGE" \
+                    run \
+                    --adapter-url http://sdk-adapter:8080 \
+                    --mock-url http://test-harness:8081 \
+                    --output text \
+                    --report /report/sdk-compliance-report.md \
+                    --sdk-type server
+
+            - name: Publish report to the job summary
+              if: always()
+              run: |
+                  if [ -f report/sdk-compliance-report.md ]; then
+                    cat report/sdk-compliance-report.md >> "$GITHUB_STEP_SUMMARY"
+                  fi
+
+            - name: Upload compliance report
+              if: always()
+              uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+              with:
+                  name: node-sdk-compliance-report-${{ matrix.compression }}
+                  path: report/sdk-compliance-report.md
+
+            - name: Show adapter logs on failure
+              if: failure()
+              run: docker logs sdk-adapter || true
+
+            - name: Stop containers
+              if: always()
+              run: |
+                  docker rm -f sdk-adapter || true
+                  docker network rm test-network || true
diff --git a/.oxlintrc.json b/.oxlintrc.json
index d1a516b370..7705802637 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -125,12 +125,13 @@
     },
     "overrides": [
         {
-            "files": ["compliance/node/v2/**"],
+            "files": ["compliance/node/v2/**", "compliance/node/adapter.mjs"],
             "env": { "node": true },
             "rules": {
                 "compat/compat": "off",
                 "posthog-js/no-direct-null-check": "off",
                 "posthog-js/no-direct-array-check": "off",
+                "posthog-js/no-direct-function-check": "off",
                 "posthog-js/no-direct-number-check": "off",
                 "posthog-js/no-direct-undefined-check": "off"
             }
diff --git a/compliance/node/Dockerfile b/compliance/node/Dockerfile
index b38aee351e..06601ede4a 100644
--- a/compliance/node/Dockerfile
+++ b/compliance/node/Dockerfile
@@ -25,7 +25,7 @@ RUN pnpm --filter posthog-node build
 WORKDIR /app/adapter
 
 # Copy adapter code
-COPY compliance/node/adapter.js ./
+COPY compliance/node/adapter.mjs ./
 
 # Install adapter dependencies (express) in clean directory
 RUN npm init -y && npm install express
@@ -33,4 +33,4 @@ RUN npm init -y && npm install express
 EXPOSE 8080
 
 USER node
-CMD ["node", "adapter.js"]
+CMD ["node", "adapter.mjs"]
diff --git a/compliance/node/Dockerfile.v1 b/compliance/node/Dockerfile.v1
deleted file mode 100644
index 90e3e65f1e..0000000000
--- a/compliance/node/Dockerfile.v1
+++ /dev/null
@@ -1,42 +0,0 @@
-FROM node:24-alpine
-
-WORKDIR /app
-
-# Copy the entire monorepo (needed for workspace dependencies)
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
-COPY patches ./patches
-COPY tooling ./tooling
-COPY packages/types ./packages/types
-COPY packages/core ./packages/core
-COPY packages/node ./packages/node
-
-# Install pnpm
-RUN npm install -g pnpm@11.7.0
-
-# Install dependencies
-RUN pnpm install --frozen-lockfile
-
-# Build the types, core, and node packages
-RUN pnpm --filter @posthog/types build
-RUN pnpm --filter @posthog/core build
-RUN pnpm --filter posthog-node build
-
-# Set up adapter in separate directory
-WORKDIR /app/adapter
-
-# Copy adapter code
-COPY compliance/node/adapter.js ./
-
-# Install adapter dependencies (express) in clean directory
-RUN npm init -y && npm install express
-
-# Run the adapter in Capture V1 mode so it advertises the capture_v1 capability
-# and the harness runs the /i/v1/analytics/events contract against it. The
-# reusable compliance workflow only passes PORT at runtime, so the mode is baked
-# into the image here.
-ENV POSTHOG_CAPTURE_MODE=v1
-
-EXPOSE 8080
-
-USER node
-CMD ["node", "adapter.js"]
diff --git a/compliance/node/README.md b/compliance/node/README.md
index 20a2c9e862..5622c07ce8 100644
--- a/compliance/node/README.md
+++ b/compliance/node/README.md
@@ -1,21 +1,21 @@
 # PostHog Node SDK Compliance Adapter
 
 Compliance adapter for the posthog-node SDK with the [PostHog SDK Test Harness](https://github.com/PostHog/posthog-sdk-test-harness).
+It runs the capture v1 suites (`capture_v1`, `capture_ai_v1`) and the feature flag suites.
 
 ## Running Tests
 
 ```bash
-# From compliance/node — legacy /batch/ contract (capture_v0)
+# From compliance/node
 docker-compose up --build --abort-on-container-exit
 
-# Capture V1 contract (POST /i/v1/analytics/events)
-POSTHOG_CAPTURE_MODE=v1 docker-compose up --build --abort-on-container-exit
+# Another codec for the compression tests
+COMPRESSION=zstd docker-compose up --build --abort-on-container-exit
 ```
 
-The adapter's capture mode is fixed per process: with `POSTHOG_CAPTURE_MODE=v1`
-it advertises the `capture_v1` capability and the harness runs the V1 contract;
-otherwise it advertises `capture_v0`. CI runs both as separate jobs
-(`Dockerfile` for v0, `Dockerfile.v1` for v1).
+Each adapter process runs one codec (`COMPRESSION`: `gzip`, `deflate` or `zstd`, default `gzip`) and advertises only that `encoding_<codec>` capability.
+CI runs one job per codec (`.github/workflows/sdk-compliance-tests-node.yml`).
+The Gherkin harness adapter lives in `v2/`.
 
 ## Documentation
 
diff --git a/compliance/node/adapter.js b/compliance/node/adapter.js
deleted file mode 100644
index 959949e016..0000000000
--- a/compliance/node/adapter.js
+++ /dev/null
@@ -1,324 +0,0 @@
-/**
- * PostHog Node SDK Compliance Adapter
- *
- * Wraps the posthog-node SDK for compliance testing.
- */
-
-const express = require('express')
-const { PostHog } = require('../packages/node/dist/entrypoints/index.node')
-
-const app = express()
-app.use(express.json())
-
-// Capture mode is fixed per adapter process (baked into the image via env) so the
-// harness runs exactly one capture contract against it: v1 advertises capture_v1,
-// otherwise capture_v0.
-const CAPTURE_MODE = process.env.POSTHOG_CAPTURE_MODE === 'v1' ? 'v1' : 'v0'
-
-// Harness EventOptions -> posthog-node sentinel properties. The SDK lifts these
-// sentinels out of properties into the v1 event `options` object.
-const OPTION_SENTINELS = {
-    cookieless_mode: '$cookieless_mode',
-    disable_skew_correction: '$ignore_sent_at',
-    process_person_profile: '$process_person_profile',
-    product_tour_id: '$product_tour_id',
-}
-
-const state = {
-    client: null,
-    totalEventsCaptured: 0,
-    totalEventsSent: 0,
-    totalRetries: 0,
-    lastError: null,
-    requestsMade: [],
-    pendingEvents: 0,
-}
-
-async function discardClient() {
-    if (!state.client) {
-        return
-    }
-
-    const client = state.client
-    state.client = null
-
-    // Test resets should discard queued events instead of flushing them into
-    // the next mock-server scenario.
-    try {
-        client.clearFlushTimer?.()
-        client.setPersistedProperty?.('queue', [])
-        // v1 mode routes $ai_* events to a separate queue, and captureAi() events to
-        // their own dedicated queue; clear both so they can't leak into the next scenario.
-        client.setPersistedProperty?.('ai_queue', [])
-        client.setPersistedProperty?.('ai_capture_queue', [])
-        await client.shutdown(1)
-    } catch (error) {
-        // Ignore reset-time shutdown errors; the next test starts with a fresh client.
-    }
-}
-
-app.get('/health', (req, res) => {
-    res.json({
-        sdk_name: 'posthog-node',
-        sdk_version: require('../packages/node/package.json').version,
-        adapter_version: '1.0.0',
-        capabilities:
-            CAPTURE_MODE === 'v1'
-                ? ['capture_v1', 'capture_ai_v0', 'encoding_gzip']
-                : ['capture_v0', 'capture_ai_v0', 'encoding_gzip'],
-    })
-})
-
-app.post('/init', async (req, res) => {
-    const {
-        api_key,
-        host,
-        flush_at,
-        flush_interval_ms,
-        max_retries,
-        enable_compression,
-        disable_geoip,
-        historical_migration,
-    } = req.body
-
-    await discardClient()
-
-    // Reset state
-    state.totalEventsCaptured = 0
-    state.totalEventsSent = 0
-    state.totalRetries = 0
-    state.lastError = null
-    state.requestsMade = []
-    state.pendingEvents = 0
-
-    // Create new client
-    state.client = new PostHog(api_key, {
-        host,
-        // Respect the harness batch-size configuration, including flush_at: 1
-        // for auto-flush compliance tests. Default to 2 only when omitted so
-        // ad-hoc single-event captures wait for an explicit /flush call.
-        flushAt: flush_at ?? 2,
-        flushInterval: flush_interval_ms ?? 100,
-        fetchRetryCount: max_retries ?? 3,
-        // Keep v1 partial-retry backoff short so retry compliance tests stay well
-        // within their wait windows (the mock also sends Retry-After: 1s).
-        fetchRetryDelay: CAPTURE_MODE === 'v1' ? 250 : undefined,
-        disableCompression: enable_compression === undefined ? undefined : !enable_compression,
-        disableGeoip: disable_geoip ?? false,
-        historicalMigration: historical_migration ?? undefined,
-        // Capture V1 opt-in is env-var-only: the SDK reads POSTHOG_CAPTURE_MODE
-        // (set by docker-compose / Dockerfile.v1) itself, so no option is passed.
-        // Use before_send to track events being sent
-        before_send: (event) => {
-            // Track that event is being sent
-            // Note: This runs before the HTTP request
-            return event
-        },
-        // Override fetch to track HTTP requests
-        fetch: async (url, options) => {
-            const response = await fetch(url, options)
-
-            // Track the request
-            try {
-                const body = options?.body ? JSON.parse(options.body) : null
-                const events = body?.batch || (body ? [body] : [])
-
-                state.requestsMade.push({
-                    timestamp_ms: Date.now(),
-                    status_code: response.status,
-                    retry_attempt: 0,
-                    event_count: events.length,
-                    uuid_list: events.map(e => e.uuid).filter(Boolean),
-                })
-
-                if (response.status === 200) {
-                    state.totalEventsSent += events.length
-                    state.pendingEvents -= events.length
-                    if (state.pendingEvents < 0) state.pendingEvents = 0
-                }
-            } catch (e) {
-                // Ignore parsing errors
-            }
-
-            return response
-        },
-    })
-
-    res.json({ success: true })
-})
-
-app.post('/capture', (req, res) => {
-    if (!state.client) {
-        return res.status(400).json({ error: 'SDK not initialized' })
-    }
-
-    const { distinct_id, event, properties, timestamp, options } = req.body
-
-    if (!distinct_id || !event) {
-        return res.status(400).json({ error: 'distinct_id and event are required' })
-    }
-
-    try {
-        // Translate harness EventOptions into the SDK's sentinel properties; the SDK
-        // lifts them into the v1 event `options` object (no-op in v0 mode).
-        const mergedProperties = { ...(properties || {}) }
-        if (options && typeof options === 'object') {
-            for (const [optionKey, sentinel] of Object.entries(OPTION_SENTINELS)) {
-                if (Object.prototype.hasOwnProperty.call(options, optionKey)) {
-                    mergedProperties[sentinel] = options[optionKey]
-                }
-            }
-        }
-
-        // Capture event
-        state.client.capture({
-            distinctId: distinct_id,
-            event,
-            properties: mergedProperties,
-            timestamp: timestamp ? new Date(timestamp) : undefined,
-        })
-
-        state.totalEventsCaptured++
-        state.pendingEvents++
-
-        // TODO: Get actual UUID from SDK
-        res.json({ success: true, uuid: 'generated-uuid' })
-    } catch (error) {
-        state.lastError = error.message
-        res.status(500).json({ error: error.message })
-    }
-})
-
-app.post('/capture_ai', (req, res) => {
-    if (!state.client) {
-        return res.status(400).json({ error: 'SDK not initialized' })
-    }
-
-    const { distinct_id, event, properties, timestamp, options, uuid } = req.body
-
-    if (!distinct_id || !event) {
-        return res.status(400).json({ error: 'distinct_id and event are required' })
-    }
-
-    try {
-        const mergedProperties = { ...(properties || {}) }
-        if (options && typeof options === 'object') {
-            for (const [optionKey, sentinel] of Object.entries(OPTION_SENTINELS)) {
-                if (Object.prototype.hasOwnProperty.call(options, optionKey)) {
-                    mergedProperties[sentinel] = options[optionKey]
-                }
-            }
-        }
-
-        // Unlike /capture, forward a supplied uuid so it's echoed back to the caller.
-        const returnedUuid = state.client.captureAi({
-            distinctId: distinct_id,
-            event,
-            properties: mergedProperties,
-            timestamp: timestamp ? new Date(timestamp) : undefined,
-            uuid,
-        })
-
-        state.totalEventsCaptured++
-        state.pendingEvents++
-
-        res.json({ success: true, uuid: returnedUuid })
-    } catch (error) {
-        state.lastError = error.message
-        res.status(500).json({ error: error.message })
-    }
-})
-
-app.post('/flush', async (req, res) => {
-    if (!state.client) {
-        return res.status(400).json({ error: 'SDK not initialized' })
-    }
-
-    const sentBeforeFlush = state.totalEventsSent
-
-    try {
-        await state.client.flush()
-        res.json({ success: true, events_flushed: state.totalEventsSent })
-    } catch (error) {
-        // The harness deliberately configures mock-server failures for retry
-        // assertions. Treat SDK flush rejections as a completed adapter action
-        // so the harness can inspect the outbound requests it caused.
-        state.lastError = error.message
-        res.json({
-            success: false,
-            events_flushed: Math.max(0, state.totalEventsSent - sentBeforeFlush),
-            error: error.message,
-        })
-    }
-})
-
-app.get('/state', (req, res) => {
-    res.json({
-        pending_events: state.pendingEvents,
-        total_events_captured: state.totalEventsCaptured,
-        total_events_sent: state.totalEventsSent,
-        total_retries: state.totalRetries,
-        last_error: state.lastError,
-        requests_made: state.requestsMade,
-    })
-})
-
-app.post('/get_feature_flag', async (req, res) => {
-    if (!state.client) {
-        return res.status(400).json({ error: 'SDK not initialized' })
-    }
-
-    const {
-        key,
-        distinct_id,
-        person_properties,
-        groups,
-        group_properties,
-        disable_geoip,
-        force_remote = true,
-    } = req.body || {}
-
-    if (!key) {
-        return res.status(400).json({ error: 'key is required' })
-    }
-    if (!distinct_id) {
-        return res.status(400).json({ error: 'distinct_id is required' })
-    }
-
-    try {
-        const value = await state.client.getFeatureFlag(key, distinct_id, {
-            groups,
-            personProperties: person_properties,
-            groupProperties: group_properties,
-            disableGeoip: disable_geoip,
-            onlyEvaluateLocally: !force_remote,
-        })
-
-        // Feature flag calls enqueue a $feature_flag_called event by default.
-        // Flush it before returning so it cannot leak into the next test case.
-        await state.client.flush()
-
-        res.json({ success: true, value })
-    } catch (error) {
-        state.lastError = error.message
-        res.status(500).json({ error: error.message })
-    }
-})
-
-app.post('/reset', async (req, res) => {
-    await discardClient()
-
-    state.totalEventsCaptured = 0
-    state.totalEventsSent = 0
-    state.totalRetries = 0
-    state.lastError = null
-    state.requestsMade = []
-    state.pendingEvents = 0
-
-    res.json({ success: true })
-})
-
-const port = process.env.PORT || 8080
-app.listen(port, () => {
-    console.log(`PostHog Node SDK adapter listening on port ${port}`)
-})
diff --git a/compliance/node/adapter.mjs b/compliance/node/adapter.mjs
new file mode 100644
index 0000000000..b6d0dca852
--- /dev/null
+++ b/compliance/node/adapter.mjs
@@ -0,0 +1,381 @@
+/**
+ * PostHog Node SDK Compliance Adapter
+ *
+ * Wraps the posthog-node SDK for the YAML compliance harness (capture v1).
+ */
+
+import { readFileSync } from 'node:fs'
+import zlib from 'node:zlib'
+import express from 'express'
+import { PostHog } from '../packages/node/dist/entrypoints/index.node.mjs'
+
+const SDK_VERSION = JSON.parse(readFileSync(new URL('../packages/node/package.json', import.meta.url), 'utf8')).version
+
+const app = express()
+app.use(express.json())
+
+// The harness has one enable_compression flag but a test per codec, so each
+// adapter process runs one codec and advertises only that encoding capability.
+const COMPRESSION = process.env.COMPRESSION || 'gzip'
+const CODECS = ['gzip', 'deflate', 'zstd']
+if (!CODECS.includes(COMPRESSION)) {
+    throw new Error(`unsupported COMPRESSION ${JSON.stringify(COMPRESSION)}: want one of ${CODECS.join(', ')}`)
+}
+
+const DECOMPRESS = {
+    gzip: zlib.gunzipSync,
+    deflate: zlib.inflateSync,
+    zstd: zlib.zstdDecompressSync,
+}
+
+const state = {
+    client: null,
+    totalEventsCaptured: 0,
+    totalEventsSent: 0,
+    lastError: null,
+    requestsMade: [],
+    pendingEvents: 0,
+    reportedDrops: [],
+    logLines: [],
+    // Event names per uuid in send order (from requests) and in call order (from captureAi), so a reported drop can
+    // name its event; a duplicate uuid has several names. Kept apart so one event is never counted twice.
+    sentNames: new Map(),
+    calledNames: new Map(),
+}
+
+function resetCounters() {
+    state.totalEventsCaptured = 0
+    state.totalEventsSent = 0
+    state.lastError = null
+    state.requestsMade = []
+    state.pendingEvents = 0
+    state.reportedDrops = []
+    state.logLines = []
+    state.sentNames = new Map()
+    state.calledNames = new Map()
+}
+
+// The SDK logs through console; /state returns those lines (log_capture).
+for (const level of ['log', 'info', 'warn', 'error', 'debug']) {
+    const write = console[level].bind(console)
+    console[level] = (...args) => {
+        state.logLines.push(args.map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg))).join(' '))
+        write(...args)
+    }
+}
+
+function rememberName(names, uuid, event) {
+    if (uuid) {
+        names.set(uuid, [...(names.get(uuid) ?? []), event])
+    }
+}
+
+function recordDrops(error) {
+    const duplicatesSeen = new Map()
+    for (const { uuid, details } of error?.drops ?? []) {
+        const names = state.sentNames.get(uuid) ?? state.calledNames.get(uuid) ?? []
+        let index = 0
+        if (details === 'duplicate_event_uuid') {
+            // Capture keeps the first copy, so the dropped copies are the later names, in order.
+            index = 1 + (duplicatesSeen.get(uuid) ?? 0)
+            duplicatesSeen.set(uuid, index)
+        }
+        state.reportedDrops.push({ uuid, event: names[index] ?? names[0] ?? null, details: details ?? null })
+    }
+}
+
+const PADDING_KEY = '$test_padding'
+
+// One ASCII padding property makes the properties' compact JSON exactly `size` bytes (generated_payloads).
+function padProperties(properties, size, marker = '') {
+    const padded = { ...properties, [PADDING_KEY]: '' }
+    const fill = size - Buffer.byteLength(JSON.stringify(padded), 'utf8')
+    // The marker's bytes as written in JSON, escapes included, without its quotes.
+    const markerBytes = Buffer.byteLength(JSON.stringify(marker), 'utf8') - 2
+    if (fill < markerBytes) {
+        throw new Error(`pad_properties_to_bytes ${size} is smaller than the properties`)
+    }
+    padded[PADDING_KEY] = marker + 'x'.repeat(fill - markerBytes)
+    return padded
+}
+
+async function discardClient() {
+    if (!state.client) {
+        return
+    }
+
+    const client = state.client
+    state.client = null
+
+    // Test resets should not flush queued events into the next mock-server scenario.
+    try {
+        await client.shutdown(1)
+    } catch {
+        // The next test starts with a fresh client.
+    }
+}
+
+function headerValue(headers, name) {
+    if (!headers) {
+        return undefined
+    }
+    if (typeof headers.get === 'function') {
+        return headers.get(name) ?? undefined
+    }
+    const key = Object.keys(headers).find((k) => k.toLowerCase() === name)
+    return key === undefined ? undefined : headers[key]
+}
+
+// Best effort: /state is diagnostic, so an unreadable body only skips the counters.
+function parseEvents(fetchOptions) {
+    const body = fetchOptions?.body
+    if (!body) {
+        return []
+    }
+    let raw =
+        typeof body === 'string'
+            ? Buffer.from(body)
+            : Buffer.from(body.buffer ?? body, body.byteOffset, body.byteLength)
+    const encoding = headerValue(fetchOptions.headers, 'content-encoding')
+    if (encoding && DECOMPRESS[encoding]) {
+        raw = DECOMPRESS[encoding](raw)
+    }
+    const parsed = JSON.parse(raw.toString('utf8'))
+    return Array.isArray(parsed?.batch) ? parsed.batch : []
+}
+
+function captureMessage({ distinct_id, event, properties, timestamp, options, uuid, pad_properties_to_bytes, marker }) {
+    return {
+        distinctId: distinct_id,
+        event,
+        properties:
+            pad_properties_to_bytes === undefined
+                ? properties || {}
+                : padProperties(properties || {}, pad_properties_to_bytes, marker),
+        timestamp: timestamp ? new Date(timestamp) : undefined,
+        // Options and caller uuids go to the SDK unchanged; the SDK owns validation.
+        options,
+        uuid,
+    }
+}
+
+app.get('/health', (req, res) => {
+    res.json({
+        sdk_name: 'posthog-node',
+        sdk_version: SDK_VERSION,
+        adapter_version: '2.0.0',
+        capabilities: [
+            'capture_v1',
+            'capture_ai_v1',
+            'event_options',
+            'event_uuid_override',
+            'bounded_retries',
+            'disable_geoip',
+            'historical_migration',
+            'reported_drops',
+            'log_capture',
+            'generated_payloads',
+            'property_layers',
+            'fail_open',
+            `encoding_${COMPRESSION}`,
+        ],
+    })
+})
+
+app.post('/init', async (req, res) => {
+    const {
+        api_key,
+        host,
+        flush_at,
+        flush_interval_ms,
+        max_retries,
+        enable_compression,
+        disable_geoip,
+        historical_migration,
+        super_properties,
+        before_send,
+    } = req.body
+
+    await discardClient()
+    resetCounters()
+
+    // The SDK compresses both lanes by default; the harness flag picks this process's codec or none.
+    const compression = enable_compression === undefined ? undefined : enable_compression ? COMPRESSION : 'none'
+
+    state.client = new PostHog(api_key, {
+        host,
+        // flush_at: 1 sends on capture; default to 2 so a lone capture waits for /flush.
+        flushAt: flush_at ?? 2,
+        flushInterval: flush_interval_ms ?? 100,
+        captureMaxRetries: max_retries ?? 3,
+        captureCompression: compression,
+        captureAiCompression: compression,
+        disableGeoip: disable_geoip ?? false,
+        historicalMigration: historical_migration ?? undefined,
+        ...(before_send
+            ? {
+                  before_send: (event) => ({
+                      ...event,
+                      properties: { ...event.properties, ...before_send.set_properties },
+                  }),
+              }
+            : {}),
+        fetch: async (url, fetchOptions) => {
+            const response = await fetch(url, fetchOptions)
+            try {
+                const events = parseEvents(fetchOptions)
+                const attempt = Number(headerValue(fetchOptions?.headers, 'posthog-attempt') ?? 1)
+                if (attempt === 1) {
+                    for (const event of events) {
+                        rememberName(state.sentNames, event.uuid, event.event)
+                    }
+                }
+                state.requestsMade.push({
+                    timestamp_ms: Date.now(),
+                    status_code: response.status,
+                    retry_attempt: Math.max(0, attempt - 1),
+                    event_count: events.length,
+                    uuid_list: events.map((e) => e.uuid).filter(Boolean),
+                })
+                if (response.status === 200) {
+                    state.totalEventsSent += events.length
+                    state.pendingEvents = Math.max(0, state.pendingEvents - events.length)
+                }
+            } catch {
+                // Diagnostic counters only.
+            }
+            return response
+        },
+    })
+    state.client.on('error', (error) => {
+        state.lastError = error?.message ?? String(error)
+        recordDrops(error)
+    })
+    if (super_properties) {
+        await state.client.register(super_properties)
+    }
+
+    res.json({ success: true })
+})
+
+app.post('/capture', (req, res) => {
+    if (!state.client) {
+        return res.status(400).json({ error: 'SDK not initialized' })
+    }
+
+    try {
+        const message = captureMessage(req.body)
+        state.client.capture(message)
+        state.totalEventsCaptured++
+        state.pendingEvents++
+        // capture() returns nothing, so only a caller-supplied uuid is known here.
+        res.json({ success: true, uuid: message.uuid ?? null })
+    } catch (error) {
+        state.lastError = error.message
+        res.status(500).json({ error: error.message })
+    }
+})
+
+app.post('/capture_ai', (req, res) => {
+    if (!state.client) {
+        return res.status(400).json({ error: 'SDK not initialized' })
+    }
+
+    try {
+        const uuid = state.client.captureAi(captureMessage(req.body))
+        // A local drop is never sent, so it is named from the call.
+        rememberName(state.calledNames, uuid, req.body.event)
+        state.totalEventsCaptured++
+        state.pendingEvents++
+        res.json({ success: true, uuid: uuid ?? null })
+    } catch (error) {
+        state.lastError = error.message
+        res.status(500).json({ error: error.message })
+    }
+})
+
+app.post('/flush', async (req, res) => {
+    if (!state.client) {
+        return res.status(400).json({ error: 'SDK not initialized' })
+    }
+
+    const sentBeforeFlush = state.totalEventsSent
+
+    try {
+        await state.client.flush()
+        res.json({ success: true, events_flushed: state.totalEventsSent - sentBeforeFlush })
+    } catch (error) {
+        // Retry tests configure failing responses on purpose; the harness inspects the requests instead.
+        state.lastError = error.message
+        res.json({
+            success: false,
+            events_flushed: Math.max(0, state.totalEventsSent - sentBeforeFlush),
+            error: error.message,
+        })
+    }
+})
+
+app.get('/state', (req, res) => {
+    res.json({
+        pending_events: state.pendingEvents,
+        total_events_captured: state.totalEventsCaptured,
+        total_events_sent: state.totalEventsSent,
+        total_retries: state.requestsMade.filter((r) => r.retry_attempt > 0).length,
+        last_error: state.lastError,
+        requests_made: state.requestsMade,
+        reported_drops: state.reportedDrops,
+        log_lines: state.logLines,
+    })
+})
+
+app.post('/get_feature_flag', async (req, res) => {
+    if (!state.client) {
+        return res.status(400).json({ error: 'SDK not initialized' })
+    }
+
+    const {
+        key,
+        distinct_id,
+        person_properties,
+        groups,
+        group_properties,
+        disable_geoip,
+        force_remote = true,
+    } = req.body || {}
+
+    if (!key) {
+        return res.status(400).json({ error: 'key is required' })
+    }
+    if (!distinct_id) {
+        return res.status(400).json({ error: 'distinct_id is required' })
+    }
+
+    try {
+        const value = await state.client.getFeatureFlag(key, distinct_id, {
+            groups,
+            personProperties: person_properties,
+            groupProperties: group_properties,
+            disableGeoip: disable_geoip,
+            onlyEvaluateLocally: !force_remote,
+        })
+
+        // Flush the $feature_flag_called event so it cannot leak into the next test case.
+        await state.client.flush()
+
+        res.json({ success: true, value })
+    } catch (error) {
+        state.lastError = error.message
+        res.status(500).json({ error: error.message })
+    }
+})
+
+app.post('/reset', async (req, res) => {
+    await discardClient()
+    resetCounters()
+    res.json({ success: true })
+})
+
+const port = process.env.PORT || 8080
+app.listen(port, () => {
+    process.stdout.write(`PostHog Node SDK adapter listening on port ${port} (compression=${COMPRESSION})\n`)
+})
diff --git a/compliance/node/docker-compose.yml b/compliance/node/docker-compose.yml
index 8ab0598b93..bf9813ca8f 100644
--- a/compliance/node/docker-compose.yml
+++ b/compliance/node/docker-compose.yml
@@ -5,16 +5,15 @@ services:
       dockerfile: compliance/node/Dockerfile
     expose:
       - "8080"
-    # Set POSTHOG_CAPTURE_MODE=v1 to run the Capture V1 contract locally; the
-    # adapter then advertises capture_v1 and the harness selects the v1 suite.
+    # One codec per adapter process: gzip, deflate or zstd.
     environment:
-      - POSTHOG_CAPTURE_MODE=${POSTHOG_CAPTURE_MODE:-}
+      - COMPRESSION=${COMPRESSION:-gzip}
     networks:
       - test-network
 
   test-harness:
-    image: ghcr.io/posthog/sdk-test-harness:0.10.0
-    command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081"]
+    image: ghcr.io/posthog/sdk-test-harness:1.26.0
+    command: ["run", "--adapter-url", "http://sdk-adapter:8080", "--mock-url", "http://test-harness:8081", "--sdk-type", "server"]
     networks:
       - test-network
     depends_on:
diff --git a/compliance/node/v2/server.test.mjs b/compliance/node/v2/server.test.mjs
index 8c11c9a98e..f100bfacad 100644
--- a/compliance/node/v2/server.test.mjs
+++ b/compliance/node/v2/server.test.mjs
@@ -142,7 +142,8 @@ for (const mode of ['v1'])
                 const event = request.body.batch[0]
                 assert.equal(event.event, expectedEvent)
                 assert.equal(event.distinct_id, distinctId)
-                assert.equal(event.properties.$geoip_disable, undefined)
+                // posthog-node 6 sends a per-call disableGeoip: false as $geoip_disable: false.
+                assert.equal(event.properties.$geoip_disable, false)
                 if (route === '/identify') assert.deepEqual(event.properties.$set, set)
                 else if (route === '/alias') assert.equal(event.properties.alias, 'user-123')
                 else {

From 52868b63264a97131adfb13c07650c3247ca8a7b Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Thu, 29 Oct 2026 16:29:38 -0700
Subject: [PATCH 17/20] docs(node): add the 5.x to 6.0 migration guide (#5461)

* docs(node): add the 5.x to 6.0 migration guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): qualify the log guarantee and positional captureException note

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): describe the before_send copy, exception levels and captureException warnings in the 6.0 guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): note that before_send edits no longer reach the sendFeatureFlags request

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-node-capture-hardening.md |   2 +-
 packages/node/MIGRATION.md                   | 341 +++++++++++++++++++
 packages/node/README.md                      |   2 +
 3 files changed, 344 insertions(+), 1 deletion(-)
 create mode 100644 packages/node/MIGRATION.md

diff --git a/.changeset/posthog-node-capture-hardening.md b/.changeset/posthog-node-capture-hardening.md
index 7b13fdb3bb..92aeb233b8 100644
--- a/.changeset/posthog-node-capture-hardening.md
+++ b/.changeset/posthog-node-capture-hardening.md
@@ -4,4 +4,4 @@
 
 A personal API key (`phx_...`) passed as the project API key now disables the client, like a missing key, and either case logs one error that never includes the key.
 Debug mode logs event names, uuids and counts instead of whole events, and a `before_send` function that throws is logged with the error's type instead of its message. In debug mode, a capture error can still include the server or proxy response text.
-The Express and NestJS integrations take a new `captureTracingHeaders` option (default `true`): set it to `false` to stop reading the `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` request headers into the request context.
+A new client option, `captureTracingHeaders` (default `true`), controls whether the Express and NestJS integrations read the `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` request headers into the request context.
diff --git a/packages/node/MIGRATION.md b/packages/node/MIGRATION.md
new file mode 100644
index 0000000000..81ffa0e6f5
--- /dev/null
+++ b/packages/node/MIGRATION.md
@@ -0,0 +1,341 @@
+# Migrating from posthog-node 5.x to 6.0
+
+posthog-node 6.0 sends every event through capture v1 and removes the legacy capture path.
+Most apps upgrade without code changes.
+Read the checklist first, then the sections that apply to you.
+
+For background on capture v1, its options, limits and per-event results, see the [capture v1 API docs](https://posthog.com/docs/api/capture-v1) and the [capture v1 SDK guide](https://posthog.com/docs/libraries/capture-v1).
+
+## Checklist
+
+You need to change code or configuration if your app does any of these:
+
+- sends events through a reverse proxy, or to a self-hosted PostHog (see [Reverse proxies and self-hosted PostHog](#reverse-proxies-and-self-hosted-posthog))
+- relies on `flush()`, `shutdown()` or `captureImmediate()` rejecting when delivery fails
+- listens for the `'error'` event and inspects the error's type or fields
+- sets `POSTHOG_CAPTURE_MODE`
+- calls `captureException()` or `captureExceptionImmediate()` with positional arguments after `error` (still works in 6.x, with a deprecation error)
+- sets `$exception_level` or another reserved exception property in `captureException()` properties
+- reads the result of `prepareEventMessage()`
+- reuses one event `uuid` for more than one event
+- passes strings such as `"true"` for `$process_person_profile`, `$cookieless_mode` or `$ignore_sent_at`
+- sets `$is_server`, `$geoip_disable` or feature flag properties on events, in context or with `register()`, and expects the SDK's value to win
+- sets `$lib` or `$lib_version`
+- sends a `$session_id` or `$window_id` that is not a string
+- passes a personal API key (`phx_...`) as the project API key
+- reads event content from the SDK's debug log, or alerts on SDK log text
+- sends AI events with `captureAi()` and tunes the AI queue, timeout or compression
+- uses `sendFeatureFlags` together with a `before_send` hook that drops events or edits `groups` or `sendFeatureFlags`
+- uses `@posthog/convex`, `@posthog/next` or `@posthog/nuxt` (stay on posthog-node 5 for now)
+
+## Reverse proxies and self-hosted PostHog
+
+posthog-node 6.0 sends events to new paths:
+
+| Method                                                                                                              | Endpoint                 |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| `capture`, `captureImmediate`, `identify`, `alias`, `groupIdentify`, `captureException` and the other event methods | `/i/v1/analytics/events` |
+| `captureAi`, `captureAiImmediate`, and `@posthog/ai` on posthog-node 6                                              | `/i/v1/ai/events`        |
+
+An `$ai_*` event sent with `capture()` goes to the analytics endpoint. Only `captureAi()` and `captureAiImmediate()` use the AI endpoint.
+
+If you send events to a self-hosted PostHog, check that it serves both endpoints before you upgrade.
+An endpoint that is not served drops every event sent to it.
+A `404` that lasts through every retry can mean the deployment has no capture v1 route.
+
+If you send events through your own reverse proxy, update it before you upgrade:
+
+- Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog.
+- Pass `Authorization` through unchanged when it starts with `Bearer `. It carries the project API key, which is no longer in the request body. PostHog answers `401` without it.
+- Pass every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged. PostHog answers `400` without them, and the batch fails.
+- Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx.
+
+The body limit matters more than before. 5.x halved a batch and retried it when it got a `413`. 6.0 does not split batches: a `413` fails the whole batch, and the events are lost.
+Raise the proxy's body limit before you upgrade.
+
+PostHog's managed reverse proxy already does all of this. See the [proxy guides](https://posthog.com/docs/advanced/proxy).
+
+### Redirects
+
+A capture request follows only `307` and `308` redirects, and only to the same origin (scheme, host and port) as `host`, at most 5 times.
+It resends the same body and headers.
+Any other redirect fails the batch without a retry.
+If a proxy redirects capture requests to another host, set `host` to the final host.
+Feature flag requests are unchanged.
+
+## Removed and renamed
+
+| 5.x                                                                                                             | 6.0                                                                                                                                                                                         |
+| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POSTHOG_CAPTURE_MODE` environment variable                                                                     | Not read. Capture v1 is the only path. The client logs one warning when the variable is set.                                                                                                |
+| `CaptureV1Error` (the error name in capture v1 mode)                                                            | `CaptureError`, exported from `posthog-node`. There is no alias.                                                                                                                            |
+| `captureException(error, distinctId, properties, uuid, flags)`                                                  | `captureException(error, { distinctId, properties, options, uuid, flags, level })`. JavaScript positional calls still work in 6.x. TypeScript callers must use the options object.          |
+| `captureExceptionImmediate(error, distinctId, properties, flags)`                                               | `captureExceptionImmediate(error, { distinctId, properties, options, uuid, flags, level })`. JavaScript positional calls still work in 6.x. TypeScript callers must use the options object. |
+| `prepareEventMessage()` returns `{ distinctId, event, properties, options: { uuid, timestamp, disableGeoip } }` | Returns a flat message: `{ distinctId, event, properties, options, uuid, timestamp, disableGeoip }`. `options` holds the event options.                                                     |
+| `fetchRetryDelay` set capture retry waits                                                                       | Capture ignores it. See [Retries](#retries).                                                                                                                                                |
+
+### `captureException()`
+
+```ts
+// 5.x
+posthog.captureException(error, 'user_123', { endpoint: '/api/users' })
+
+// 6.0
+posthog.captureException(error, {
+  distinctId: 'user_123',
+  properties: { endpoint: '/api/users' },
+  level: 'warning',
+})
+```
+
+- The positional form logs one deprecation error per method per process. It will be removed in the next major version.
+- Arguments after the options object are ignored, with one warning per process.
+- `level` sets `$exception_level`. It is read case-insensitively, and `critical`, `alert` and `emergency` mean `fatal`, `warn` means `warning`, `notice` means `info` and `trace` means `debug`, as in posthog-python. The default is `'error'`, and an unknown value is ignored.
+- Exception properties the SDK owns, such as `$exception_list` and `$exception_level`, are ignored in `properties`. Use `level` instead.
+
+### `prepareEventMessage()`
+
+```ts
+// 5.x
+const { properties, options } = await posthog.prepareEventMessage(message)
+const uuid = options.uuid
+
+// 6.0
+const { properties, options, uuid, timestamp, disableGeoip } = await posthog.prepareEventMessage(message)
+// options is now the event options, such as { process_person_profile: false }
+```
+
+The result is built in the same order as a real event, including `before_send`.
+It still rejects with `null` when `before_send` drops the event.
+
+## Errors and the `'error'` event
+
+Capture v1 returns a result for every event, even when the request succeeds.
+An event can be dropped inside a `2xx` response, for example when it is over a product quota.
+6.0 reports those events as failures.
+When the whole request is over the billing limit, capture answers `402`, which fails the batch without a retry.
+
+`flush()`, `shutdown()` and `captureImmediate()` no longer reject when delivery fails.
+Every delivery failure arrives on the `'error'` event as a `CaptureError`:
+
+```ts
+import { PostHog, CaptureError } from 'posthog-node'
+
+const posthog = new PostHog('<project_api_key>', { host: 'https://us.i.posthog.com' })
+
+posthog.on('error', (error) => {
+  if (error instanceof CaptureError) {
+    // error.endpoint: '/i/v1/analytics/events' or '/i/v1/ai/events'
+    // error.requestId: the PostHog-Request-Id of the failed request, or '' for a local drop
+    // error.drops: [{ uuid, details }] for events that were dropped
+    // error.retryExhausted: uuids still unsent when retries ran out, or lost with a failed request
+    // error.cause: the underlying HTTP or network error, when the whole request failed
+  }
+})
+```
+
+- `details` names the reason, for example a capture result such as `invalid_options` or `duplicate_event_uuid`, or a local reason: `queue full`, `event too large` or `invalid event`.
+- A local drop report lists at most 100 uuids. Its message carries the full count.
+- An event with no result in a `2xx` response counts as delivered. A proxy that answers the capture path with its own `200` therefore reports nothing. Make sure your proxy passes the capture response through.
+- With no `'error'` listener, the SDK logs one warning per failed batch, for example `[PostHog] 3 event(s) were not delivered to /i/v1/analytics/events: 3 failed with HTTP 400`. The line never contains event content, uuids or the server's response text.
+- 5.x emitted the raw HTTP or network error. Update any code or log-based alerts that match the old errors.
+
+## Retries
+
+The SDK retries `404`, `408`, `429`, `500`, `502`, `503` and `504` responses and network errors.
+Every other status fails the batch at once.
+5.x retried `408`, `429` and every `5xx`, but not `404`.
+A proxy in front of capture can return `404` or `429`.
+
+- `captureMaxRetries` (new) sets how many times a capture request is retried after its first attempt, on both lanes. It accepts 0 to 9. When it is not set, the SDK uses `fetchRetryCount` (default 3).
+- Waits start at 100 ms and double each retry, up to 30 seconds. Each wait varies randomly by up to 25%, so many clients do not retry at the same moment.
+- A `Retry-After` header sets the minimum wait, up to 30 seconds.
+- `fetchRetryDelay` (default 3000 ms) no longer affects capture. It still applies to other requests.
+- Events whose last attempt got no response, such as after a network error or a timeout, stay in the queue and are sent again on the next flush.
+
+## Lanes, batching and sizes
+
+Analytics events and `captureAi()` events use separate lanes.
+Each lane has its own queue, batches and requests, so a slow or failing lane never delays or drops the other lane's events.
+
+- Batches stop before an event that would take them past about 5 MiB of serialized events. `flushAt` and `maxBatchSize` still cap the number of events.
+- An analytics event larger than 10 MiB is dropped before sending and reported through `'error'`.
+- `maxQueueSize` (default 10000) now applies to analytics events only. When a queue is full, the oldest event is dropped and reported through `'error'`.
+- `flush()` and `shutdown()` send both lanes at the same time. `shutdown(shutdownTimeoutMs)` uses one deadline for both. Events still queued at the deadline are reported through `'error'`.
+- The `'flush'` event fires once per lane.
+- `captureCompression` (new) sets how analytics requests are compressed: `'none'`, `'gzip'`, `'deflate'` or `'zstd'`. The default is `'gzip'`. `disableCompression: true` still turns compression off when `captureCompression` is not set. `'zstd'` needs Node 22.15 or later and falls back to `'gzip'` elsewhere, including the edge build.
+- `requestTimeout` (default 10000 ms) still sets the timeout of analytics requests.
+
+## AI events
+
+`captureAi()` and `captureAiImmediate()` send to `/i/v1/ai/events`.
+In 5.x they sent to the legacy AI endpoint.
+
+- An AI event whose `properties` are larger than 8 MiB is dropped before sending and reported through `'error'`.
+- The AI lane has its own settings. It does not read `maxQueueSize`, `requestTimeout`, `captureCompression` or `disableCompression`.
+
+  | Option                      | Default  | What it does                                                             |
+  | --------------------------- | -------- | ------------------------------------------------------------------------ |
+  | `captureAiMaxQueueSize`     | 1000     | AI events held in memory. When full, the oldest is dropped and reported. |
+  | `captureAiRequestTimeoutMs` | 30000    | Timeout of each AI request, in milliseconds.                             |
+  | `captureAiCompression`      | `'gzip'` | Same values as `captureCompression`.                                     |
+
+- `captureMaxRetries`, `flushAt`, `flushInterval` and `maxBatchSize` apply to both lanes.
+- An invalid value for one of these options is logged once, and the default is used.
+
+`@posthog/ai` sends every AI event with `captureAi()` when the client is posthog-node 6.
+`enableFullAiCapture` then controls only string truncation and media redaction.
+With posthog-node 5, nothing changes: AI events use `capture()` unless `enableFullAiCapture` is set.
+
+## Event options
+
+Capture v1 sends processing options in an `options` object, next to `properties`.
+
+- `capture`, `captureAi`, `identify`, `alias`, `groupIdentify`, `setPersonProperties`, `unsetPersonProperties`, `captureException` and their `Immediate` variants take an `options` field:
+
+  ```ts
+  posthog.capture({
+    distinctId: 'user_123',
+    event: 'signed_up',
+    options: { cookieless_mode: true },
+  })
+  ```
+
+- `registerOptions(options)` (new) sets options on every event, like `register()` does for properties. `unregisterOptions(key)` removes one. Both return a promise.
+- `withContext()` and `enterContext()` accept `options`, which apply to every event in the context.
+- Options are sent as given. The SDK no longer converts their values. PostHog validates them and drops an event whose option value it cannot read, which reaches `'error'` with `details: 'invalid_options'`.
+- An `options` value that is not an object is logged as an error and ignored. The event is still sent.
+- The legacy option properties, the `$`-prefixed properties legacy capture reads as settings, still work. They fill the matching option only when it is unset, and the SDK always removes them from `properties`. Their values are no longer converted, so pass `true` or `false`, not `"true"`.
+
+  | Legacy option property    | Option                    |
+  | ------------------------- | ------------------------- |
+  | `$process_person_profile` | `process_person_profile`  |
+  | `$cookieless_mode`        | `cookieless_mode`         |
+  | `$ignore_sent_at`         | `disable_skew_correction` |
+  | `$product_tour_id`        | `product_tour_id`         |
+
+- An option set at any layer wins over its legacy property set at any layer. For example, `registerOptions({ cookieless_mode: true })` wins over an event's `$cookieless_mode: false` property. When you move a default to options, move the per-event overrides of that key to options too.
+- A `null` or `undefined` option counts as unset, so a later layer can fill it.
+
+## Layer order
+
+Each event is built in this order. Each step fills only the properties and options the steps before it left unset:
+
+1. the call's own `properties` and `options`, then its `groups` (merged into `$groups`) and `disableGeoip` (fills `$geoip_disable`)
+2. context `properties` and `options`, from `withContext()`, `enterContext()` or the Express and NestJS integrations
+3. `register()` properties and `registerOptions()` options
+4. values the SDK adds: `$is_server` (from `isServer`), `$geoip_disable` (from `disableGeoip`), the `$feature/<key>` and `$active_feature_flags` properties (from `flags` or `sendFeatureFlags`), `$trace_id` and `$span_id` from the active OpenTelemetry span on `$exception` events, and `options.process_person_profile = false` for an event without a distinct id
+5. `before_send`, which sees the result of steps 1 to 4 and can change or remove any of it. Nothing is added after it.
+6. legacy option properties, which fill unset options and are then removed
+
+A property set to `undefined` counts as unset.
+`$set`, `$set_once`, `$groups` and `$group_set` fill one level deep.
+When the call and a later step both set one of them to an object, the later step adds only the keys the call left out.
+For example, `register({ $set: { plan: 'free', source: 'web' } })` and a call with `properties: { $set: { plan: 'pro' } }` send `{ plan: 'pro', source: 'web' }`.
+
+These changes follow from this order:
+
+- A `$is_server`, `$geoip_disable` or feature flag property set on the event, in context or with `register()` now wins over the SDK's value. In 5.x the SDK overwrote some of them.
+- `before_send` now sees `$is_server`, `$geoip_disable`, feature flag properties, trace ids and `options`. In 5.x it ran before the SDK added them. To change an option in `before_send`, edit `options`, which is always an object.
+- `before_send` gets its own copy of the event's plain objects and arrays. Changing a nested value no longer changes your objects or the `register()` and context values, as it could in 5.x. Class instances, such as `Date`, are not copied.
+- `$geoip_disable` and `$groups` are set before `before_send`, so to change them, edit the properties. Changing the message's `disableGeoip` or `groups` field has no effect.
+- A `before_send` hook that throws drops the event, as in 5.x. The error log names the event and the error's type, not its message, which can hold the data the hook was removing.
+- With `sendFeatureFlags`, the `/flags` request now runs before `before_send` and uses the event's own distinct id, even for an event the hook then drops. Changes the hook makes to the message's `groups` or `sendFeatureFlags` no longer reach that request, as editing those objects in place could in 5.x. To avoid that request, call `evaluateFlags()` yourself and pass the snapshot as `flags`.
+- Context and `register()` properties and options now reach `identify`, `alias` and `groupIdentify` events, not only `capture`.
+
+## GeoIP
+
+`disableGeoip` still defaults to `true`, so events get `$geoip_disable: true` unless something else sets it.
+
+- A `$geoip_disable` property set on the event, in context, with `register()` or in `before_send` now wins over the client setting. For example, `register({ $geoip_disable: false })` turns GeoIP lookup on for events.
+- A per-call `disableGeoip` argument belongs to that event, so it wins over context and `register()`. A `$geoip_disable` in the call's own `properties` still wins over it.
+- A per-call `disableGeoip: false` now sends `$geoip_disable: false`.
+- Feature flag requests still follow the `disableGeoip` client setting.
+
+## Identity and request context
+
+- An empty or whitespace-only `distinctId` counts as missing. The event uses the context distinct id, or else a generated personless distinct id with `options.process_person_profile = false`. 5.x sent a whitespace-only id, and capture dropped the event.
+- The SDK's `process_person_profile: false` for a personless event fills only an unset option. An option set on the event, in context or with `registerOptions()` wins over it. A `$process_person_profile: true` property no longer turns person processing back on. Set the option instead.
+- `groupIdentify` uses the `distinctId` you pass, then the context distinct id, then `$<groupType>_<groupKey>`. In 5.x it skipped the context id. If `$<groupType>_<groupKey>` is over 200 bytes, pass `distinctId`.
+- `groupIdentify` never adds the context session id.
+- `alias` never takes its alias target from context or `register()`.
+- PostHog drops an event whose distinct id is over 200 UTF-8 bytes (`distinct_id_too_large`), and `'error'` reports it. Legacy capture shortened the id and kept the event.
+- Generated personless distinct ids and event uuids are UUIDv7, with random bits from `crypto.getRandomValues` instead of `Math.random`.
+
+### Tracing headers
+
+The Express and NestJS integrations read the `X-POSTHOG-DISTINCT-ID` and `X-POSTHOG-SESSION-ID` request headers into the request context, as in 5.x.
+These headers only fill a missing distinct id or session id, and any client can set them, so never use them for authentication.
+To stop reading them, set the new client option `captureTracingHeaders: false`:
+
+```ts
+const posthog = new PostHog('<project_api_key>', { captureTracingHeaders: false })
+```
+
+## SDK identity
+
+PostHog sets `$lib` and `$lib_version` on every event from the `PostHog-Sdk-Info` request header, which the client sets.
+The SDK removes `$lib` and `$lib_version` from the properties it sends.
+A value you set on an event, in context, with `register()` or in `before_send` does not reach PostHog.
+
+## Session and window ids
+
+Capture v1 sends `$session_id` and `$window_id` as top-level event fields, not as properties.
+The SDK moves them out of `properties` for you.
+
+- A string is sent as given.
+- `null` and `undefined` count as unset.
+- Any other value is dropped, and the SDK logs a warning with the key and the value's type, not the value. 5.x sent it as a property.
+
+## Invalid events
+
+Capture rejects a whole request when one event has a broken field.
+6.0 drops only that event before sending, so the rest of the batch is delivered.
+
+- An event whose name is missing, empty or not a string is dropped and reported through `'error'` (`details: 'invalid event'`). 5.x sent it, and an object name was sent as `"[object Object]"`.
+- An event whose name, distinct id, session id or window id is not well-formed Unicode (it has a lone surrogate) is dropped the same way.
+- A lone surrogate in a property string is replaced with U+FFFD, and the event is kept. Before, one bad character failed the whole request.
+- `NaN`, `Infinity` and `-Infinity` are sent as `null`, and the event is kept. A `NaN` under `$set` clears that person property.
+- PostHog drops an event whose name is over 200 UTF-8 bytes (`event_name_too_long`), and `'error'` reports it. Legacy capture had no event name limit. Check your event names before you upgrade.
+
+## Timestamps
+
+- Timestamps are sent in UTC, with millisecond precision.
+- An invalid `timestamp` is still replaced with the current time. The SDK now logs a warning, which never includes the value.
+
+## Event uuids
+
+- Each event needs its own uuid. Capture keeps the first event for each uuid in a request and drops the later copies. `'error'` reports each dropped copy in `CaptureError.drops` with `details: 'duplicate_event_uuid'`. 5.x sent every copy to legacy capture.
+- The SDK accepts a uuid with hyphens, 32 hex digits, `{...}` braces or a `urn:uuid:` prefix, in any case. It sends the lowercase hyphenated form, and `captureAi()` returns that form.
+- Any other value is replaced with a generated uuid, and the SDK logs a warning that does not include the value. An empty string counts as unset.
+
+## API keys
+
+- A missing or empty project API key disables the client, as in 5.x.
+- A personal API key (`phx_...`) passed as the project API key now disables the client too. Capture rejects personal API keys.
+- Either case logs one error, which never includes the key.
+- A disabled client sends nothing. To build one on purpose, for example in tests, pass `disabled: true`.
+
+## Logs
+
+The SDK's own logs no longer print whole events or `before_send` error messages.
+
+- Debug mode logs event names, uuids and counts instead of whole events.
+- A `before_send` error is logged with the error's type, not its message.
+- In debug mode, a capture error can still include the server or proxy response text.
+- The failed-batch line, the invalid uuid warning, the invalid timestamp warning and the session id warning never include event values.
+- Log-based alerts that match 5.x log text will stop matching. Listen for `'error'` instead.
+
+## Wrapper packages
+
+| Package                                             | Works with                                                                    |
+| --------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `@posthog/ai`                                       | posthog-node 5 and 6. On 6 it sends AI events with `captureAi()`.             |
+| `@posthog/mcp`                                      | posthog-node 5 and 6                                                          |
+| `@posthog/convex`, `@posthog/next`, `@posthog/nuxt` | posthog-node 5. They move to posthog-node 6 in their own next major versions. |
+
+Upgrade `@posthog/ai` and `@posthog/mcp` to a version that accepts posthog-node 6 before or together with posthog-node.
+
+## posthog-node 5.x support
+
+posthog-node 5.x keeps receiving security fixes for at least one year after the 6.0 release.
diff --git a/packages/node/README.md b/packages/node/README.md
index 434eddea61..c93d4fede4 100644
--- a/packages/node/README.md
+++ b/packages/node/README.md
@@ -2,6 +2,8 @@
 
 Please see the main [PostHog docs](https://posthog.com/docs).
 
+Upgrading from 5.x? See [MIGRATION.md](./MIGRATION.md).
+
 SDK usage examples and code snippets live in the official documentation so they stay up to date.
 
 ## Documentation

From 6f350fef7518abd999739035e81b369e425a29a5 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Fri, 30 Oct 2026 18:52:30 -0700
Subject: [PATCH 18/20] fix(ai): set the personless option on AI events with no
 user id (#5497)

* fix(ai): set the personless option on AI events with no user id

On posthog-node 6 an option beats its legacy property at every layer, so a
registered or context `process_person_profile: true` turned person processing
on for AI events keyed by a trace id. Each integration now sets the option
alongside the property; posthog-node 5 ignores options and keeps reading the
property.

An empty or whitespace-only distinct id now counts as missing in every
integration, so those events use the trace or run id and stay personless.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): note the @posthog/ai personless option in the 6.0 guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/posthog-ai-personless-option.md    |  5 +++
 packages/ai/src/adk/plugin.ts                 | 20 ++++--------
 packages/ai/src/captureAiEvent.ts             | 24 ++++++++++++++
 packages/ai/src/captureAiGeneration.ts        |  9 ++++--
 packages/ai/src/claude-agent-sdk/processor.ts |  8 ++---
 packages/ai/src/langchain/callbacks.ts        |  6 ++--
 packages/ai/src/openai-agents/processor.ts    | 16 +++-------
 packages/ai/tests/adk.test.ts                 | 27 +++++++++++-----
 packages/ai/tests/callbacks.test.ts           | 26 ++++++++++++++++
 packages/ai/tests/captureAiGeneration.test.ts | 31 ++++++++++++++-----
 packages/ai/tests/claude-agent-sdk.test.ts    | 15 +++++++++
 packages/ai/tests/openai-agents.test.ts       | 12 ++++---
 packages/node/MIGRATION.md                    |  1 +
 13 files changed, 148 insertions(+), 52 deletions(-)
 create mode 100644 .changeset/posthog-ai-personless-option.md

diff --git a/.changeset/posthog-ai-personless-option.md b/.changeset/posthog-ai-personless-option.md
new file mode 100644
index 0000000000..fddc7350fc
--- /dev/null
+++ b/.changeset/posthog-ai-personless-option.md
@@ -0,0 +1,5 @@
+---
+'@posthog/ai': patch
+---
+
+An AI event with no user distinct id now also sets the `process_person_profile: false` event option, so with posthog-node 6 it stays personless even when a context or registered option turns person processing on. An empty or whitespace-only distinct id now counts as missing in every integration, so the event uses the trace or run id and stays personless.
diff --git a/packages/ai/src/adk/plugin.ts b/packages/ai/src/adk/plugin.ts
index 39c3e18fe7..fddea3762c 100644
--- a/packages/ai/src/adk/plugin.ts
+++ b/packages/ai/src/adk/plugin.ts
@@ -13,7 +13,7 @@ import {
 } from '../utils'
 import { sanitizeGemini } from '../sanitization'
 import { captureAiGeneration } from '../captureAiGeneration'
-import { captureAiEvent, captureAiEventImmediate } from '../captureAiEvent'
+import { captureAiEvent, captureAiEventImmediate, personlessOptions, userDistinctId } from '../captureAiEvent'
 import { formatAiError } from '../serializeError'
 import type { FormattedContent, FormattedMessage } from '../types'
 import { mapGeminiUsage } from '../gemini/usage'
@@ -516,6 +516,7 @@ export class PostHogADKPlugin extends BasePlugin {
         ...(distinctId ? {} : { $process_person_profile: false }),
       },
       groups: this._groups,
+      ...personlessOptions(!distinctId),
     }
 
     if (this._captureImmediate) {
@@ -526,22 +527,13 @@ export class PostHogADKPlugin extends BasePlugin {
   }
 
   private _resolveDistinctId(context: Context): string | undefined {
-    if (typeof this._distinctId === 'function') {
-      const resolved = this._distinctId(context)
-      if (resolved) {
-        return String(resolved)
-      }
-    } else if (this._distinctId) {
-      return String(this._distinctId)
-    }
-    return context.userId ? String(context.userId) : undefined
+    const configured = typeof this._distinctId === 'function' ? this._distinctId(context) : this._distinctId
+    return userDistinctId(configured) ?? userDistinctId(context.userId)
   }
 
   private _resolveInvocationDistinctId(context: InvocationContext): string | undefined {
-    if (typeof this._distinctId === 'string' && this._distinctId) {
-      return String(this._distinctId)
-    }
-    return context.userId ? String(context.userId) : undefined
+    const configured = typeof this._distinctId === 'string' ? this._distinctId : undefined
+    return userDistinctId(configured) ?? userDistinctId(context.userId)
   }
 
   private _rememberContext(context: Context): void {
diff --git a/packages/ai/src/captureAiEvent.ts b/packages/ai/src/captureAiEvent.ts
index bfc2d1ce3f..ee8e800e24 100644
--- a/packages/ai/src/captureAiEvent.ts
+++ b/packages/ai/src/captureAiEvent.ts
@@ -19,6 +19,30 @@ export function isFullAiCaptureEnabled(client?: FullAiCaptureGate): boolean {
   return client?.enableFullAiCapture === true
 }
 
+/**
+ * The caller's distinct id as a string, or undefined when it is missing, empty or only whitespace.
+ *
+ * @internal
+ */
+export function userDistinctId(value: unknown): string | undefined {
+  if (!value) {
+    return undefined
+  }
+  const id = String(value)
+  return id.trim() === '' ? undefined : id
+}
+
+/**
+ * Turns person processing off for an AI event with no user distinct id. On posthog-node 6 the
+ * option beats context and global options, which the legacy `$process_person_profile` property
+ * cannot do. posthog-node 5 ignores options and reads the property, so callers set both.
+ *
+ * @internal
+ */
+export function personlessOptions(personless: boolean): Pick<EventMessage, 'options'> {
+  return personless ? { options: { process_person_profile: false } } : {}
+}
+
 /**
  * posthog-node 6 sends every AI event on its capture v1 AI lane; `enableFullAiCapture` then only
  * controls truncation and media redaction. posthog-node 5 keeps the opt-in, so an `@posthog/ai`
diff --git a/packages/ai/src/captureAiGeneration.ts b/packages/ai/src/captureAiGeneration.ts
index b3a5a57a90..55d410be09 100644
--- a/packages/ai/src/captureAiGeneration.ts
+++ b/packages/ai/src/captureAiGeneration.ts
@@ -7,7 +7,7 @@ import { formatAiError } from './serializeError'
 import { AIEvent, CostOverride, getTokensSource, hasTokenOverrides, isPrivacyModeEnabled } from './utils'
 import { redactMcpToolCredentials } from './mcpCredentials'
 import { warnIfPostHogAiGateway } from './gatewayWarning'
-import { captureAiEvent, captureAiEventImmediate } from './captureAiEvent'
+import { captureAiEvent, captureAiEventImmediate, personlessOptions, userDistinctId } from './captureAiEvent'
 
 /**
  * Options for `captureAiGeneration`. Mirrors the `$ai_generation` event shape
@@ -231,6 +231,8 @@ export const captureAiGeneration = async (client: PostHog, options: CaptureAiGen
       ...(usage.rawUsage ? { $ai_usage: usage.rawUsage } : {}),
     }
 
+    const distinctId = userDistinctId(options.distinctId)
+
     const properties: Record<string, unknown> = {
       $ai_lib: 'posthog-ai',
       $ai_lib_version: version,
@@ -250,7 +252,7 @@ export const captureAiGeneration = async (client: PostHog, options: CaptureAiGen
       ...(options.baseURL === null ? {} : { $ai_base_url: options.baseURL ?? '' }),
       ...options.properties,
       $ai_tokens_source: getTokensSource(options.properties),
-      ...(options.distinctId ? {} : { $process_person_profile: false }),
+      ...(distinctId ? {} : { $process_person_profile: false }),
       ...(options.stopReason ? { $ai_stop_reason: options.stopReason } : {}),
       ...(options.tools ? { $ai_tools: redactMcpToolCredentials(options.tools) } : {}),
       ...(options.completionId ? { $ai_completion_id: options.completionId } : {}),
@@ -262,10 +264,11 @@ export const captureAiGeneration = async (client: PostHog, options: CaptureAiGen
     }
 
     const event: EventMessage = {
-      distinctId: options.distinctId ?? traceId,
+      distinctId: distinctId ?? traceId,
       event: eventType,
       properties,
       groups: options.groups,
+      ...personlessOptions(!distinctId),
     }
 
     if (options.captureImmediate) {
diff --git a/packages/ai/src/claude-agent-sdk/processor.ts b/packages/ai/src/claude-agent-sdk/processor.ts
index ab1254b64f..aed46daac8 100644
--- a/packages/ai/src/claude-agent-sdk/processor.ts
+++ b/packages/ai/src/claude-agent-sdk/processor.ts
@@ -11,7 +11,7 @@ import type {
 import type { EventMessage, PostHog } from 'posthog-node'
 import { v4 as uuidv4 } from 'uuid'
 import { version } from '../../package.json'
-import { captureAiEvent, captureAiEventImmediate } from '../captureAiEvent'
+import { captureAiEvent, captureAiEventImmediate, personlessOptions, userDistinctId } from '../captureAiEvent'
 import { captureAiGeneration } from '../captureAiGeneration'
 import type { CaptureAiGenerationOptions } from '../captureAiGeneration'
 import { formatAiError } from '../serializeError'
@@ -834,6 +834,7 @@ export class PostHogClaudeAgentProcessor {
         ...(distinctId ? {} : { $process_person_profile: false }),
       },
       groups: trace.groups,
+      ...personlessOptions(!distinctId),
     }
 
     try {
@@ -887,8 +888,7 @@ function resolveDistinctId(resolver: DistinctIdResolver | undefined, result?: SD
     if (!result) {
       return undefined
     }
-    const resolved = resolver(result)
-    return resolved ? String(resolved) : undefined
+    return userDistinctId(resolver(result))
   }
-  return resolver ? String(resolver) : undefined
+  return userDistinctId(resolver)
 }
diff --git a/packages/ai/src/langchain/callbacks.ts b/packages/ai/src/langchain/callbacks.ts
index 4071b98893..597355989e 100644
--- a/packages/ai/src/langchain/callbacks.ts
+++ b/packages/ai/src/langchain/callbacks.ts
@@ -15,7 +15,7 @@ import { formatAiError } from '../serializeError'
 import { warnIfPostHogAiGateway } from '../gatewayWarning'
 import { isObject } from '../typeGuards'
 import { responsesStopReason } from '../openai/utils'
-import { captureAiEvent } from '../captureAiEvent'
+import { captureAiEvent, personlessOptions, userDistinctId } from '../captureAiEvent'
 
 // Mirror LangGraph's isGraphBubbleUp guard without adding LangGraph as a dependency. Every
 // LangGraph control-flow exception (GraphInterrupt, NodeInterrupt, ParentCommand, GraphDrained,
@@ -84,7 +84,7 @@ export class LangChainCallbackHandler extends BaseCallbackHandler {
     }
     super()
     this.client = options.client
-    this.distinctId = options.distinctId
+    this.distinctId = userDistinctId(options.distinctId)
     this.traceId = options.traceId
     this.properties = options.properties || {}
     this.privacyMode = options.privacyMode || false
@@ -484,6 +484,7 @@ export class LangChainCallbackHandler extends BaseCallbackHandler {
       event: eventName,
       properties: eventProperties,
       groups: this.groups,
+      ...personlessOptions(!this.distinctId),
     })
   }
 
@@ -617,6 +618,7 @@ export class LangChainCallbackHandler extends BaseCallbackHandler {
       event: '$ai_generation',
       properties: eventProperties,
       groups: this.groups,
+      ...personlessOptions(!this.distinctId),
     })
   }
 
diff --git a/packages/ai/src/openai-agents/processor.ts b/packages/ai/src/openai-agents/processor.ts
index db9b3c3450..b6aafcc24e 100644
--- a/packages/ai/src/openai-agents/processor.ts
+++ b/packages/ai/src/openai-agents/processor.ts
@@ -29,7 +29,7 @@ import {
 import { summarizeErrorForPrivacy } from '../serializeError'
 import { version } from '../../package.json'
 import { warnIfPostHogAiGateway } from '../gatewayWarning'
-import { captureAiEvent, isFullAiCaptureEnabled } from '../captureAiEvent'
+import { captureAiEvent, isFullAiCaptureEnabled, personlessOptions, userDistinctId } from '../captureAiEvent'
 import { extractCacheWriteTokens } from '../openai/utils'
 
 /**
@@ -172,17 +172,9 @@ export class PostHogTracingProcessor implements TracingProcessor {
 
   private _getDistinctId(trace: Trace | null): string | undefined {
     if (typeof this._distinctId === 'function') {
-      if (trace) {
-        const result = this._distinctId(trace)
-        if (result) {
-          return String(result)
-        }
-      }
-      return undefined
-    } else if (this._distinctId) {
-      return String(this._distinctId)
+      return trace ? userDistinctId(this._distinctId(trace)) : undefined
     }
-    return undefined
+    return userDistinctId(this._distinctId)
   }
 
   private _withPrivacyMode(value: unknown): unknown {
@@ -242,6 +234,8 @@ export class PostHogTracingProcessor implements TracingProcessor {
         event,
         properties: finalProperties,
         groups: Object.keys(this._groups).length > 0 ? this._groups : undefined,
+        // `properties` holds only values this processor built, so the flag here is its own personless marker.
+        ...personlessOptions(properties.$process_person_profile === false),
       }
 
       captureAiEvent(this._client, eventMessage)
diff --git a/packages/ai/tests/adk.test.ts b/packages/ai/tests/adk.test.ts
index 9c04586f70..8d998842cb 100644
--- a/packages/ai/tests/adk.test.ts
+++ b/packages/ai/tests/adk.test.ts
@@ -480,15 +480,28 @@ describe('PostHogADKPlugin', () => {
       expect(capturedEvent(client).distinctId).toBe('adk-user')
     })
 
-    it('captures anonymously (personless) when there is no distinctId or userId', async () => {
-      plugin = new PostHogADKPlugin({ client })
-      const ctx = createContext({ userId: '' })
+    it('falls back to the ADK userId when the distinctId option is only whitespace', async () => {
+      plugin = new PostHogADKPlugin({ client, distinctId: '  ' })
+      const ctx = createContext({ userId: 'adk-user' })
       await plugin.beforeModelCallback({ callbackContext: ctx, llmRequest: createRequest() })
       await plugin.afterModelCallback({ callbackContext: ctx, llmResponse: createResponse() })
-      const event = capturedEvent(client)
-      expect(event.distinctId).toBe('inv_123')
-      expect(event.properties.$process_person_profile).toBe(false)
-    })
+      expect(capturedEvent(client).distinctId).toBe('adk-user')
+      expect(capturedEvent(client).options).toBeUndefined()
+    })
+
+    it.each(['', '  '])(
+      'captures anonymously (personless) when there is no distinctId and the userId is %j',
+      async (userId) => {
+        plugin = new PostHogADKPlugin({ client })
+        const ctx = createContext({ userId })
+        await plugin.beforeModelCallback({ callbackContext: ctx, llmRequest: createRequest() })
+        await plugin.afterModelCallback({ callbackContext: ctx, llmResponse: createResponse() })
+        const event = capturedEvent(client)
+        expect(event.distinctId).toBe('inv_123')
+        expect(event.properties.$process_person_profile).toBe(false)
+        expect(event.options).toEqual({ process_person_profile: false })
+      }
+    )
   })
 
   it('redacts input and output content in privacy mode', async () => {
diff --git a/packages/ai/tests/callbacks.test.ts b/packages/ai/tests/callbacks.test.ts
index fa66597a91..61cdc4530f 100644
--- a/packages/ai/tests/callbacks.test.ts
+++ b/packages/ai/tests/callbacks.test.ts
@@ -80,6 +80,32 @@ describe('LangChainCallbackHandler', () => {
     expect(captureCall[0].properties.$ai_provider).toBe('openai')
   })
 
+  it.each([
+    { distinctId: undefined, personless: true },
+    { distinctId: '', personless: true },
+    { distinctId: '  ', personless: true },
+    { distinctId: 'user-1', personless: false },
+  ])('marks events personless only without a user distinct id: $distinctId', ({ distinctId, personless }) => {
+    const capture = mockPostHogClient.capture as vi.Mock
+    const personlessHandler = new LangChainCallbackHandler({ client: mockPostHogClient, distinctId })
+    const llm = { lc: 1, type: 'constructor', id: ['langchain', 'llms', 'openai', 'OpenAI'], kwargs: {} } as const
+    const chain = { lc: 1, type: 'constructor', id: ['langchain', 'chains', 'TestChain'], kwargs: {} } as const
+
+    personlessHandler.handleLLMStart(llm, ['Hello'], 'run_llm', undefined, { invocation_params: {} })
+    personlessHandler.handleLLMEnd({ generations: [[{ text: 'Hi' }]], llmOutput: {} }, 'run_llm')
+    personlessHandler.handleChainStart(chain, {}, 'run_chain')
+    personlessHandler.handleChainEnd({}, 'run_chain')
+
+    const events = capture.mock.calls.map(([event]) => event)
+    expect(events.map((event) => event.distinctId)).toEqual(
+      personless ? ['run_llm', 'run_chain'] : ['user-1', 'user-1']
+    )
+    for (const event of events) {
+      expect(event.properties.$process_person_profile).toBe(personless ? false : undefined)
+      expect(event.options).toEqual(personless ? { process_person_profile: false } : undefined)
+    }
+  })
+
   it('does not throw when generation capture fails', () => {
     const capture = mockPostHogClient.capture as vi.Mock
     capture.mockImplementationOnce(() => {
diff --git a/packages/ai/tests/captureAiGeneration.test.ts b/packages/ai/tests/captureAiGeneration.test.ts
index 2fef0fffa3..ed486e9343 100644
--- a/packages/ai/tests/captureAiGeneration.test.ts
+++ b/packages/ai/tests/captureAiGeneration.test.ts
@@ -79,6 +79,7 @@ describe('captureAiGeneration', () => {
     })
     expect(event.properties.$ai_tools).toEqual([{ type: 'function', function: { name: 'foo', parameters: {} } }])
     expect(event.properties.$process_person_profile).toBeUndefined()
+    expect(event.options).toBeUndefined()
   })
 
   it.each([
@@ -96,17 +97,33 @@ describe('captureAiGeneration', () => {
     }
   })
 
-  it('auto-generates a traceId and uses it as distinctId when missing', async () => {
+  it.each([undefined, '', '  '])(
+    'auto-generates a traceId and uses it as a personless distinctId when the distinctId is %j',
+    async (distinctId) => {
+      const client = buildClient()
+
+      await captureAiGeneration(client, { ...baseRequiredOptions, distinctId })
+
+      const event = (client.capture as vi.Mock).mock.calls[0][0]
+      expect(event.properties.$ai_trace_id).toEqual(expect.any(String))
+      expect(event.properties).not.toHaveProperty('$ai_latency')
+      expect(event.distinctId).toBe(event.properties.$ai_trace_id)
+      expect(event.properties.$process_person_profile).toBe(false)
+      expect(event.options).toEqual({ process_person_profile: false })
+    }
+  )
+
+  it('stays personless on posthog-node 6 when a process_person_profile option is registered', async () => {
+    const { PostHog: RealPostHog } = await vi.importActual<typeof import('posthog-node')>('posthog-node')
+    const posthog = new RealPostHog('TEST_API_KEY', { host: 'http://example.com' })
+    await posthog.registerOptions({ process_person_profile: true })
     const client = buildClient()
 
     await captureAiGeneration(client, baseRequiredOptions)
+    const message = await posthog.prepareEventMessage((client.capture as vi.Mock).mock.calls[0][0])
+    await posthog.shutdown()
 
-    const event = (client.capture as vi.Mock).mock.calls[0][0]
-    expect(event.properties.$ai_trace_id).toEqual(expect.any(String))
-    expect(event.properties).not.toHaveProperty('$ai_latency')
-    expect(event.distinctId).toBe(event.properties.$ai_trace_id)
-    // Anonymous events disable person processing
-    expect(event.properties.$process_person_profile).toBe(false)
+    expect(message.options).toEqual({ process_person_profile: false })
   })
 
   it('honours captureImmediate by awaiting captureImmediate instead of capture', async () => {
diff --git a/packages/ai/tests/claude-agent-sdk.test.ts b/packages/ai/tests/claude-agent-sdk.test.ts
index b53c92554f..3053178526 100644
--- a/packages/ai/tests/claude-agent-sdk.test.ts
+++ b/packages/ai/tests/claude-agent-sdk.test.ts
@@ -762,9 +762,24 @@ describe('Claude Agent SDK integration', () => {
     const generation = capturedEvents(client, '$ai_generation')[0]
     expect(generation.distinctId).toBe('sess_123')
     expect(generation.properties.$process_person_profile).toBeUndefined()
+    expect(generation.options).toBeUndefined()
+    expect(trace.options).toBeUndefined()
     expect(generation.properties.environment).toBe('production')
   })
 
+  it.each([undefined, '', '  '])('captures personless events when the distinct ID is %j', async (distinctId) => {
+    const client = createMockClient()
+    queryMock.mockReturnValue(scriptedQuery([messageStart(), messageStop(), resultMessage()]))
+
+    await drain(query({ prompt: 'Hello', posthog: { client, distinctId } }))
+
+    for (const event of [capturedEvents(client, '$ai_trace')[0], capturedEvents(client, '$ai_generation')[0]]) {
+      expect(event.distinctId).toBe(event.properties.$ai_trace_id)
+      expect(event.properties.$process_person_profile).toBe(false)
+      expect(event.options).toEqual({ process_person_profile: false })
+    }
+  })
+
   it('rotates turn state when result processing fails before trace capture', async () => {
     const client = createMockClient()
     const brokenResult = resultMessage()
diff --git a/packages/ai/tests/openai-agents.test.ts b/packages/ai/tests/openai-agents.test.ts
index a20f1c7312..a02c5e9c0d 100644
--- a/packages/ai/tests/openai-agents.test.ts
+++ b/packages/ai/tests/openai-agents.test.ts
@@ -178,8 +178,8 @@ describe('PostHogTracingProcessor', () => {
   })
 
   describe('personless mode', () => {
-    it('uses personless mode when no distinct_id is provided', async () => {
-      const proc = new PostHogTracingProcessor({ client: mockClient })
+    it.each([undefined, '', '  '])('uses personless mode when the distinct_id is %j', async (distinctId) => {
+      const proc = new PostHogTracingProcessor({ client: mockClient, distinctId })
       const trace = createMockTrace()
 
       await proc.onTraceStart(trace as any)
@@ -187,6 +187,7 @@ describe('PostHogTracingProcessor', () => {
 
       const call = mockClient.capture.mock.calls[0][0]
       expect(call.properties.$process_person_profile).toBe(false)
+      expect(call.options).toEqual({ process_person_profile: false })
       expect(call.distinctId).toBe(trace.traceId)
     })
 
@@ -205,13 +206,14 @@ describe('PostHogTracingProcessor', () => {
 
       const call = mockClient.capture.mock.calls[0][0]
       expect(call.properties.$process_person_profile).toBe(false)
+      expect(call.options).toEqual({ process_person_profile: false })
       expect(call.distinctId).toBe(trace.traceId)
     })
 
-    it('uses personless mode when callable distinct_id returns null', async () => {
+    it.each([null, '  '])('uses personless mode when callable distinct_id returns %j', async (resolved) => {
       const proc = new PostHogTracingProcessor({
         client: mockClient,
-        distinctId: () => null,
+        distinctId: () => resolved,
       })
       const trace = createMockTrace()
       const span = createMockSpan({
@@ -226,6 +228,7 @@ describe('PostHogTracingProcessor', () => {
 
       const call = mockClient.capture.mock.calls[0][0]
       expect(call.properties.$process_person_profile).toBe(false)
+      expect(call.options).toEqual({ process_person_profile: false })
       expect(call.distinctId).toBe(trace.traceId)
     })
 
@@ -236,6 +239,7 @@ describe('PostHogTracingProcessor', () => {
 
       const call = mockClient.capture.mock.calls[0][0]
       expect(call.properties.$process_person_profile).toBeUndefined()
+      expect(call.options).toBeUndefined()
     })
   })
 
diff --git a/packages/node/MIGRATION.md b/packages/node/MIGRATION.md
index 81ffa0e6f5..fdec09d29a 100644
--- a/packages/node/MIGRATION.md
+++ b/packages/node/MIGRATION.md
@@ -186,6 +186,7 @@ In 5.x they sent to the legacy AI endpoint.
 `@posthog/ai` sends every AI event with `captureAi()` when the client is posthog-node 6.
 `enableFullAiCapture` then controls only string truncation and media redaction.
 With posthog-node 5, nothing changes: AI events use `capture()` unless `enableFullAiCapture` is set.
+When an `@posthog/ai` integration has no user distinct id, it sends the event under the trace or run id with the option `process_person_profile: false`, so a `registerOptions()` or context `process_person_profile: true` doesn't create a person for each trace. An empty or whitespace-only distinct id counts as missing.
 
 ## Event options
 

From 2ad361cf1ddad5dc85c7b1a93c0279e21a64e322 Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Fri, 30 Oct 2026 18:52:53 -0700
Subject: [PATCH 19/20] docs(node): ask users to review before_send hooks for
 the 6.0 event shape (#5498)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/node/MIGRATION.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/node/MIGRATION.md b/packages/node/MIGRATION.md
index fdec09d29a..f1be89c8b4 100644
--- a/packages/node/MIGRATION.md
+++ b/packages/node/MIGRATION.md
@@ -238,6 +238,7 @@ These changes follow from this order:
 
 - A `$is_server`, `$geoip_disable` or feature flag property set on the event, in context or with `register()` now wins over the SDK's value. In 5.x the SDK overwrote some of them.
 - `before_send` now sees `$is_server`, `$geoip_disable`, feature flag properties, trace ids and `options`. In 5.x it ran before the SDK added them. To change an option in `before_send`, edit `options`, which is always an object.
+- Review your `before_send` hooks for the new event shape. A legacy property such as `$process_person_profile` that the hook sets does not replace an option that is already set. A hook that returns a new message must copy `options`, or the event is sent without them. That includes the `process_person_profile: false` the SDK sets for an event without a distinct id, so PostHog would create a person for its generated id.
 - `before_send` gets its own copy of the event's plain objects and arrays. Changing a nested value no longer changes your objects or the `register()` and context values, as it could in 5.x. Class instances, such as `Date`, are not copied.
 - `$geoip_disable` and `$groups` are set before `before_send`, so to change them, edit the properties. Changing the message's `disableGeoip` or `groups` field has no effect.
 - A `before_send` hook that throws drops the event, as in 5.x. The error log names the event and the error's type, not its message, which can hold the data the hook was removing.

From 4811d54f1d1b0b180ec6a35b1e841dff653126be Mon Sep 17 00:00:00 2001
From: Eli Reisman <eli.r@posthog.com>
Date: Fri, 30 Oct 2026 18:53:22 -0700
Subject: [PATCH 20/20] docs(node): keep PostHog keys and strip other
 Authorization values behind a proxy (#5486)

* docs(node): say which Authorization values a proxy must keep

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(node): keep every PostHog key type in the proxy checklist

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/node/MIGRATION.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/node/MIGRATION.md b/packages/node/MIGRATION.md
index f1be89c8b4..18b1a59f27 100644
--- a/packages/node/MIGRATION.md
+++ b/packages/node/MIGRATION.md
@@ -46,7 +46,7 @@ A `404` that lasts through every retry can mean the deployment has no capture v1
 If you send events through your own reverse proxy, update it before you upgrade:
 
 - Forward `/i/v1/analytics/events` and `/i/v1/ai/events` to PostHog.
-- Pass `Authorization` through unchanged when it starts with `Bearer `. It carries the project API key, which is no longer in the request body. PostHog answers `401` without it.
+- Pass `Authorization` through unchanged when it starts with `Bearer phc_`, `Bearer phs_` or `Bearer phx_`. `phc_` is the project API key, which is no longer in the request body, and PostHog answers `401` without it. `phs_` and `phx_` are the secret key the SDK sends for local feature flag evaluation and remote config. Also allow the exact `Bearer <key>` value of an older key without one of these prefixes. Strip any other `Authorization` value, such as session tokens your app adds to its own requests. See the [proxy reference](https://posthog.com/docs/advanced/proxy/proxy-reference).
 - Pass every `PostHog-*` header, `Content-Type`, `Content-Encoding` and `User-Agent` through unchanged. PostHog answers `400` without them, and the batch fails.
 - Accept request bodies up to 20 MB. AI requests are often larger than 1 MB, the default limit in nginx and ingress-nginx.