#Journey stage machine (T1.4)

Canonical state diagram + transition rules for CX Orbit. This is a documentation/spec lock. It does not add a new engine.

Runtime already follows this machine:

Related: METRICS-AND-RISK.md §4, RISK-RULES-V1.md §5 and §9, DATA-MODEL.md §3–4, event dictionary SEC-02 in simiaroom-cx-v5.md.

#1. SEC-02 alignment

#2. Stages listed for funnel display

Two different uses of the same enum. Do not mix them.

#2.1 Linear spine (T3.2 conversion table)

Displayed in this order. Conversion is reached(N) / reached(N−1). These are not current-stage buckets.

identified has no previous stage; conversion is null (UI —).

Cohort size = clients whose first identified event falls in the required [from, to] window.

#2.2 Non-linear branches (T3.2 side counts, not denominators)

A client who paused after session 1 still keeps in_treatment first-reach. Branches are extra, not a replacement column.

There is no funnel branch returned_from_churn. Churn → return is a current_stage path only (§7). T3.2 must not grow a seventh conversion stage for it.

#2.3 Serving-only values (not funnel columns)

JOURNEY_STAGES = unknown, the six spine ids, paused, completed, churned.

#3. State diagram

Linear arrows are the happy-path spine. Dashed / labeled arrows are non-linear. Skip-forward on the spine is allowed by the engine when a later authoritative event arrives without the earlier one (illegal for producers — §8).

stateDiagram-v2
  [*] --> unknown

  unknown --> identified: authentication_succeeded / identity_link_created
  identified --> assessed: assessment_completed
  assessed --> matched: therapist_selected
  matched --> booked: booking_confirmed
  booked --> paid: payment_succeeded
  paid --> in_treatment: session_completed

  in_treatment --> paused: therapy_pause_declared
  paused --> in_treatment: therapy_resumed

  in_treatment --> completed: treatment_completed
  paused --> completed: treatment_completed

  in_treatment --> churned: therapy_stop_declared / churn_confirmed / churn_reason_submitted
  paused --> churned: therapy_stop_declared / churn_confirmed / churn_reason_submitted

  churned --> in_treatment: therapy_resumed

Rematch does not appear as a stage: therapist_selected with selection_context=replacement stays on the current stage (§7.2).

Pause expiry does not appear as a stage: current_stage stays paused until resume, stop, or completion. Risk/retention flip via pause_expired, not via a new stage id.

#4. Transitions driven by events (not clicks)

Replay events in UTC occurred_at order; tie-break source_event_id lexicographic (same as T2.9 / T3.2).

#4.1 Stage-changing events

Terminal for linear advance: completed and churned. Later spine events (session_completed, payment_succeeded, …) do not move those stages. Return from churn/completion uses therapy_resumed only.

Monotonic spine: a later spine event may skip forward (identified + payment_succeeded → paid). An earlier spine event never moves the client backward.

#4.2 Stage-neutral events (recompute may run; stage must not jump)

These may trigger SYS-01 profile recompute. They must not change current_stage:

Clicks and behavioral events (not in the table, default = no stage change): page_viewed, landing_page_viewed, login_clicked, assessment_started, assessment_question_answered, therapist_options_viewed, therapist_profile_viewed, booking_started, return_intent_detected, and any other GA/product click. SEC-02: a click is not a transition.

therapist_change_requested / therapist_change_reason_submitted are rematch intent, not a stage. Stage stays put until a later therapist_selected (usually still no stage change — §7.2).

#5. Pause and completion suppressions

Stage, funnel, retention, and risk all see the same events. They apply different suppressions. Do not reuse continuation_status=stopped as churn (T2.4 maps completion that way; T3.3 must use completion_flag).

#5.1 Declared pause — `therapy_pause_declared` (CON-04)

Active pause = current_pause_flag AND NOT pause_expired.

pause_expired (does not change stage):

When expired: T3.3 counts a dangerous-pause indicator (not churn). T3.4 lifts the cap and fires SIG-GAP-PAUSE-BREACH. current_stage remains paused until therapy_resumed, stop, or completion.

#5.2 Completion — `treatment_completed` (CHR-S04)

