Churn Signal Detector

Detects behavioural churn signals from usage events and scores account risk.

THE SILENT FAILURE. Churn models fire on the wrong thing. The classic error is treating ABSENCE of events as a signal without distinguishing the user stopping from US no longer receiving data — an instrumentation outage looks exactly like mass churn, and teams have acted on that. The second is comparing against a shifting baseline, so seasonal quiet reads as decline every year.

DISTINGUISHING USER SILENCE FROM DATA SILENCE IS THE PRODUCT. If a whole segment goes quiet simultaneously that is a pipeline signal, not a churn signal, and the detector says which it believes and why.

Risk is scored from individually-inspectable factors; every point names the factor and the observation behind it. There is no opaque score. It REFUSES to score an account with insufficient history rather than returning a low-confidence number that will be read as a real one.

WHAT IT CANNOT KNOW: this detects correlates of churn, not causes, and cannot know intent. It is a prioritisation aid for humans, not a prediction, and the README says so.

VERIFIED: 49 tests, 10/10 mutations caught. Every mutation was observed FAILING before the source was restored — a test never seen to fail is a decoration.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function assertValidPeriod(period: PeriodWindow, label: string): void;
  export function assertNonOverlapping(current: PeriodWindow, baselinePeriods: PeriodWindow[]): void;
  export function countEventsInWindow(events: UsageEvent[], window: PeriodWindow): number;
  export function countNegativeSignalsInWindow(events: UsageEvent[], window: PeriodWindow): number;
  export function mean(values: number[]): number;
  export function tierFor(score: number): ChurnRiskTier;
  export function scoreAccountChurnRisk( history: AccountHistory, options: ScoreOptions, ): ChurnRiskResult;
  export function naiveChurnAlert(currentCount: number, baselineAvg: number): boolean;

  export type ChurnRiskTier = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
  export type SegmentSilenceLabel = "DATA_SILENCE" | "USER_SILENCE" | "INSUFFICIENT_SEGMENT_DATA";