Closed-beta funnel: PostHog taxonomy, identity stitching, funnel insight

Card #4708, epic #4701. Extends docs/architecture/posthog-raxx-adoption.md section 5 (conventions there apply: flat snake_case <object>_<verb_past_tense>, typed property values, base properties app and environment). Emitters in #4707, #4709 and #4710 import the constants; they do not retype names.

Constants (kept identical, enforced by backend_v2/tests/test_beta_funnel_events_parity_4708.py):

1. Rules for every funnel event

• No PII. distinct_id is an id, never an email. Forbidden property keys: email, email_address, name, token, invite_token, ip, ip_address (FORBIDDEN_PROP_KEYS). Invite tokens never appear in any payload or URL property.
• Server capture goes through api/services/posthog_capture.py (flag posthog_events_enabled, fire-and-forget, no-PII backstop). Console never holds a PostHog key; it asks Raptor's internal endpoint to capture (epic default 4).
• Consent gate: client events go through AnalyticsGate.queue() and are buffered until consent (or the NDA-ack interim basis for authenticated beta pages, per adoption doc section 7). Server-truth events (state changes already audited) fire regardless of the browser consent state, carry only ids and enums, and are dropped entirely when posthog_events_enabled is off. Pre-account events never carry anything derivable to an email without ANALYTICS_ID_KEY.
• Customer-facing copy never names a broker or vendor; framing is retrospective.

2. Event taxonomy

"Emitter" is the service that fires the event. Funnel order is BETA_FUNNEL_EVENT_NAMES.