Completion is a successful operational outcome. It is not a clinical claim.

#5.3 True churn (for contrast)

therapy_stop_declared or churn_confirmed → current_stage = churned, completion_flag = false.

T3.3 churn-after-N requires a stop event, completion_flag = false, pause not active, and session_count = N. Gap and expired pause are not churn.

T3.4: SIG-STOP → high_risk, queue kind churned, not preventable at-risk.

#6. Flags vs stage (do not collapse)

#7. Return and rematch paths

#7.1 Return

Not return: authentication_succeeded, login_clicked, page_viewed, return_intent_detected, or a new booking/session while still churned/completed (linear advance is blocked). SEC-02: login after churn is not reactivation.

Same-therapist vs rematch-on-return is a property (selection_context=resume / replacement), not a new stage.

#7.2 Rematch

Rematch is a therapist-change overlay on the existing continuum. It is not a funnel stage and must not reset session_number (T2.4).

T3.4 SIG-THERAPIST-CHG may fire (attention, not high by itself). Completion still suppresses it.

#8. Illegal and ambiguous transitions

Producers must not emit these. The engine still has a deterministic last-event / monotonic rule so replay does not crash. Funnel conversion may look wrong if producers skip the spine.

#9. Product journey refs J-01…J-12 (not extra funnel columns)

T1.1 maps product reality onto J-01…J-12: JOURNEY-GAP-ANALYSIS.md. This machine collapses them for P0 display:

#10. Test Agent walkthroughs

Walk each scenario event by event against §3–§4. Expected current_stage is after that event. First-reach is the set of stages entered at least once (T3.2).

W1 and W2 reuse T3.2 fixture clients in fixtures/journey-funnel/p0-cohort.json (cohort window 2026-01-01 … 2026-06-30). W3 extends usr_churn with an explicit resume (not in that fixture).

#W1 — Happy path (`usr_full_a`)

First-reach: identified, assessed, matched, booked, paid, in_treatment.

Branches: none (not paused, not returned, not completed, not churned).

Suppressions: none. If session_count ≥ 1, T3.4 may score; T3.3 includes the client in reached(1).

Not in this path: page_viewed / therapist browse would not have moved the stage if inserted between 2 and 3.

#W2 — Pause then return (`usr_pause_ret`)

Same spine as W1 through session_completed (2026-03-01) → in_treatment, then:

First-reach: all six linear stages plus paused.

Branches: paused = yes, returned_from_pause = yes, completed = no, churned = no.

T3.2: client still counts in in_treatment (first-reach kept).

T3.3: while paused (and not expired), not churn. Gap signals suppressed.

T3.4: while active pause, gap signals suppressed; level capped; not on the high-risk tab. After resume, gap scoring resumes against cadence.

Expired-pause variant (not this fixture): if as_of passed expected_return_date with no resume, stage stays paused, T3.3 dangerous-pause indicator, T3.4 SIG-GAP-PAUSE-BREACH. Still not churn.

#W3 — Churn then return (synthetic on `usr_churn`)

Use usr_churn through churn_confirmed, then add resume. Login in between must not return.

First-reach: linear spine + churned. Resume does not add a T3.2 returned_from_pause branch (no pause event).

T3.3 (step 7 snapshot, as_of after confirm, before resume): churned with session_count = 1. Pause/completion do not apply.

T3.3 (step 8 snapshot): a stop event still exists at or before as_of, so the retention churn flag stays true (T3.3 has no resume override). That is intentional residual, not a stage-machine failure. Test Agent should still accept step 8 as a stage return.

T3.4: after step 7, SIG-STOP → churned queue, not preventable. After step 8, SIG-STOP does not fire (therapy_resumed is later than the stop); score as in-treatment.

#11. Out of scope (explicit)

• T1.1 product-vs-J-ref gap interviews (analysis doc: JOURNEY-GAP-ANALYSIS.md; named ops/PM interview still residual)
• New funnel columns, new JOURNEY_STAGES values, or engine refactors
• Crisis routing as a stage
• P1 behavioral funnel (assessment start, therapist view) as conversion stages — T3.2 residual stands
• Live Postgres serving (fixture-first, same as T3.2)

#12. Change log