Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

44.8 KB
Raw Blame
//! The per-event read-modify-write — the Stage 1 "brain".
//!
//! [`plan_event`] decides what to read; [`fold_event`] folds one re-keyed event into each affected
//! leaf's RocksDB state, staging every write into a [`StagedBatch`](crate::store::StagedBatch) that
//! commits atomically through [`CohortStore::apply`](crate::store::CohortStore::apply). The sync
//! [`process_event`] composition (tests, blocking contexts) and the async
//! [`process_event_offloaded`] composition (production, over the
//! [`StoreHandle`](crate::store::StoreHandle) facade) share those two cores. Both return the
//! transitions that flipped, surfaced only after the commit succeeds.
//!
//! The behavioral side stages a per-leaf `cf_behavioral` row per matching condition; the person side
//! collapses all of a person's person-property leaf state into one durable [`PersonRecord`] in
//! `cf_person_records`, updated per the freshness decision table in [`crate::stage1::person_record`].

use std::collections::BTreeMap;

use metrics::{counter, histogram};
use uuid::Uuid;

use crate::consumers::events::CohortStreamEvent;
use crate::filters::reverse_index::{BehavioralCandidates, TeamFilters};
use crate::filters::TeamId;
use crate::hogvm::{
    build_behavioral_globals, build_person_property_globals, CohortEvaluator, GlobalsBuild,
};
use crate::observability::metrics::{
    STAGE1_BEHAVIORAL_APPLIES, STAGE1_CONDITIONS_EVALUATED, STAGE1_CONDITIONS_SKIPPED,
    STAGE1_GLOBALS_BUILDS, STAGE1_PERSON_RECORD_SIZE_BYTES, STAGE1_PERSON_RECORD_TOTAL,
    STAGE1_REPLAY_SKIPPED, STAGE1_SNAPSHOT_KEYS, STAGE1_STATE_DECODE_ERROR, STAGE1_STATE_WRITES,
    STAGE1_UNSUPPORTED_VARIANT_SKIPPED,
};
use crate::stage1::bucket_tz::{
    daily_bucket_len, day_idx_in_tz, now_day_for_window, window_start_for_now,
};
use crate::stage1::compressed_history;
use crate::stage1::daily::{daily_eviction_deadline, slide_window_forward};
use crate::stage1::key::LeafStateKey;
use crate::stage1::person_record::{
    apply_eval, apply_skip_eval, apply_stale, decide, CatalogFingerprint, Decision, DedupCoords,
    MatchedSet, PersonRecord, PriorRecord, PropsFingerprint, Stamp,
};
use crate::stage1::pick_state::EvictionWindow;
use crate::stage1::predicate::{compressed_predicate, daily_predicate, predicate};
use crate::stage1::state::{
    dedup_is_replay, dedup_record, AppliedOffsets, Stage1State, StateVariant, StatefulRecord,
};
use crate::stage1::time::clickhouse_timestamp_to_millis;
use crate::stage1::transition::{LeafTransition, TransitionKind};
use crate::stage2::{single_leaf_transition_register_writes, stage_register_writes};
use crate::store::{
    Behavioral, BehavioralKey, CohortStore, EventSnapshotRaw, PersonPrefix, PersonRecords,
    StagedBatch, StoreError, StoreHandle,
};

/// Whether to evaluate only the behavioral conditions matching the incoming event name. A behavioral
/// leaf's bytecode roots at `event == event_key`, so a name mismatch can never match: gating it out
/// drops no `BehavioralApply`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EventNameGating {
    /// Evaluate only the event's name bucket.
    Enabled,
    /// Evaluate every behavioral condition.
    Disabled,
}

impl EventNameGating {
    pub fn from_enabled(enabled: bool) -> Self {
        if enabled {
            Self::Enabled
        } else {
            Self::Disabled
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SkipReason {
    NullPersonId,
    /// Non-empty but not a valid UUID.
    UnparseablePersonId,
    NoTeamFilters,
    NoConditions,
    /// `person_properties` failed to parse. A malformed `properties` does not reach here; it drops
    /// the behavioral side and leaves the person side to run.
    GlobalsParseError,
    BadTimestamp,
}

impl SkipReason {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::NullPersonId => "null_person_id",
            Self::UnparseablePersonId => "unparseable_person_id",
            Self::NoTeamFilters => "no_team_filters",
            Self::NoConditions => "no_conditions",
            Self::GlobalsParseError => "globals_parse_error",
            Self::BadTimestamp => "bad_timestamp",
        }
    }
}

#[derive(Debug, Default, PartialEq, Eq)]
pub struct EventOutcome {
    pub transitions: Vec<LeafTransition>,
    pub schedules: Vec<(BehavioralKey, i64)>,
    /// This event's parsed timestamp (epoch ms). `0` on skip/no-applies paths.
    pub event_ms: i64,
    pub skipped: Option<SkipReason>,
}

impl EventOutcome {
    fn processed(
        transitions: Vec<LeafTransition>,
        schedules: Vec<(BehavioralKey, i64)>,
        event_ms: i64,
    ) -> Self {
        Self {
            transitions,
            schedules,
            event_ms,
            skipped: None,
        }
    }

