Kigi-CLI/crates/codegen/kigi-fsnotify/src/state.rs

//! Lock-state machine. Pure data + pure transition function. No I/O.

use std::time::{Duration, Instant};

/// Drop transient OS events for this window after a head-changing op;
/// consumers refresh from scratch anyway.
pub(crate) const COOLDOWN_MS: u64 = 500;

/// After a lock release, wait this long before declaring the operation
/// complete: a lock reappearing within the window (a rebase/squash cycles
/// `index.lock` per pick) is the *same* operation, so rapid cycles merge into
/// one `Started`/`Completed` pair instead of storming consumers.
pub const SETTLE_MS: u64 = 500;

/// Diagnostic threshold — fires a one-time warning when a lock is held
/// longer than this. `git gc` on huge repos can exceed this legitimately;
/// the state machine stays locked until the lock file disappears regardless.
const STALE_LOCK_SECS: u64 = 60;

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum LockState {
    Idle,
    Locked {
        head_at_start: Option<String>,
        since: Instant,
    },
    /// Lock released, operation not yet declared complete. `head_at_start`
    /// and `since` are carried from the first `Locked` entry of the merged
    /// operation so re-locks preserve the op-wide HEAD comparison and the
    /// stale-lock clock.
    Settling {
        head_at_start: Option<String>,
        since: Instant,
        until: Instant,
    },
    Cooldown {
        until: Instant,
    },
}

#[derive(Debug, PartialEq, Eq)]
pub(crate) enum LockTransition {
    None,
    Started,
    /// Emitted on any `Locked → !Locked` transition. `head_changed` is the
    /// HEAD comparison; cooldown begins iff true.
    Completed {
        head_changed: bool,
    },
    /// Cooldown timer expired; consumer never sees this — internal only.
    CooldownEnded,
}

/// One step. Pure; mutates `state` from freshly-observed FS facts.
pub(crate) fn drive(
    state: &mut LockState,
    lock_present: bool,
    head_now: Option<String>,
    now: Instant,
    cooldown: Duration,
) -> LockTransition {
    match (state.clone(), lock_present) {
        (LockState::Idle, true) | (LockState::Cooldown { .. }, true) => {
            *state = LockState::Locked {
                head_at_start: head_now,
                since: now,
            };
            LockTransition::Started
        }
        // Same operation resumes: keep the op-start HEAD and `since` so the
        // eventual Completed spans the whole merged op. No duplicate Started —
        // consumers never saw a Completed, so their in-op flag never flipped.
        (
            LockState::Settling {
                head_at_start,
                since,
                ..
            },
            true,
        ) => {
            *state = LockState::Locked {
                head_at_start,
                since,
            };
            LockTransition::None
        }
        // Don't complete yet: give a rapid re-lock the settle window to merge.
        (
            LockState::Locked {
                head_at_start,
                since,
            },
            false,
        ) => {
            *state = LockState::Settling {
                head_at_start,
                since,
                until: now + Duration::from_millis(SETTLE_MS),
            };
            LockTransition::None
        }
        (
            LockState::Settling {
                head_at_start,
                until,
                ..
            },
            false,
        ) if now >= until => {
            let head_changed = head_at_start.as_ref() != head_now.as_ref();
            *state = if head_changed {
                LockState::Cooldown {
                    until: now + cooldown,
                }
            } else {
                LockState::Idle
            };
            LockTransition::Completed { head_changed }
        }
        (LockState::Cooldown { until }, false) if now >= until => {
            *state = LockState::Idle;
            LockTransition::CooldownEnded
        }
        _ => LockTransition::None,
    }
}

/// `check` fires once per stale period; resets when the lock releases.
#[derive(Debug, Default)]
pub(crate) struct StaleWarn {
    warned: bool,
}

