[eli-r-ph]

⚠️ DO NOT MERGE prior to v1 SDK public release! ⚠️

Problem

• The next SDK to port to capture v1 has no contract to copy: the canonical capture, retry-queue, http-client and event-batcher specs still describe the legacy wire (/batch/, api_key in the body, $lib stamped into properties, global defaults overwriting the call, 429 retried, batches shrunk on 413).
• posthog-python 8.0, posthog-go v2, posthog-rs 1.0 and posthog-node 6.0 already share one capture v1 contract on their v1 branches, worked out during the ports.
• docs(capture-ai): specify the capture v1 AI lane and wrapper routing #147 (the capture v1 AI lane) was approved and squashed into this branch, so this PR lands both.

Changes

• capture gains the capture v1 wire contract: the endpoint, the body envelope, strict field types, the required headers and which ones change on a retry, and the per-event results map with duplicates_dropped.
• capture gains per-event options, the hoisting of the four legacy option properties after before_send, and global and context options where an SDK has global and context properties. SDK docs and examples set these settings through options.
• capture gains the server event-building order: the call wins, context and global values fill only unset keys, SDK values fill last, before_send has the final say. This folds in the flag-property rule from docs(capture): place server feature flag properties in the merge order #145.
  • Breaking for posthog-python and posthog-go users whose global defaults used to overwrite the call; both majors already ship the new order.