    fn skipped(reason: SkipReason) -> Self {
        Self {
            transitions: Vec::new(),
            schedules: Vec::new(),
            event_ms: 0,
            skipped: Some(reason),
        }
    }
}

/// One behavioral leaf that matched this event: recorded only on a match, so a behavioral row is
/// staged for it.
struct BehavioralApply {
    lsk: LeafStateKey,
    condition_hash: [u8; 16],
}

/// How the person side of an event is handled, resolved once before the read.
enum PersonPlan {
    /// No person conditions, or empty `person_properties`: the record is neither read nor written.
    Inactive,
    /// A person condition exists and the payload is non-empty. The record is read and the freshness
    /// decision table runs; `props_fp`/`catalog_fp` are the fingerprints the table compares against
    /// the stored record.
    Active {
        props_fp: PropsFingerprint,
        catalog_fp: CatalogFingerprint,
    },
}

impl PersonPlan {
    fn is_active(&self) -> bool {
        matches!(self, Self::Active { .. })
    }
}

struct PendingWrite {
    key: BehavioralKey,
    bytes: Vec<u8>,
    variant: StateVariant,
}

/// What [`plan_event`] resolved for one event, up to (but not including) the pre-event read.
pub(crate) enum EventPlan {
    /// The event was skipped before any leaf evaluated (`skipped` reason).
    Skip(SkipReason),
    /// Nothing to read or write: no behavioral leaf matched and the person side is inactive.
    NoApplies,
    /// Work to do; read the snapshot and hand the result to [`fold_event`].
    Read(ReadPlan),
}

/// The data [`fold_event`] needs from [`plan_event`], carried by [`EventPlan::Read`]. The behavioral
/// keys are derived from `prefix` in `behavioral` order so the fold's zip over the read result stays
/// aligned; the record key is the person prefix (read iff the person side is active).
pub(crate) struct ReadPlan {
    prefix: PersonPrefix,
    behavioral: Vec<BehavioralApply>,
    person: PersonPlan,
    event_ms: i64,
    origin: Option<Uuid>,
}

impl ReadPlan {
    /// The behavioral keys to read, in `behavioral` order.
    fn behavioral_keys(&self) -> Vec<BehavioralKey> {
        self.behavioral
            .iter()
            .map(|apply| self.prefix.behavioral_key(apply.lsk))
            .collect()
    }
}

/// The metric emissions a successful fold implies, captured so the compositions can defer them until
/// after the commit succeeds. A fold that stages nothing yields empty stats.
pub(crate) struct WriteStats {
    /// Per-`StateVariant` `STAGE1_STATE_WRITES` counts, in first-seen order.
    variant_writes: Vec<(StateVariant, u64)>,
    /// Encoded person-record size to record on [`STAGE1_PERSON_RECORD_SIZE_BYTES`], when a record was
    /// staged.
    record_size: Option<usize>,
    /// The person side's decision outcome for [`STAGE1_PERSON_RECORD_TOTAL`], `None` when the person
    /// side was inactive. Deferred with the write metrics so a failed commit's redelivery cannot
    /// double-count; a write-free outcome (replay) still counts, since emission is gated on the commit
    /// step passing, not on there being writes.
    person_record_result: Option<&'static str>,
}

impl WriteStats {
    /// Emit the deferred write metrics. Called by the compositions only after the commit step
    /// succeeded (an event that staged nothing has no commit to fail), so a failed write records no
    /// phantom counts.
    pub(crate) fn emit(&self) {
        for &(variant, count) in &self.variant_writes {
            counter!(STAGE1_STATE_WRITES, "variant" => variant.as_str()).increment(count);
        }
        if let Some(size) = self.record_size {
            histogram!(STAGE1_PERSON_RECORD_SIZE_BYTES).record(size as f64);
        }
        if let Some(result) = self.person_record_result {
            counter!(STAGE1_PERSON_RECORD_TOTAL, "result" => result).increment(1);
        }
    }
}

/// The pure result of [`fold_event`]: either a whole-event skip (a person-props parse failure on the
/// evaluation arm) or the staged writes plus what the caller surfaces after commit. Infallible
/// w.r.t. the store — the fold touches no store.
pub(crate) enum FoldResult {
    Skip(SkipReason),
    Folded(FoldOutput),
}

/// The staged writes plus what the caller surfaces after commit.
pub(crate) struct FoldOutput {
    pub staged: StagedBatch,
    pub transitions: Vec<LeafTransition>,
    pub schedules: Vec<(BehavioralKey, i64)>,
    pub write_stats: WriteStats,
}

/// One behavioral apply's stored state as read by the event's single batched pre-event read.
enum PriorState {
    /// No row: this apply is the leaf's first write.
    Absent,
    /// The decoded pre-event record.
    Present(StatefulRecord),
    /// A row exists but does not decode; the apply is skipped.
    Corrupt,
}

impl PriorState {
    /// Decode one behavioral snapshot slot. The decode error is counted here — the only place a
    /// `Corrupt` can be born.
    fn decode(bytes: Option<Vec<u8>>) -> Self {
        match bytes {
            None => Self::Absent,
            Some(bytes) => match StatefulRecord::decode(&bytes) {
                Ok(record) => Self::Present(record),
                Err(_) => {
                    counter!(STAGE1_STATE_DECODE_ERROR).increment(1);
                    Self::Corrupt
                }
            },
        }
    }
}

/// Fold one event with event-name gating disabled (full behavioral sweep). The gating-aware entry is
/// [`process_event_gated`].
pub fn process_event(
    partition_id: u16,
    store: &CohortStore,
    filters: &TeamFilters,
    event: &CohortStreamEvent,
) -> Result<EventOutcome, StoreError> {
    process_event_gated(
        partition_id,
        store,
        filters,
        event,
        EventNameGating::Disabled,
    )
}

/// Fold one event through the synchronous store, with explicit event-name gating. The public test
/// surface; the production async composition is [`process_event_offloaded`].
// The sync composition runs in blocking contexts, so its direct `read_event_snapshot` + `apply` are
// sanctioned; production folds through `process_event_offloaded`, which the crate-wide lint keeps
// free of raw `CohortStore` calls.
#[allow(clippy::disallowed_methods)]
pub fn process_event_gated(
    partition_id: u16,
    store: &CohortStore,
    filters: &TeamFilters,
    event: &CohortStreamEvent,
    event_name_gating: EventNameGating,
) -> Result<EventOutcome, StoreError> {
    let read = match plan_event(partition_id, filters, event, event_name_gating) {
        EventPlan::Skip(reason) => return Ok(EventOutcome::skipped(reason)),
        EventPlan::NoApplies => return Ok(EventOutcome::processed(Vec::new(), Vec::new(), 0)),
        EventPlan::Read(read) => read,
    };

    let event_ms = read.event_ms;
    let behavioral_keys = read.behavioral_keys();
    let record_key = read.person.is_active().then(|| read.prefix.record_key());
    let snapshot = store.read_event_snapshot(&behavioral_keys, record_key.as_ref())?;
    record_snapshot_keys(&snapshot);

    let (staged, transitions, schedules, write_stats) =
        match fold_event(filters, read, snapshot, event) {
            FoldResult::Skip(reason) => return Ok(EventOutcome::skipped(reason)),
            FoldResult::Folded(FoldOutput {
                staged,
                transitions,
                schedules,
                write_stats,
            }) => (staged, transitions, schedules, write_stats),
        };

    // The batch spans exactly one event: the next event in the sub-batch must see this event's
    // committed writes (argMax tiebreaker, replay dedup, the person record's stamp/matched set).
    // Metrics emit only once the commit step passed.
    if !staged.is_empty() {
        store.apply(&staged)?;
    }
    write_stats.emit();

    Ok(EventOutcome::processed(transitions, schedules, event_ms))
}

/// The production composition of [`plan_event`] + [`fold_event`], reading and writing through the
/// async [`StoreHandle`] facade so the store I/O runs on the blocking pool.
///
/// Sequential awaits only: the batched read must observe the prior event's committed writes, so the
/// read and commit are never joined or reordered.
#[hotpath::measure]
pub(crate) async fn process_event_offloaded(
    partition_id: u16,
    handle: &StoreHandle,
    filters: &TeamFilters,
    event: &CohortStreamEvent,
    event_name_gating: EventNameGating,
) -> Result<EventOutcome, StoreError> {
    let read = match plan_event(partition_id, filters, event, event_name_gating) {
        EventPlan::Skip(reason) => return Ok(EventOutcome::skipped(reason)),
        EventPlan::NoApplies => return Ok(EventOutcome::processed(Vec::new(), Vec::new(), 0)),
        EventPlan::Read(read) => read,
    };

    let event_ms = read.event_ms;
    let behavioral_keys = read.behavioral_keys();
    let record_key = read.person.is_active().then(|| read.prefix.record_key());
    let snapshot = handle
        .read_event_snapshot(behavioral_keys, record_key)
        .await?;
    record_snapshot_keys(&snapshot);

    let (staged, transitions, schedules, write_stats) =
        match fold_event(filters, read, snapshot, event) {
            FoldResult::Skip(reason) => return Ok(EventOutcome::skipped(reason)),
            FoldResult::Folded(FoldOutput {
                staged,
                transitions,
                schedules,
                write_stats,
            }) => (staged, transitions, schedules, write_stats),
        };

    // Commit before the caller processes the next event; metrics emit only once the commit step passed.
    if !staged.is_empty() {
        handle.commit(staged).await?;
    }
    write_stats.emit();

    Ok(EventOutcome::processed(transitions, schedules, event_ms))
}

/// Record the snapshot's total key count (behavioral rows + the 0-or-1 record slot) on
/// [`STAGE1_SNAPSHOT_KEYS`].
fn record_snapshot_keys(snapshot: &EventSnapshotRaw) {
    let keys = snapshot.behavioral.len() + usize::from(snapshot.record.is_some());
    histogram!(STAGE1_SNAPSHOT_KEYS).record(keys as f64);
}

/// Resolve everything up to the pre-event read: gating, behavioral evaluation and applies, and the
/// person plan (fingerprints only — the person record read and evaluation happen in the fold).
#[hotpath::measure]
pub(crate) fn plan_event(
    partition_id: u16,
    filters: &TeamFilters,
    event: &CohortStreamEvent,
    event_name_gating: EventNameGating,
) -> EventPlan {
    if event.person_id.is_empty() {
        return EventPlan::Skip(SkipReason::NullPersonId);
    }
    let Ok(person_id) = Uuid::parse_str(&event.person_id) else {
        return EventPlan::Skip(SkipReason::UnparseablePersonId);
    };

    let origin: Option<Uuid> = event
        .redirected_from
        .as_deref()
        .and_then(|raw| Uuid::parse_str(raw).ok());

    let has_behavioral = !filters.behavioral.conditions.is_empty();
    let has_person = !filters.person_property_conditions.is_empty();
    if !has_behavioral && !has_person {
        return EventPlan::Skip(SkipReason::NoConditions);
    }

    let mut behavioral: Vec<BehavioralApply> = Vec::new();
    collect_behavioral_applies(filters, event, event_name_gating, &mut behavioral);

    // Fingerprints are computed here; the record read and evaluation happen in the fold.
    let person = match active_person_props(filters, event) {
        Some(raw) => PersonPlan::Active {
            props_fp: PropsFingerprint::of(raw),
            catalog_fp: filters.catalog_fingerprint,
        },
        None => PersonPlan::Inactive,
    };

    if behavioral.is_empty() && !person.is_active() {
        return EventPlan::NoApplies;
    }

    let Some(event_ms) = clickhouse_timestamp_to_millis(&event.timestamp) else {
        return EventPlan::Skip(SkipReason::BadTimestamp);
    };

    let prefix = PersonPrefix::new(partition_id, event.team_id as u64, person_id);
    EventPlan::Read(ReadPlan {
        prefix,
        behavioral,
        person,
        event_ms,
        origin,
    })
}

/// Fold the pre-event `snapshot` into the behavioral rows and the person record, staging the writes
/// into a [`StagedBatch`] for the caller to commit. Pure w.r.t. the store. Returns
/// [`FoldResult::Skip`] on a person-props parse failure.
#[hotpath::measure]
pub(crate) fn fold_event(
    filters: &TeamFilters,
    read: ReadPlan,
    snapshot: EventSnapshotRaw,
    event: &CohortStreamEvent,
) -> FoldResult {
    let ReadPlan {
        prefix,
        behavioral,
        person,
        event_ms,
        origin,
    } = read;
    let person_id = prefix.person_id;
    let origin_ref = origin.as_ref();
    let EventSnapshotRaw {
        behavioral: behavioral_values,
        record: record_slot,
    } = snapshot;

    // Person side first: an evaluation-arm parse failure skips the whole event, so nothing (behavioral
    // included) may be staged before the person decision succeeds.
    let (record_put, mut transitions, record_result) = match fold_person(
        filters,
        &prefix,
        &person,
        record_slot,
        event,
        event_ms,
        origin_ref,
    ) {
        PersonFoldResult::Skip(reason) => return FoldResult::Skip(reason),
        PersonFoldResult::Folded {
            record_put,
            transitions,
            record_result,
        } => (record_put, transitions, record_result),
    };

    let behavioral_keys: Vec<BehavioralKey> = behavioral
        .iter()
        .map(|apply| prefix.behavioral_key(apply.lsk))
        .collect();
    histogram!(STAGE1_BEHAVIORAL_APPLIES).record(behavioral.len() as f64);

    let mut schedules: Vec<(BehavioralKey, i64)> = Vec::new();
    let mut pending: Vec<PendingWrite> = Vec::new();
    fold_behavioral(
        filters,
        &behavioral,
        &behavioral_keys,
        behavioral_values,
        person_id,
        origin_ref,
        event,
        event_ms,
        &mut transitions,
        &mut schedules,
        &mut pending,
    );

    let mut staged = StagedBatch::default();
    let mut write_stats = WriteStats {
        variant_writes: Vec::new(),
        record_size: None,
        person_record_result: record_result,
    };
    for write in &pending {
        staged.put::<Behavioral>(&write.key, &write.bytes);
        record_variant_write(&mut write_stats.variant_writes, write.variant);
    }
    if let Some(bytes) = record_put {
        write_stats.record_size = Some(bytes.len());
        staged.put::<PersonRecords>(&prefix.record_key(), &bytes);
    }
    for transition in &transitions {
        stage_register_writes(
            &mut staged,
            single_leaf_transition_register_writes(
                filters,
                prefix.partition_id,
                transition,
                event_ms,
            ),
        );
    }

    FoldResult::Folded(FoldOutput {
        staged,
        transitions,
        schedules,
        write_stats,
    })
}

/// Fold each behavioral apply via the `mutate_behavioral*` variants: a match stages an advanced
/// `cf_behavioral` row, may schedule a sweep deadline, and may emit a transition.
#[allow(clippy::too_many_arguments)]
fn fold_behavioral(
    filters: &TeamFilters,
    behavioral: &[BehavioralApply],
    behavioral_keys: &[BehavioralKey],
    behavioral_values: Vec<Option<Vec<u8>>>,
    person_id: Uuid,
    origin: Option<&Uuid>,
    event: &CohortStreamEvent,
    event_ms: i64,
    transitions: &mut Vec<LeafTransition>,
    schedules: &mut Vec<(BehavioralKey, i64)>,
    pending: &mut Vec<PendingWrite>,
) {
    // Alignment-safe zip: the snapshot preserves the request order, `None` for absent keys.
    for ((apply, &key), bytes) in behavioral
        .iter()
        .zip(behavioral_keys)
        .zip(behavioral_values)
    {
        let prev = match PriorState::decode(bytes) {
            PriorState::Absent => None,
            PriorState::Present(record) => Some(record),
            PriorState::Corrupt => continue,
        };

        let mutation = match filters.by_lsk.get(&apply.lsk).map(|meta| meta.variant) {
            Some(StateVariant::BehavioralDailyBuckets) => mutate_behavioral_daily(
                filters,
                apply.lsk,
                apply.condition_hash,
                person_id,
                origin,
                event,
                event_ms,
                prev,
            ),
            Some(StateVariant::BehavioralCompressedHistory) => mutate_behavioral_compressed(
                filters,
                apply.lsk,
                apply.condition_hash,
                person_id,
                origin,
                event,
                event_ms,
                prev,
            ),
            _ => mutate_behavioral(
                filters,
                apply.lsk,
                apply.condition_hash,
                person_id,
                origin,
                event,
                event_ms,
                prev,
            ),
        };

        let Some((record, transition)) = mutation else {
            continue;
        };

        if let Some(transition) = transition {
            transitions.push(transition);
        }
        if let Some(deadline) = schedule_deadline(&record.state) {
            schedules.push((key, deadline));
        }
        pending.push(PendingWrite {
            variant: record.state.variant(),
            bytes: record.encode(),
            key,
        });
    }
}

/// The result of the person side of a fold: either a whole-event skip (an evaluation-arm parse
/// failure) or the record put to stage (if any) plus the person transitions.
enum PersonFoldResult {
    Skip(SkipReason),
    Folded {
        record_put: Option<Vec<u8>>,
        transitions: Vec<LeafTransition>,
        /// The decision outcome for [`STAGE1_PERSON_RECORD_TOTAL`]; `None` when the person side was
        /// inactive. Deferred to post-commit via [`WriteStats`] so a failed commit's redelivery
        /// cannot double-count.
        record_result: Option<&'static str>,
    },
}

/// Run the freshness decision table for the person side against the stored record.
///
/// `Inactive` touches nothing. Otherwise the prior record is decoded (its classification — present,
/// absent, corrupt — feeds the metric), [`decide`] classifies the event, and:
///
/// - `Replay`: nothing staged, no transitions.
/// - `Stale`: the record advances its dedup + `last_seen` only; no HogVM, no transitions.
/// - `SkipEval`: the record adopts the event stamp; no HogVM, no transitions.
/// - `Eval`: parse the person globals (a failure skips the whole event), evaluate the effective
///   person conditions, and diff the resulting TRUE set against the record's matched set.
#[allow(clippy::too_many_arguments)]
fn fold_person(
    filters: &TeamFilters,
    prefix: &PersonPrefix,
    person: &PersonPlan,
    record_slot: Option<Option<Vec<u8>>>,
    event: &CohortStreamEvent,
    event_ms: i64,
    origin: Option<&Uuid>,
) -> PersonFoldResult {
    let PersonPlan::Active {
        props_fp,
        catalog_fp,
    } = person
    else {
        return PersonFoldResult::Folded {
            record_put: None,
            transitions: Vec::new(),
            record_result: None,
        };
    };

    // The record slot is always requested for an active person, so the outer `Option` is `Some`.
    let record_bytes = record_slot.flatten();
    let prior = PriorRecord::decode(record_bytes.as_deref());
    let baseline = PersonRecord::absent();
    let event_stamp = Stamp::new(event_ms, event.source_offset);
    let dedup = DedupCoords::new(origin.copied(), event.source_partition, event.source_offset);

    // Absent/corrupt priors fold from an absent baseline; a present prior folds from itself.
    let from = match &prior {
        PriorRecord::Present(record) => record,
        PriorRecord::Absent | PriorRecord::Corrupt => &baseline,
    };

    match decide(&prior, event_stamp, dedup, *props_fp, *catalog_fp) {
        Decision::Replay => PersonFoldResult::Folded {
            record_put: None,
            transitions: Vec::new(),
            record_result: Some("replay"),
        },
        Decision::Stale => {
            let record = apply_stale(from, event_stamp, dedup);
            PersonFoldResult::Folded {
                record_put: Some(record.encode()),
                transitions: Vec::new(),
                record_result: Some("argmax_stale"),
            }
        }
        Decision::SkipEval => {
            let record = apply_skip_eval(from, event_stamp, dedup);
            PersonFoldResult::Folded {
                record_put: Some(record.encode()),
                transitions: Vec::new(),
                record_result: Some("fresh"),
            }
        }
        Decision::Eval { freshness } => {
            // A globals parse failure skips the whole event. The effective condition subset and the
            // catalog slice passed to `diff`/`apply_eval` are the same filtered set, so a
            // defensively-skipped hash in the stored set never emits a spurious `Left`.
            let globals = match build_person_property_globals(event) {
                Ok(globals) => globals,
                Err(_) => return PersonFoldResult::Skip(SkipReason::GlobalsParseError),
            };
            let mut evaluator = CohortEvaluator::new();
            evaluator.set_globals(globals);
            let (true_set, effective_catalog) = eval_person_conditions(filters, &mut evaluator);

            let (record, raw_transitions) = apply_eval(
                true_set,
                &effective_catalog,
                from,
                event_stamp,
                dedup,
                *props_fp,
                *catalog_fp,
            );
            // absent/corrupt are labelled from the prior classification (an eval from nothing), not
            // from the freshness axis (which reports StaleBoth for both).
            let record_result = match &prior {
                PriorRecord::Absent => "absent",
                PriorRecord::Corrupt => "corrupt",
                PriorRecord::Present(_) => freshness.as_str(),
            };

            let transitions = raw_transitions
                .into_iter()
                .map(|(hash, kind)| LeafTransition {
                    team_id: TeamId(event.team_id),
                    leaf_state_key: LeafStateKey::for_person_property(&hash),
                    person_id: prefix.person_id,
                    condition_hash: hash,
                    kind,
                })
                .collect();
            PersonFoldResult::Folded {
                record_put: Some(record.encode()),
                transitions,
                record_result: Some(record_result),
            }
        }
    }
}

/// Accumulate one write into its variant's running count, preserving first-seen order for the
/// deferred emission.
fn record_variant_write(counts: &mut Vec<(StateVariant, u64)>, variant: StateVariant) {
    if let Some((_, count)) = counts.iter_mut().find(|(v, _)| *v == variant) {
        *count += 1;
    } else {
        counts.push((variant, 1));
    }
}

/// Returns `None` for permanent-membership states (`i64::MAX` sentinel), so only time-bounded
/// leaves get scheduled for sweep eviction.
pub(crate) fn schedule_deadline(state: &Stage1State) -> Option<i64> {
    state.eviction_deadline().filter(|&d| d != i64::MAX)
}

/// The raw `person_properties` iff there is a person condition and the payload is non-empty.
fn active_person_props<'a>(filters: &TeamFilters, event: &'a CohortStreamEvent) -> Option<&'a str> {
    if filters.person_property_conditions.is_empty() {
        return None;
    }
    event
        .person_properties
        .as_deref()
        .filter(|raw| !raw.is_empty())
}