impl StaleWarn {
    pub(crate) fn check(&mut self, state: &LockState, now: Instant) -> Option<Duration> {
        match state {
            // Settling counts as held: `since` spans the merged operation, so
            // a long rebase of short lock cycles still warns (once), and the
            // latch doesn't reset in the sub-second gaps between cycles.
            LockState::Locked { since, .. } | LockState::Settling { since, .. } => {
                let elapsed = now.duration_since(*since);
                if !self.warned && elapsed > Duration::from_secs(STALE_LOCK_SECS) {
                    self.warned = true;
                    return Some(elapsed);
                }
                None
            }
            _ => {
                self.warned = false;
                None
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn cooldown() -> Duration {
        Duration::from_millis(500)
    }

    #[test]
    fn idle_to_locked_on_lock_appearance() {
        let mut s = LockState::Idle;
        let now = Instant::now();
        assert_eq!(
            drive(&mut s, true, Some("ref: main".into()), now, cooldown()),
            LockTransition::Started
        );
        assert!(matches!(s, LockState::Locked { .. }));
    }

    /// A lock release no longer completes the operation; it opens the settle
    /// window (rapid re-locks merge) and emits nothing.
    #[test]
    fn locked_to_settling_emits_nothing() {
        let now = Instant::now();
        let mut s = LockState::Locked {
            head_at_start: Some("ref: main".into()),
            since: now,
        };
        assert_eq!(
            drive(&mut s, false, Some("ref: feature".into()), now, cooldown()),
            LockTransition::None
        );
        match &s {
            LockState::Settling {
                head_at_start,
                since,
                until,
            } => {
                assert_eq!(head_at_start.as_deref(), Some("ref: main"));
                assert_eq!(*since, now);
                assert_eq!(*until, now + Duration::from_millis(SETTLE_MS));
            }
            other => panic!("expected Settling, got {other:?}"),
        }
    }

    /// Re-lock inside the settle window: the same operation continues, so the
    /// op-start HEAD and `since` are preserved and nothing is emitted (no
    /// duplicate Started — the consumer's in-op flag never flipped).
    #[test]
    fn settling_relock_preserves_op_start_and_emits_nothing() {
        let op_start = Instant::now();
        let later = op_start + Duration::from_millis(100);
        let mut s = LockState::Settling {
            head_at_start: Some("ref: main".into()),
            since: op_start,
            until: later + Duration::from_millis(400),
        };
        assert_eq!(
            drive(&mut s, true, Some("pick-1".into()), later, cooldown()),
            LockTransition::None
        );
        assert_eq!(
            s,
            LockState::Locked {
                head_at_start: Some("ref: main".into()),
                since: op_start,
            },
            "op-start HEAD and since must survive the re-lock"
        );
    }

    /// Settle expiry emits exactly one Completed comparing the first pick's
    /// pre-op HEAD against the final HEAD (head_changed spans the merged op).
    #[test]
    fn settling_expiry_emits_completed_spanning_merged_op() {
        let now = Instant::now();
        let mut s = LockState::Settling {
            head_at_start: Some("ref: main".into()),
            since: now - Duration::from_secs(1),
            until: now,
        };
        assert_eq!(
            drive(&mut s, false, Some("pick-4".into()), now, cooldown()),
            LockTransition::Completed { head_changed: true }
        );
        assert!(matches!(s, LockState::Cooldown { .. }));
    }

    #[test]
    fn settling_expiry_head_unchanged_goes_idle() {
        let now = Instant::now();
        let mut s = LockState::Settling {
            head_at_start: Some("ref: main".into()),
            since: now - Duration::from_secs(1),
            until: now,
        };
        assert_eq!(
            drive(&mut s, false, Some("ref: main".into()), now, cooldown()),
            LockTransition::Completed {
                head_changed: false
            }
        );
        assert_eq!(s, LockState::Idle);
    }

    #[test]
    fn settling_before_expiry_emits_nothing() {
        let now = Instant::now();
        let mut s = LockState::Settling {
            head_at_start: Some("ref: main".into()),
            since: now,
            until: now + Duration::from_millis(1),
        };
        assert_eq!(
            drive(&mut s, false, Some("pick-1".into()), now, cooldown()),
            LockTransition::None
        );
        assert!(matches!(s, LockState::Settling { .. }));
    }

    #[test]
    fn cooldown_to_idle_after_timer() {
        let start = Instant::now();
        let mut s = LockState::Cooldown { until: start };
        let later = start + Duration::from_millis(1);
        assert_eq!(
            drive(&mut s, false, None, later, cooldown()),
            LockTransition::CooldownEnded
        );
        assert_eq!(s, LockState::Idle);
    }

    #[test]
    fn cooldown_to_locked_on_re_acquire() {
        let now = Instant::now();
        let mut s = LockState::Cooldown {
            until: now + Duration::from_millis(500),
        };
        assert_eq!(
            drive(&mut s, true, Some("ref: main".into()), now, cooldown()),
            LockTransition::Started
        );
        assert!(matches!(s, LockState::Locked { .. }));
    }

    /// Regression: timer-arm `drive()` must report Started so the consumer's
    /// `in_op` flag flips; otherwise FilesChanged events skip buffering.
    #[test]
    fn cooldown_to_locked_when_lock_reappears_at_timer_fire() {
        let now = Instant::now();
        let mut s = LockState::Cooldown { until: now };
        assert_eq!(
            drive(&mut s, true, Some("ref: main".into()), now, cooldown()),
            LockTransition::Started,
        );
        assert!(matches!(s, LockState::Locked { .. }));
    }

    #[test]
    fn no_transition_when_idle_and_no_lock() {
        let mut s = LockState::Idle;
        assert_eq!(
            drive(&mut s, false, None, Instant::now(), cooldown()),
            LockTransition::None
        );
        assert_eq!(s, LockState::Idle);
    }

    #[test]
    fn stale_warn_fires_once_per_stale_period() {
        let now = Instant::now();
        let s = LockState::Locked {
            head_at_start: None,
            since: now - Duration::from_secs(STALE_LOCK_SECS + 1),
        };
        let mut w = StaleWarn::default();
        assert!(w.check(&s, now).is_some());
        // Second check while still Locked: latched, no re-fire.
        assert!(w.check(&s, now).is_none());
    }

    #[test]
    fn stale_warn_resets_when_lock_releases() {
        let now = Instant::now();
        let locked = LockState::Locked {
            head_at_start: None,
            since: now - Duration::from_secs(STALE_LOCK_SECS + 1),
        };
        let mut w = StaleWarn::default();
        assert!(w.check(&locked, now).is_some());
        assert!(w.check(&LockState::Idle, now).is_none());
        // Re-acquire: should fire again.
        assert!(w.check(&locked, now).is_some());
    }

    /// A long rebase made of short lock cycles: `since` spans the merged op,
    /// so the warning fires once past the threshold and the settle gaps
    /// between cycles neither reset the latch nor re-fire it.
    #[test]
    fn stale_warn_spans_merged_op_and_stays_latched_through_settling() {
        let now = Instant::now();
        let op_start = now - Duration::from_secs(STALE_LOCK_SECS + 1);
        let settling = LockState::Settling {
            head_at_start: None,
            since: op_start,
            until: now + Duration::from_millis(SETTLE_MS),
        };
        let locked = LockState::Locked {
            head_at_start: None,
            since: op_start,
        };
        let mut w = StaleWarn::default();
        assert!(w.check(&settling, now).is_some(), "settling counts as held");
        assert!(w.check(&locked, now).is_none(), "latched across re-lock");
        assert!(w.check(&settling, now).is_none(), "latched across release");
    }
}