• capture gains the rules capture v1 makes observable: blank distinct ids, the $groupidentify fallback id, timestamps at millisecond precision or finer, per-event serialization, $lib/$lib_version sent in properties and stored as sent, with the PostHog-Sdk-Info header only as a fallback, fail-open on a missing or personal API key.
• retry-queue gains the capture v1 status set (404/408/429/500/502/503/504 and network errors retried; 402/413 terminal), four attempts with 100 ms doubling waits and jitter, Retry-After as a clamped floor, and no HTTP-library retries. "429 retryable" and "shrink on 413" are marked legacy.
• http-client gains bearer auth, the accepted Content-Encoding values, and same-origin 307/308 redirects only.
• event-batcher gains byte-aware check-before-append batching and the end of 413 batch shrinking.
• migration/yaml-parity-v1 mirrors the harness capture v1 suite update (posthog-sdk-test-harness#92): 404, 429 and 502 retry scenarios, and the warning result in place of limited, which capture never sends.
• From docs(capture-ai): specify the capture v1 AI lane and wrapper routing #147: capture-ai gains the capture v1 AI lane (/i/v1/ai/events, lane isolation, misrouted_event, size rules and lane configuration), PostHog's AI wrappers always send through the AI method, and capture-ai-v1.feature / capture-ai-v1-delivery.feature add the v1 AI cases under capture_ai_v1.
• Every new requirement is scoped to SDKs that deliver through capture v1; legacy SDKs keep the existing rules and the capture_v0* harness features are untouched.

Note

Three open PRs touch the same ground and need a decision before merge: #145 (folded in here), #140 (requires null for non-finite numbers, while posthog-go v2 drops the event locally; this change records both as allowed), #81 (gzip by default, while the v1 server SDKs default to no compression).

How did you test this code?

• openspec validate add-capture-v1 --type change --strict passed before archiving.
• openspec validate --specs --strict --no-interactive after archiving: 67 passed, 0 failed, the same totals as main.
• Every requirement was checked against capture on PostHog/posthog master (rust/capture/src/v1/) and against the four SDK v1 branches, including their open pre-release PRs. Sources are listed in the archived design.md.
• Harness docs(batching): define replay session and identity boundaries #92 branch with SDK_V2_SPECS pointing at this branch: discovery ready with no missing bindings (160 migrated cases), and the retry and outcome features pass against the harness reference hosts. The harness case-count test needs 157 → 160 when the harness bumps its specs pin.
• Not run: the harness against a real SDK adapter. The scenarios are not opted in with @sdk:server; that needs an end-to-end run against a real adapter.

🤖 Agent context

• Written by Claude Code (Claude Fable 5.1) with the SDK owner directing scope and decisions.
• Skills invoked: writing-pr-descriptions.
• The session surveyed capture-rs, the four SDK branches and the production ingress config, drafted the change with the OpenSpec CLI, archived it, and synced the narrative notes by hand.

🤖 Generated with Claude Code

[turnipdabeets]

A few more from checking the current text against the iOS, Android, Flutter and React Native plugin v1 branches.

[nit] Outside the diff: retry-queue (lines 19, 70, 94, 117), http-client and event-batcher still say Flutter has no Dart queue, transport or batcher of its own and delegates to native or posthog-js. That's no longer true for 6.0 on Windows and Linux.

[dustinbyrne]

Approved with non-blocking comments on token-rule scope, server retry-overlap coverage, and nullable optional-ID parsing. The prior artifact corrections are addressed. The declared public-v1-release prerequisite remains separate; this approval does not clear that gate.

AI-assisted review.

[turnipdabeets]

setup still says wire payload fields (api_key, token) "keep their names and carry the same value" (setup/spec.md:207). On capture v1 this PR sends the token only as Authorization: Bearer <token>, never in the body (capture/spec.md:697, http-client/spec.md:261), so the two disagree for v1 SDKs. Could that line scope the field names to legacy /batch/ delivery, or say the token keeps its value wherever the transport carries it?

[turnipdabeets]

posthog-kmp 0.11 is a capture v1 release too: it wraps posthog-android 4.0, posthog-ios 4.0 and the JVM core 7.0, so Android, JVM, iOS and macOS send to /i/v1/*. JavaScript and Wasm stay on legacy capture through posthog-js. PostHog/posthog-kmp#119 adds the v1 surface, built against this PR:

• options on every event call, as a map sent as given, with registerOptions() / unregisterOptions() and options in beforeSend. JavaScript and Wasm map the four known keys to their legacy properties, as posthog-flutter web does.
• captureAi(), returning the UUID. It's a no-op on JavaScript and Wasm.
• captureAiCompression, captureAiMaxQueueSize, captureAiTimeout and captureAiMaxEventBytes on PostHogConfig, passed through to the native SDKs.

The spec doesn't name posthog-kmp in these places yet:

• openspec/specs/capture/spec.md:5: the client SDKs that move to capture v1.
• openspec/specs/capture/spec.md:860: the SDKs that offer registerOptions() / unregisterOptions().
• openspec/specs/capture-ai/spec.md:26 and openspec/specs/capture-ai/spec.md:123, plus the same list in AI lane configuration is scoped to the AI lane (openspec/specs/capture-ai/spec.md:480): the SDKs that implement captureAi and expose the AI lane settings.

Could you add posthog-kmp 0.11 (native on Android, JVM, iOS and macOS; legacy on JavaScript and Wasm) next to posthog-flutter 6.0 in each?

[turnipdabeets]

[suggestion] Could we extend this rule to client SDKs too? posthog-ios#1067 and posthog-android#979 now ignore a registered $process_person_profile, and a wrapper-registered process_person_profile option, on the same six events. Flutter and KMP inherit that from native, and a posthog-flutter PR for the desktop (Dart) path is coming.

The reason is the same as on the server, and stronger: in 3.x the client SDKs overwrote a registered $process_person_profile with their own value, so a registered false never blocked identify. Without this, 4.0 would start dropping those calls for apps that register false.

How the client version differs from the server rule:

• It removes the registered value instead of setting true. Ingestion treats the two the same, and the SDK's own personless false for an anonymous user still applies, which is the client counterpart of the generated-id exception.
• A value passed on the call, or set in before_send, still applies.
• person_profiles: never still skips these calls.

So we'd replace "On a client SDK, global and registered layers still reach these events like any other event" with something like: "A client SDK SHALL NOT apply a registered $process_person_profile property or registered process_person_profile option to an identify-style event; a value set on the call or in before_send still applies." We'd also tag the layered-personless scenarios below @client too, or add client scenarios for a registered false, a call false, a before_send false, and an ordinary-event control.

[turnipdabeets]

[suggestion] The register spec needs the same exception: openspec/specs/register/spec.md says registered properties reach every later event (step 6), and that identify / alias / group include them too. For $process_person_profile, those two lines would need to exclude the six identity events, matching the capture rule above.