| 17 | beta_lab_started | tester opens the Rules Lab for the first time (lab_started_at set) | Antlers client (#4760) | str(user_id) | cohort=beta | | 18 | beta_lab_mission_started | a mission screen is entered | Antlers client | str(user_id) | mission (1-5) | | 19 | beta_lab_mission_completed | a mission is completed | Antlers client | str(user_id) | mission (1-5), duration_s | | 20 | beta_lab_rule_violation_shown | the blocked-order panel renders (mission 4) | Raptor, on the 422 lab_rule_violation | str(user_id) | rule_type (max_loss, max_positions, delta_range, spread_width); never the symbol or the limit values | | 21 | beta_lab_backtest_completed | mission 5 rule-aware backtest returns | Antlers client | str(user_id) | none beyond defaults | | 22 | beta_lab_completed | recap screen reached (lab_completed_at set) | Antlers client | str(user_id) | none beyond defaults | | 23 | beta_lab_abandoned | tester leaves the lab before the recap (page hide / navigate away) | Antlers client | str(user_id) | last_mission (0-5) |

Lab events carry no tickers, symbols, rule values, comments or tokens. ticker, symbol, underlying, comment and answers are in FORBIDDEN_PROP_KEYS and are stripped by the capture helpers.

Enums: cohort in (preview, beta); survey_trigger in (first_paper_trade_placed, first_backtest_completed, first_strategy_created, lab_completed); rule_type in (max_loss, max_positions, delta_range, spread_width); mission 1-5.

Existing related events, unchanged and not part of the new constant list except as compatibility names (BETA_RELATED_EXISTING_EVENT_NAMES): beta_invite_page_viewed, signup_completed, passkey_enrolled.

Compatibility note: lib/enrollmentFunnel.ts still declares legacy names beta_join_page_viewed and passkey_enrollment_success. The shipped, tested names are those in tests/fixtures/phase1FunnelEventTaxonomy.ts (beta_invite_page_viewed, ...). New code must use the constants above; the legacy names are not funnel steps.

3. Identity stitching

Problem: Phase 1 and the Phase 2 invite happen before an account exists, across Raptor and Console, so PostHog's browser anonymous id is unavailable (server-rendered pages, email-link flows).

Design:

1. Pre-account distinct_id = pre_ + HMAC-SHA256(ANALYTICS_ID_KEY, lowercase(strip(email))) hex (pre_account_distinct_id()). Deterministic across Raptor and Console, so every pre-account event for one tester lands on one person; not reversible or joinable to an email without the secret; the email never reaches PostHog.
2. At join/enrollment (beta_phase2_joined, and also plain signup_completed for a waitlist email), Raptor calls PostHog alias(previous_id=pre_account_id, distinct_id=str(user_id)) once, then continues with str(user_id) (the existing posthog_capture convention). Raptor computes the pre-account id from the account email at that moment; no email is sent.
3. Events after the alias use str(user_id) only. Events for an email with no account stay on the pre-account id.
4. The client-side identifyPostHogUser(userId) merge from the adoption doc section 5 stays as is for the browser anonymous id; the alias above is the server-side link and is independent of it.
5. Missing secret: AnalyticsIdKeyMissing is raised; emitters must skip capture and log, never fall back to a hash of the bare email or the email itself.
6. Rotation: rotating ANALYTICS_ID_KEY splits identities for tester emails not yet aliased. Rotate only with a plan (re-alias or accept the split); aliased users are unaffected.

Secret: ANALYTICS_ID_KEY, 32 random bytes hex. Vault: /Raxx/Raptor/ANALYTICS_ID_KEY in Infisical environments prod and staging. Heroku config var on raxx-api-prod, raxx-api-staging, raxx-console-prod, raxx-console-staging (same value everywhere so one email maps to one id across environments in the shared PostHog project).

4. Funnel insight

PostHog project raxx (id in vault /MooseQuest/posthog/PH_PROJECT_ID_RAXX). The vault holds only the capture key (no Personal API Key), so the insight could not be created via API; create it in the UI: Product analytics, New insight, Funnels.

Definition:

• Name: Closed beta funnel: waitlist to first core action
• Type: Funnel, Steps, ordered ("sequential"), conversion window 60 days, count unique persons.
• Steps in order: waitlist_signed_up, beta_phase1_invited, beta_phase1_opened, beta_phase1_completed, beta_phase2_invited, beta_phase2_opened, beta_phase2_joined, beta_phase2_completed, beta_access_granted, beta_first_run_started, then an "any of" final step: first_paper_trade_placed OR first_backtest_completed OR first_strategy_created.
• Global filter: environment = prod.
• Breakdown (optional second copy): cohort.
• Separate trends insight: beta_micro_survey_shown, beta_micro_survey_answered, beta_micro_survey_dismissed broken down by survey_trigger.

API equivalent (POST /api/projects/<id>/insights/, Personal API Key with insight:write):

{
  "name": "Closed beta funnel: waitlist to first core action",
  "query": {
    "kind": "InsightVizNode",
    "source": {
      "kind": "FunnelsQuery",
      "series": [
        {"kind": "EventsNode", "event": "waitlist_signed_up"},
        {"kind": "EventsNode", "event": "beta_phase1_invited"},
        {"kind": "EventsNode", "event": "beta_phase1_opened"},
        {"kind": "EventsNode", "event": "beta_phase1_completed"},
        {"kind": "EventsNode", "event": "beta_phase2_invited"},
        {"kind": "EventsNode", "event": "beta_phase2_opened"},
        {"kind": "EventsNode", "event": "beta_phase2_joined"},
        {"kind": "EventsNode", "event": "beta_phase2_completed"},
        {"kind": "EventsNode", "event": "beta_access_granted"},
        {"kind": "EventsNode", "event": "beta_first_run_started"},
        {"kind": "ActionsNode", "name": "First core action",
         "custom_name": "First core action (any of paper trade, backtest, strategy)"}
      ],
      "funnelsFilter": {"funnelVizType": "steps", "funnelOrderType": "ordered",
                        "funnelWindowInterval": 60, "funnelWindowIntervalUnit": "day"},
      "properties": [{"type": "event", "key": "environment", "operator": "exact", "value": ["prod"]}]
    }
  }
}

The last step is an Action ("First core action") defined in PostHog as any of the three events; create the action first and put its id in the final ActionsNode.