HealthLog/src/lib/daily/score-steady.ts

/**
 * "Steady for N weeks": how long the health score has held where it is.
 *
 * The score moves slowly on purpose (long windows against reference bands),
 * so on most days the honest thing to say about it is not a delta but how long
 * it has stayed put. That is a real statement only when it comes with a
 * duration read off the record, which is what this does: it walks the stored
 * daily scores (`HealthScoreRecord`) back from the newest and counts how long
 * the number held.
 *
 * A day belongs to the run while it was computed the same way (same algorithm
 * version, same composition), sat in the same band, and stayed within
 * {@link STEADY_TOLERANCE} points of the newest value, and the newest stored
 * day must match the score on screen the same way. A gap in the record
 * longer than {@link STEADY_MAX_GAP_DAYS} ends the run: an absence is not
 * evidence of steadiness.
 */
import { addDays, dayDiff } from "@/lib/cycle/day-math";

/** Points either side of the newest value that still count as "the same". */
export const STEADY_TOLERANCE = 2;

/** Longest stretch without a stored score the run may bridge. */
export const STEADY_MAX_GAP_DAYS = 3;

/** Shortest run worth saying out loud. One week is not yet a pattern. */
export const STEADY_MIN_WEEKS = 2;

/** How far back the read looks; also the longest run it can report. */
export const STEADY_READ_DAYS = 120;

export interface StoredScoreDay {
  dayKey: string;
  composite: number;
  band: string;
  scoreVersion: number;
  composition: readonly string[];
}

function sameComposition(a: readonly string[], b: readonly string[]): boolean {
  return a.length === b.length && a.every((id, i) => id === b[i]);
}

/** The score the ring shows, as the run is compared against it. */
export interface ShownScore {
  value: number;
  band: string;
  /** Absent on an older snapshot; then only value and band are compared. */
  scoreVersion?: number;
  composition?: readonly string[];
}

/** How long the score has held. */
export interface SteadyRun {
  /** Whole weeks the run covers, counted over stored days that were read. */
  weeks: number;
  /**
   * True when the run reaches the start of what was read
   * ({@link STEADY_READ_DAYS}): the score has held at least `weeks`, and when
   * it started is not known. Said as "at least", never as a start.
   */
  atLeast: boolean;
}

function sameBand(a: string, b: string): boolean {
  return a.toLowerCase() === b.toLowerCase();
}

/**
 * How long the score has held, or null when it has not held for at least
 * {@link STEADY_MIN_WEEKS}. `rows` may come in any order; `todayKey` is the
 * reader's local day, so a record that stopped updating days ago does not
 * claim a run that reaches today. The newest stored day must also agree with
 * the score on screen in value, band and, where the screen says, algorithm
 * version and composition: the ring is computed live, the record nightly,
 * and a run that ended overnight is not "steady" next to a number, or a band,
 * that has moved.
 */
export function steadyRun(
  rows: readonly StoredScoreDay[],
  todayKey: string,
  /** The score the ring shows; a run that does not end there is not told. */
  shown: ShownScore,
): SteadyRun | null {
  if (rows.length === 0) return null;
  const sorted = [...rows].sort((a, b) =>
    a.dayKey < b.dayKey ? 1 : a.dayKey > b.dayKey ? -1 : 0,
  );
  const newest = sorted[0];
  if (dayDiff(todayKey, newest.dayKey) > STEADY_MAX_GAP_DAYS) return null;
  if (Math.abs(newest.composite - shown.value) > STEADY_TOLERANCE) return null;
  if (!sameBand(newest.band, shown.band)) return null;
  if (
    shown.scoreVersion !== undefined &&
    newest.scoreVersion !== shown.scoreVersion
  ) {
    return null;
  }
  if (
    shown.composition !== undefined &&
    !sameComposition(newest.composition, shown.composition)
  ) {
    return null;
  }

  let oldest = newest;
  let broke = false;
  for (const row of sorted.slice(1)) {
    if (
      dayDiff(oldest.dayKey, row.dayKey) > STEADY_MAX_GAP_DAYS ||
      row.scoreVersion !== newest.scoreVersion ||
      !sameComposition(row.composition, newest.composition) ||
      !sameBand(row.band, newest.band) ||
      Math.abs(row.composite - newest.composite) > STEADY_TOLERANCE
    ) {
      broke = true;
      break;
    }
    oldest = row;
  }

  const weeks = Math.floor(dayDiff(todayKey, oldest.dayKey) / 7);
  if (weeks < STEADY_MIN_WEEKS) return null;
  // Nothing ended the run inside what was read, and what was read ends
  // within a bridgeable gap of the read's own start: the run may go back
  // further than anything here can tell.
  const atLeast =
    !broke &&
    dayDiff(oldest.dayKey, addDays(todayKey, -STEADY_READ_DAYS)) <=
      STEADY_MAX_GAP_DAYS;
  return { weeks, atLeast };
}