/// Evaluate this event's behavioral conditions, pushing a [`BehavioralApply`] per matching leaf.
///
/// The candidates resolve before the globals are built, so an event no condition roots at pays for
/// neither JSON parse. A malformed payload drops the behavioral side and leaves the person side to
/// run: skipping the whole event here would make the gating flag a correctness switch, because an
/// event outside every bucket is never parsed and so never skipped, while the sweep parses it,
/// fails, and skips.
fn collect_behavioral_applies(
    filters: &TeamFilters,
    event: &CohortStreamEvent,
    gating: EventNameGating,
    applies: &mut Vec<BehavioralApply>,
) {
    let Some(candidates) = behavioral_candidates(filters, &event.event, gating) else {
        counter!(STAGE1_GLOBALS_BUILDS, "result" => "no_candidates").increment(1);
        return;
    };
    // The whole team's plan decides which payloads are parsed, so the two gating arms agree on
    // whether this event's payloads are malformed even though they materialize different roots.
    let build = GlobalsBuild::narrowed(candidates.plan, filters.behavioral.plan);
    let Ok(globals) = build_behavioral_globals(event, build) else {
        counter!(STAGE1_GLOBALS_BUILDS, "result" => "parse_error").increment(1);
        return;
    };
    counter!(STAGE1_GLOBALS_BUILDS, "result" => "built").increment(1);
    let mut evaluator = CohortEvaluator::new();
    evaluator.set_globals(globals);
    for &hash in &candidates.conditions {
        eval_behavioral_condition(filters, hash, &mut evaluator, applies);
    }
}

