[eli-r-ph]

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

Problem

• An SDK adding AI capture today has a spec that names only posthog-python and posthog-node, lists /i/v0/ai/batch/ as the route, and ties the routing of PostHog's own AI wrappers to the enable_full_ai_capture flag.

• posthog-python 8.0, posthog-node 6.0, posthog-go v2 and posthog-rs 1.0 ship AI capture on capture v1 (/i/v1/ai/events), and their wrappers always use the AI method.

• The harness has no capture_ai_v1 capability, so an SDK on the v1 AI endpoint cannot be selected for any AI parity case.

• Depends on docs(capture): specify capture v1 delivery for server SDKs #146: the capture and retry-queue rules this spec delegates to land there, so docs(capture): specify capture v1 delivery for server SDKs #146 merges first.

Changes

• capture-ai names all four implementations and adds the Go and Rust method shapes.
• capture-ai gains the capture v1 AI lane: the endpoint, the shared body, headers and per-event results from capture, misrouted_event for a non-AI event on that endpoint, lane isolation, and the analytics endpoint's temporary acceptance of $ai_* events.
• PostHog's AI wrappers always send through the AI method; the full-capture flag now controls only truncation and media redaction, and a wrapper given a client without the AI method turns its own capture off instead of falling back to capture.
  • Breaking for the wrapper contract as written; every v1 wrapper already behaves this way.
• capture-ai gains the lane configuration surface (compression, queue capacity, request timeout, an optional lower-only per-event cap) with its defaults; this supersedes draft docs(capture-ai): specify the AI lane's configuration surface #118.
• capture-ai gains the size rules: an 8 MiB ceiling on properties, a 5 MiB request target, size-aware batching that keeps order, and a content-free oversize log line.
• migration/yaml-parity-v1/capture-ai-v1.feature adds the v1 AI cases under a new capture_ai_v1 capability, reusing the registered step phrases of the v0 feature; the README documents the capability.

Note

posthog-node 6 defaults the AI lane's compression to gzip and the other three SDKs to none. The requirement records the default as the SDK's documented choice rather than picking one.

How did you test this code?

• openspec validate add-capture-ai-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 rule was checked against capture on PostHog/posthog master (rust/capture/src/v1/analytics/router.rs, constants.rs, process.rs) and the four SDK v1 branches; sources are listed in the archived design.md.
• Not run: the harness. No adapter declares capture_ai_v1 yet, so the new feature is discoverable but unselected.

🤖 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

[marandaneto]

Automated advisory code review. Four findings revalidated against the unchanged reviewed patch. Runtime/control reproductions and the static-only limitation are identified in the individual comments.