The states system tracks entity lifecycle and status changes over time, enabling point-in-time analysis, state-based segmentation, and time-series queries.

Dimensions and Measurements

States come in two categories:

• Dimensions — categorical properties like lifecycle status (active, canceled, trialing). Stored as STRING values. These answer "what is the state of X?"

• Measurements — quantitative values like MRR, contract value, or hours logged. Stored as NUMERIC values. These answer "what is the value of X?"

Both are tracked in the same SCD2 table (nexus_entity_states), with precomputed _delta columns for measurements to enable efficient time-series queries.

Customer Lifecycle State

This project includes a person lifecycle dimension in customer_lifecycle_state with state_name = 'customer_lifecycle'.

Lifecycle values:

• lead = first contact-info trait event (email/phone/mobile_phone) for a never-enrolled person. Each lead row has a trigger_event_id.
• stale = 45+ days since last contact activity without enrollment (synthetic, rolling clock)
• enrolled = enrollment event fired
• paying = contract paid at effective_date for the initial contract when not cancelled on or before effective date
• renewed = contract renewed (TIMX renewal rows)
• churned = contract_cancelled or contract_expired

Leads and stale can cycle: lead → stale → lead → stale → ... until enrollment. A new lead starts whenever a contact-info trait arrives after a 45-day gap. See Trait-Derived States for the general pattern.

contract paid and contract renewed are generated in TIMX contract events so paid and renewal transitions stay event-driven.

Common State Patterns

Some state patterns are so common they appear in nearly every client project. These are documented as reusable templates with standardized naming:

• Marketing Relevance — classifies whether a person is a marketing target using identity resolution to separate prospects from existing users in website traffic. Uses state_name = 'marketing_relevance' with values target, not_target, and retarget.

Entity Support

States work for all entity types — both entity-resolution (ER) entities like persons and groups, and non-ER entities like subscriptions, contracts, and projects. Any entity that has a lifecycle or changing properties is a candidate for state tracking.