/// What one event can match under `gating`, or `None` when nothing can — the case that skips both
/// JSON parses. The `event_name_gate` count is emitted either way, so a gated-out condition still
/// counts on an unparsed event.
fn behavioral_candidates<'a>(
    filters: &'a TeamFilters,
    event_name: &str,
    gating: EventNameGating,
) -> Option<&'a BehavioralCandidates> {
    match gating {
        EventNameGating::Disabled => {
            (!filters.behavioral.conditions.is_empty()).then_some(&filters.behavioral)
        }
        EventNameGating::Enabled => {
            let bucket = filters.behavioral_by_event_name.get(event_name);
            let gated_out = filters
                .behavioral
                .conditions
                .len()
                .saturating_sub(bucket.map_or(0, |bucket| bucket.conditions.len()));
            if gated_out > 0 {
                counter!(STAGE1_CONDITIONS_SKIPPED, "reason" => "event_name_gate")
                    .increment(gated_out as u64);
            }
            bucket
        }
    }
}

/// Evaluate one behavioral condition, pushing a [`BehavioralApply`] for each supported state-keyed
/// leaf on a match.
fn eval_behavioral_condition(
    filters: &TeamFilters,
    hash: [u8; 16],
    evaluator: &mut CohortEvaluator,
    applies: &mut Vec<BehavioralApply>,
) {
    let Some(program) = filters.by_condition_to_program.get(&hash) else {
        return;
    };
    counter!(STAGE1_CONDITIONS_EVALUATED, "kind" => "behavioral").increment(1);
    if !evaluator.evaluate(program) {
        return;
    }
    let Some(lsks) = filters.by_condition_to_lsk.get(&hash) else {
        return;
    };
    for &lsk in lsks {
        match filters.by_lsk.get(&lsk).map(|meta| meta.variant) {
            Some(
                StateVariant::BehavioralSingle
                | StateVariant::BehavioralDailyBuckets
                | StateVariant::BehavioralCompressedHistory,
            ) => {
                applies.push(BehavioralApply {
                    lsk,
                    condition_hash: hash,
                });
            }
            Some(other) => {
                counter!(STAGE1_UNSUPPORTED_VARIANT_SKIPPED, "variant" => other.as_str())
                    .increment(1);
            }
            None => {}
        }
    }
}

/// Evaluate the person conditions in stable order, returning the TRUE set and the effective catalog
/// slice — the subset of `person_conditions_ordered` that has bytecode and a `PersonProperty`-variant
/// LSK meta. Both are the same filtered subset, so passing the effective catalog to
/// [`apply_eval`]/[`MatchedSet::diff`] means a defensively-skipped hash in the stored set is never
/// diffed and never emits a spurious `Left`.
fn eval_person_conditions(
    filters: &TeamFilters,
    evaluator: &mut CohortEvaluator,
) -> (MatchedSet, Vec<[u8; 16]>) {
    let mut true_hashes: Vec<[u8; 16]> = Vec::new();
    let mut effective_catalog: Vec<[u8; 16]> = Vec::new();
    for &hash in &filters.person_conditions_ordered {
        let Some(program) = filters.by_condition_to_program.get(&hash) else {
            continue;
        };
        // A hash whose LSK meta is missing or not a `PersonProperty` variant is skipped, so it is not
        // part of the effective catalog.
        let lsk = LeafStateKey::for_person_property(&hash);
        match filters.by_lsk.get(&lsk).map(|meta| meta.variant) {
            Some(StateVariant::PersonProperty) => {}
            Some(other) => {
                counter!(STAGE1_UNSUPPORTED_VARIANT_SKIPPED, "variant" => other.as_str())
                    .increment(1);
                continue;
            }
            None => continue,
        }
        counter!(STAGE1_CONDITIONS_EVALUATED, "kind" => "person_property").increment(1);
        // `person_conditions_ordered` is sorted, so pushing in iteration order keeps the effective
        // catalog sorted for the binary searches in `diff`/`apply_eval`.
        effective_catalog.push(hash);
        if evaluator.evaluate(program) {
            true_hashes.push(hash);
        }
    }
    (MatchedSet::from_iter(true_hashes), effective_catalog)
}

/// Fold a behavioral match into a single-bit leaf. Never emits `Left` (match is never cleared).
#[allow(clippy::too_many_arguments)]
fn mutate_behavioral(
    filters: &TeamFilters,
    lsk: LeafStateKey,
    condition_hash: [u8; 16],
    person_id: Uuid,
    origin: Option<&Uuid>,
    event: &CohortStreamEvent,
    event_ms: i64,
    prev: Option<StatefulRecord>,
) -> Option<(StatefulRecord, Option<LeafTransition>)> {
    let (prev_last_event, predicate_before, mut applied, mut redirect_dedup) = match prev {
        None => (i64::MIN, false, AppliedOffsets::default(), BTreeMap::new()),
        Some(record) => {
            let predicate_before = predicate(&record.state);
            match record.state {
                Stage1State::BehavioralSingle {
                    last_event_at_ms, ..
                } => (
                    last_event_at_ms,
                    predicate_before,
                    record.applied_offsets,
                    record.redirect_dedup,
                ),
                _ => {
                    counter!(STAGE1_STATE_DECODE_ERROR).increment(1);
                    return None;
                }
            }
        }
    };

    let window = filters.by_lsk.get(&lsk).and_then(|meta| meta.window);

    // Explicit range: day-granularity, inclusive, matching `date >= toDate(from) AND date <= toDate(to)`.
    // The bound is a tz-naive calendar day, compared directly to `day_idx_in_tz(event_ms, tz)` —
    // never re-projected through a timezone (which would shift it one day for UTC-offset teams).
    // Out-of-range events are dropped completely: no dedup record, no state, no transition.
    if let Some(EvictionWindow::Explicit { from_day, to_day }) = window {
        let event_day = day_idx_in_tz(event_ms, filters.timezone);
        let before_from = from_day.is_some_and(|f| event_day < f);
        let after_to = to_day.is_some_and(|t| event_day > t);
        if before_from || after_to {
            return None;
        }
    }

    if dedup_is_replay(
        &applied,
        &redirect_dedup,
        origin,
        event.source_partition,
        event.source_offset,
    ) {
        counter!(STAGE1_REPLAY_SKIPPED, "variant" => StateVariant::BehavioralSingle.as_str())
            .increment(1);
        return None;
    }
    dedup_record(
        &mut applied,
        &mut redirect_dedup,
        origin,
        event.source_partition,
        event.source_offset,
    );

    let last_event_at_ms = prev_last_event.max(event_ms);
    let earliest_eviction_at_ms = window.map_or(i64::MAX, |w| {
        w.earliest_eviction_at_ms(last_event_at_ms, filters.timezone)
    });

    let record = StatefulRecord {
        state: Stage1State::BehavioralSingle {
            has_match: true,
            last_event_at_ms,
            earliest_eviction_at_ms,
        },
        applied_offsets: applied,
        redirect_dedup,
    };
    let transition = if predicate_before {
        None
    } else {
        Some(LeafTransition {
            team_id: TeamId(event.team_id),
            leaf_state_key: lsk,
            person_id,
            condition_hash,
            kind: TransitionKind::Entered,
        })
    };
    Some((record, transition))
}

/// Fold a `performed_event_multiple` match into a dense daily-bucket state. A window slide can
/// drop the count below threshold and emit `Left`.
#[allow(clippy::too_many_arguments)]
fn mutate_behavioral_daily(
    filters: &TeamFilters,
    lsk: LeafStateKey,
    condition_hash: [u8; 16],
    person_id: Uuid,
    origin: Option<&Uuid>,
    event: &CohortStreamEvent,
    event_ms: i64,
    prev: Option<StatefulRecord>,
) -> Option<(StatefulRecord, Option<LeafTransition>)> {
    let (Some(window_days), Some(op)) = filters
        .by_lsk
        .get(&lsk)
        .map_or((None, None), |meta| (meta.window_days, meta.predicate_op))
    else {
        counter!(STAGE1_UNSUPPORTED_VARIANT_SKIPPED, "variant" => StateVariant::BehavioralDailyBuckets.as_str())
            .increment(1);
        return None;
    };
    let tz = filters.timezone;
    let len = daily_bucket_len(window_days);

    let (prior_buckets, prior_window_start_day, prev_last_event, mut applied, mut redirect_dedup) =
        match prev {
            None => (
                None,
                0_i32,
                i64::MIN,
                AppliedOffsets::default(),
                BTreeMap::new(),
            ),
            Some(record) => match record.state {
                Stage1State::BehavioralDailyBuckets {
                    buckets,
                    window_start_day,
                    last_event_at_ms,
                    ..
                } => (
                    Some(buckets),
                    window_start_day,
                    last_event_at_ms,
                    record.applied_offsets,
                    record.redirect_dedup,
                ),
                _ => {
                    counter!(STAGE1_STATE_DECODE_ERROR).increment(1);
                    return None;
                }
            },
        };

    if dedup_is_replay(
        &applied,
        &redirect_dedup,
        origin,
        event.source_partition,
        event.source_offset,
    ) {
        counter!(STAGE1_REPLAY_SKIPPED, "variant" => StateVariant::BehavioralDailyBuckets.as_str())
            .increment(1);
        return None;
    }
    dedup_record(
        &mut applied,
        &mut redirect_dedup,
        origin,
        event.source_partition,
        event.source_offset,
    );

    let mut buckets = match prior_buckets {
        Some(buckets) if buckets.len() == len => buckets,
        Some(_) => {
            counter!(STAGE1_STATE_DECODE_ERROR).increment(1);
            return None;
        }
        None => Vec::new(),
    };

    let predicate_before = daily_predicate(&buckets, op);

    let event_day = day_idx_in_tz(event_ms, tz);
    let mut window_start_day = if buckets.is_empty() {
        buckets = vec![0; len];
        window_start_for_now(event_day, window_days)
    } else {
        prior_window_start_day
    };

    let cur_now_day = now_day_for_window(window_start_day, window_days);
    if event_day > cur_now_day {
        slide_window_forward(&mut buckets, &mut window_start_day, window_days, event_day);
        let last = len - 1;
        buckets[last] = buckets[last].saturating_add(1);
    } else if event_day < window_start_day {
    } else {
        let idx = (event_day - window_start_day) as usize;
        buckets[idx] = buckets[idx].saturating_add(1);
    }

    let last_event_at_ms = prev_last_event.max(event_ms);
    let earliest_eviction_at_ms =
        daily_eviction_deadline(&buckets, window_start_day, window_days, tz);
    let predicate_after = daily_predicate(&buckets, op);

    let record = StatefulRecord {
        state: Stage1State::BehavioralDailyBuckets {
            buckets,
            window_start_day,
            last_event_at_ms,
            earliest_eviction_at_ms,
        },
        applied_offsets: applied,
        redirect_dedup,
    };
    let kind = match (predicate_before, predicate_after) {
        (false, true) => Some(TransitionKind::Entered),
        (true, false) => Some(TransitionKind::Left),
        _ => None,
    };
    let transition = kind.map(|kind| LeafTransition {
        team_id: TeamId(event.team_id),
        leaf_state_key: lsk,
        person_id,
        condition_hash,
        kind,
    });
    Some((record, transition))
}

/// Fold a `performed_event_multiple` match into sparse compressed-history state (>180-day windows).
#[allow(clippy::too_many_arguments)]
fn mutate_behavioral_compressed(
    filters: &TeamFilters,
    lsk: LeafStateKey,
    condition_hash: [u8; 16],
    person_id: Uuid,
    origin: Option<&Uuid>,
    event: &CohortStreamEvent,
    event_ms: i64,
    prev: Option<StatefulRecord>,
) -> Option<(StatefulRecord, Option<LeafTransition>)> {
    let (Some(window_days), Some(op)) = filters
        .by_lsk
        .get(&lsk)
        .map_or((None, None), |meta| (meta.window_days, meta.predicate_op))
    else {
        counter!(STAGE1_UNSUPPORTED_VARIANT_SKIPPED, "variant" => StateVariant::BehavioralCompressedHistory.as_str())
            .increment(1);
        return None;
    };
    let tz = filters.timezone;

    let (prior_entries, prior_window_start_day, prev_last_event, mut applied, mut redirect_dedup) =
        match prev {
            None => (
                None,
                0_i32,
                i64::MIN,
                AppliedOffsets::default(),
                BTreeMap::new(),
            ),
            Some(record) => match record.state {
                Stage1State::BehavioralCompressedHistory {
                    entries,
                    window_start_day,
                    last_event_at_ms,
                    ..
                } => (
                    Some(entries),
                    window_start_day,
                    last_event_at_ms,
                    record.applied_offsets,
                    record.redirect_dedup,
                ),
                _ => {
                    counter!(STAGE1_STATE_DECODE_ERROR).increment(1);
                    return None;
                }
            },
        };

    if dedup_is_replay(
        &applied,
        &redirect_dedup,
        origin,
        event.source_partition,
        event.source_offset,
    ) {
        counter!(STAGE1_REPLAY_SKIPPED, "variant" => StateVariant::BehavioralCompressedHistory.as_str())
            .increment(1);
        return None;
    }
    dedup_record(
        &mut applied,
        &mut redirect_dedup,
        origin,
        event.source_partition,
        event.source_offset,
    );

    let first_write = prior_entries.is_none();
    let mut entries = prior_entries.unwrap_or_default();

    let predicate_before = compressed_predicate(&entries, op);

    let event_day = day_idx_in_tz(event_ms, tz);
    let mut window_start_day = if first_write {
        window_start_for_now(event_day, window_days)
    } else {
        prior_window_start_day
    };

    let cur_now_day = now_day_for_window(window_start_day, window_days);
    if event_day > cur_now_day {
        compressed_history::slide_window_forward(
            &mut entries,
            &mut window_start_day,
            window_days,
            event_day,
        );
        compressed_history::insert_event(&mut entries, event_day);
    } else if event_day < window_start_day {
    } else {
        compressed_history::insert_event(&mut entries, event_day);
    }

    let last_event_at_ms = prev_last_event.max(event_ms);
    let earliest_eviction_at_ms =
        compressed_history::compressed_eviction_deadline(&entries, window_days, tz);
    let predicate_after = compressed_predicate(&entries, op);

    let record = StatefulRecord {
        state: Stage1State::BehavioralCompressedHistory {
            entries,
            window_start_day,
            last_event_at_ms,
            earliest_eviction_at_ms,
        },
        applied_offsets: applied,
        redirect_dedup,
    };
    let kind = match (predicate_before, predicate_after) {
        (false, true) => Some(TransitionKind::Entered),
        (true, false) => Some(TransitionKind::Left),
        _ => None,
    };
    let transition = kind.map(|kind| LeafTransition {
        team_id: TeamId(event.team_id),
        leaf_state_key: lsk,
        person_id,
        condition_hash,
        kind,
    });
    Some((record, transition))
}