incremnt 0.3.0 → 0.5.0

package/src/increment-score-replay.js

@@ -0,0 +1,822 @@
+import { createHash } from 'node:crypto';
+
+export const INCREMENT_SCORE_REPLAY_VERSION = 'increment-score-replay-v0.1';
+export const PROVISIONAL_FORMULA_VERSION = 'increment-score-provisional-v0.1';
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const SCORE_WEIGHTS = Object.freeze({
+  stimulus: 0.4,
+  progression: 0.2,
+  recovery: 0.2,
+  coverage: 0.15,
+  execution: 0.05
+});
+
+const TARGET_SETS = Object.freeze({
+  chest: { label: 'Chest', target: 8 },
+  back: { label: 'Back', target: 8 },
+  quads: { label: 'Quads', target: 6 },
+  posterior: { label: 'Posterior', target: 6 },
+  shoulders: { label: 'Shoulders', target: 6 },
+  arms: { label: 'Arms', target: 6 }
+});
+
+const EXPORTED_REPLAY_INPUT_KIND = 'incrementScoreReplayInput';
+
+const MUSCLE_ALIASES = new Map([
+  ['chest', 'chest'],
+  ['back', 'back'],
+  ['lats', 'back'],
+  ['upper back', 'back'],
+  ['quads', 'quads'],
+  ['quadriceps', 'quads'],
+  ['legs', 'quads'],
+  ['hamstrings', 'posterior'],
+  ['glutes', 'posterior'],
+  ['posterior chain', 'posterior'],
+  ['shoulders', 'shoulders'],
+  ['delts', 'shoulders'],
+  ['biceps', 'arms'],
+  ['triceps', 'arms'],
+  ['arms', 'arms']
+]);
+
+function clamp(value, min = 0, max = 100) {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, value));
+}
+
+function round(value, places = 0) {
+  const scale = 10 ** places;
+  return Math.round(value * scale) / scale;
+}
+
+function parseDateKey(value) {
+  if (!value) return null;
+  const raw = String(value);
+  if (/^\d{4}-\d{2}-\d{2}/.test(raw)) return raw.slice(0, 10);
+  const parsed = new Date(raw);
+  return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString().slice(0, 10);
+}
+
+function dateFromKey(dateKey) {
+  return new Date(`${dateKey}T00:00:00.000Z`);
+}
+
+function addDays(dateKey, days) {
+  const date = dateFromKey(dateKey);
+  date.setUTCDate(date.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}
+
+function daysBetween(startDateKey, endDateKey) {
+  return Math.round((dateFromKey(endDateKey) - dateFromKey(startDateKey)) / MS_PER_DAY);
+}
+
+function dateRange(startDateKey, endDateKey) {
+  const dates = [];
+  for (let cursor = startDateKey; cursor <= endDateKey; cursor = addDays(cursor, 1)) {
+    dates.push(cursor);
+  }
+  return dates;
+}
+
+function weekStart(dateKey) {
+  const date = dateFromKey(dateKey);
+  const day = date.getUTCDay() || 7;
+  date.setUTCDate(date.getUTCDate() - day + 1);
+  return date.toISOString().slice(0, 10);
+}
+
+function weekEnd(dateKey) {
+  return addDays(weekStart(dateKey), 6);
+}
+
+function completedAtForSession(session) {
+  return session.completedAt ?? session.summary?.date ?? session.date ?? null;
+}
+
+function normalizeExerciseName(name) {
+  return String(name ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function normalizeMuscleGroup(value) {
+  const normalized = String(value ?? '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+  return MUSCLE_ALIASES.get(normalized) ?? normalized;
+}
+
+function e1rmForSet(set) {
+  const weight = Number(set?.weight);
+  const reps = Number(set?.reps);
+  if (!Number.isFinite(weight) || !Number.isFinite(reps) || reps <= 0) return null;
+  if (weight <= 0) return reps;
+  return weight * (1 + reps / 30);
+}
+
+function completedSetsForExercise(exercise) {
+  return (exercise.sets ?? [])
+    .filter((set) => set?.isComplete !== false)
+    .map((set) => ({
+      weight: Number(set.weight ?? 0),
+      reps: Number(set.reps ?? 0),
+      rir: set.rir ?? exercise.rir ?? null,
+      estimatedOneRM: e1rmForSet(set)
+    }))
+    .filter((set) => set.reps > 0 && set.estimatedOneRM != null);
+}
+
+function completedSetsForExportedExercise(exercise) {
+  return (exercise.sets ?? [])
+    .filter((set) => set?.isComplete !== false)
+    .map((set) => {
+      const normalized = {
+        weight: Number(set.weightKg ?? set.weight ?? 0),
+        reps: Number(set.reps ?? 0),
+        rir: set.rir ?? null
+      };
+      return {
+        ...normalized,
+        estimatedOneRM: e1rmForSet(normalized)
+      };
+    })
+    .filter((set) => set.reps > 0 && set.estimatedOneRM != null);
+}
+
+function exportedExerciseName(exercise) {
+  if (exercise.customExercise) {
+    return exercise.customExerciseHash
+      ? `Custom exercise ${String(exercise.customExerciseHash).slice(0, 8)}`
+      : 'Custom exercise';
+  }
+  return exercise.canonicalName ?? exercise.name ?? exercise.exerciseName ?? 'Unknown Exercise';
+}
+
+function normalizeExportedReplayInput(payload, options = {}) {
+  const sessions = (payload?.sessions ?? [])
+    .map((session) => {
+      const date = parseDateKey(session.date ?? session.completedAt);
+      if (!date) return null;
+
+      const plannedSetCounts = new Map((session.prescription?.plannedExercises ?? [])
+        .map((exercise) => [
+          exercise.canonicalName ?? exercise.exerciseName ?? exercise.name,
+          Number(exercise.plannedSets ?? 0)
+        ])
+        .filter(([key, count]) => key && Number.isFinite(count) && count > 0));
+
+      const exercises = (session.exercises ?? []).map((exercise) => {
+        const primaryMuscle = normalizeMuscleGroup(exercise.muscleGroup);
+        const name = exportedExerciseName(exercise);
+        return {
+          name,
+          exerciseKey: String(exercise.canonicalName ?? exercise.customExerciseHash ?? normalizeExerciseName(name)),
+          primaryMuscle,
+          muscleLabel: TARGET_SETS[primaryMuscle]?.label ?? exercise.muscleGroup ?? primaryMuscle ?? 'Unknown',
+          completedSets: completedSetsForExportedExercise(exercise),
+          plannedSetCount: plannedSetCounts.get(exercise.canonicalName) ?? (Array.isArray(exercise.sets) ? exercise.sets.length : null)
+        };
+      });
+
+      const completedSetCount = exercises.reduce((sum, exercise) => sum + exercise.completedSets.length, 0);
+      const plannedSetCount = exercises.reduce((sum, exercise) => {
+        if (exercise.plannedSetCount == null) return sum;
+        return sum + exercise.plannedSetCount;
+      }, 0);
+
+      return {
+        sessionId: session.id ?? null,
+        date,
+        completedAt: session.completedAt ?? session.date ?? null,
+        dayName: null,
+        completedSetCount,
+        plannedSetCount,
+        emptyStrengthSession: completedSetCount === 0,
+        exercises
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => String(left.completedAt ?? left.date).localeCompare(String(right.completedAt ?? right.date)));
+
+  const dates = sessions.map((session) => session.date);
+  const fallbackDate = parseDateKey(options.asOf) ?? new Date().toISOString().slice(0, 10);
+  const from = options.from ?? payload?.replayWindow?.startDate ?? dates[0] ?? fallbackDate;
+  const to = options.to ?? payload?.replayWindow?.endDate ?? dates.at(-1) ?? from;
+  const accountAlias = payload?.source?.accountAlias;
+
+  return {
+    replayVersion: INCREMENT_SCORE_REPLAY_VERSION,
+    formulaVersion: options.formulaVersion ?? payload?.formulaVersion ?? PROVISIONAL_FORMULA_VERSION,
+    source: options.source ?? payload?.source?.type ?? 'replay-input',
+    extractedAt: payload?.extractedAt ?? new Date().toISOString(),
+    user: {
+      label: options.userLabel ?? accountAlias ?? 'User',
+      ref: payload?.source?.accountHash ?? null
+    },
+    sessions,
+    healthMetrics: payload?.healthMetrics ?? {},
+    from,
+    to
+  };
+}
+
+export function normalizedIncrementScoreReplayInput(snapshot, options = {}) {
+  if (snapshot?.replayVersion === INCREMENT_SCORE_REPLAY_VERSION) return snapshot;
+  if (snapshot?.kind === EXPORTED_REPLAY_INPUT_KIND) return normalizeExportedReplayInput(snapshot, options);
+
+  const sessions = (snapshot?.sessions ?? [])
+    .map((session) => {
+      const date = parseDateKey(completedAtForSession(session));
+      if (!date) return null;
+
+      const exercises = (session.exercises ?? []).map((exercise) => {
+        const primaryMuscle = normalizeMuscleGroup(
+          exercise.muscleGroup ?? exercise.primaryMuscleGroup ?? exercise.primaryMuscle
+        );
+        return {
+          name: exercise.name ?? exercise.exerciseName ?? 'Unknown Exercise',
+          exerciseKey: normalizeExerciseName(exercise.name ?? exercise.exerciseName),
+          primaryMuscle,
+          muscleLabel: TARGET_SETS[primaryMuscle]?.label ?? exercise.muscleGroup ?? primaryMuscle ?? 'Unknown',
+          completedSets: completedSetsForExercise(exercise),
+          plannedSetCount: Array.isArray(exercise.sets) ? exercise.sets.length : null
+        };
+      });
+
+      const completedSetCount = exercises.reduce((sum, exercise) => sum + exercise.completedSets.length, 0);
+      const plannedSetCount = exercises.reduce((sum, exercise) => {
+        if (exercise.plannedSetCount == null) return sum;
+        return sum + exercise.plannedSetCount;
+      }, 0);
+
+      return {
+        sessionId: session.id ?? null,
+        date,
+        completedAt: completedAtForSession(session),
+        dayName: session.dayName ?? session.summary?.dayName ?? null,
+        completedSetCount,
+        plannedSetCount,
+        emptyStrengthSession: completedSetCount === 0,
+        exercises
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => String(left.completedAt ?? left.date).localeCompare(String(right.completedAt ?? right.date)));
+
+  const dates = sessions.map((session) => session.date);
+  const fallbackDate = parseDateKey(options.asOf) ?? new Date().toISOString().slice(0, 10);
+  const from = options.from ?? dates[0] ?? fallbackDate;
+  const to = options.to ?? dates.at(-1) ?? from;
+
+  return {
+    replayVersion: INCREMENT_SCORE_REPLAY_VERSION,
+    formulaVersion: options.formulaVersion ?? PROVISIONAL_FORMULA_VERSION,
+    source: options.source ?? 'snapshot',
+    extractedAt: options.extractedAt ?? new Date().toISOString(),
+    user: redactUser(snapshot, options),
+    sessions,
+    healthMetrics: snapshot?.healthMetrics ?? {},
+    from,
+    to
+  };
+}
+
+function redactUser(snapshot, options) {
+  const explicitLabel = options.userLabel ?? snapshot?.replayUserLabel ?? snapshot?.userLabel ?? 'User';
+  const rawId = snapshot?.account?.id ?? snapshot?.accountId ?? snapshot?.userId ?? null;
+  return {
+    label: explicitLabel,
+    ref: rawId ? createHash('sha256').update(String(rawId)).digest('hex').slice(0, 10) : null
+  };
+}
+
+function sessionsInWindow(sessions, startDate, endDate) {
+  return sessions.filter((session) => session.date >= startDate && session.date <= endDate);
+}
+
+function healthReadingsInWindow(metrics, key, startDate, endDate) {
+  return (metrics?.[key] ?? []).filter((reading) => {
+    const date = parseDateKey(reading.date);
+    return date && date >= startDate && date <= endDate;
+  });
+}
+
+function buildProgressionEvents(sessions) {
+  const bestByExercise = new Map();
+  const groupedByDate = new Map();
+
+  for (const session of sessions) {
+    if (!groupedByDate.has(session.date)) groupedByDate.set(session.date, []);
+    groupedByDate.get(session.date).push(session);
+  }
+
+  const eventsByDate = new Map();
+  for (const date of [...groupedByDate.keys()].sort()) {
+    const events = [];
+    const sessionsForDate = groupedByDate.get(date);
+
+    for (const session of sessionsForDate) {
+      const eventKeys = new Set();
+      for (const exercise of session.exercises) {
+        for (const set of exercise.completedSets) {
+          const previousBest = bestByExercise.get(exercise.exerciseKey);
+          if (previousBest != null && set.estimatedOneRM > previousBest * 1.01 && !eventKeys.has(exercise.exerciseKey)) {
+            eventKeys.add(exercise.exerciseKey);
+            events.push({
+              date,
+              sessionId: session.sessionId,
+              exercise: exercise.name,
+              previousBest: round(previousBest, 1),
+              estimatedOneRM: round(set.estimatedOneRM, 1)
+            });
+          }
+        }
+      }
+    }
+
+    for (const session of sessionsForDate) {
+      for (const exercise of session.exercises) {
+        for (const set of exercise.completedSets) {
+          const current = bestByExercise.get(exercise.exerciseKey);
+          if (current == null || set.estimatedOneRM > current) {
+            bestByExercise.set(exercise.exerciseKey, set.estimatedOneRM);
+          }
+        }
+      }
+    }
+
+    if (events.length > 0) eventsByDate.set(date, events);
+  }
+
+  return eventsByDate;
+}
+
+function componentScores({ windowSessions, windowProgressionEvents, healthMetrics, windowStart, date, earliestDate }) {
+  const completedSessions = windowSessions.filter((session) => session.completedSetCount > 0);
+  const emptySessions = windowSessions.filter((session) => session.emptyStrengthSession).length;
+  const completedSetCount = completedSessions.reduce((sum, session) => sum + session.completedSetCount, 0);
+  const plannedSetCount = windowSessions.reduce((sum, session) => sum + (session.plannedSetCount ?? 0), 0);
+  const completionRate = plannedSetCount > 0 ? completedSetCount / plannedSetCount : 1;
+  const setCountsByMuscle = {};
+
+  for (const session of completedSessions) {
+    for (const exercise of session.exercises) {
+      if (!TARGET_SETS[exercise.primaryMuscle]) continue;
+      setCountsByMuscle[exercise.primaryMuscle] = (setCountsByMuscle[exercise.primaryMuscle] ?? 0) + exercise.completedSets.length;
+    }
+  }
+
+  const stimulus = Object.entries(TARGET_SETS).reduce((sum, [muscle, target]) => {
+    return sum + clamp((setCountsByMuscle[muscle] ?? 0) / target.target, 0, 1);
+  }, 0) / Object.keys(TARGET_SETS).length * 100;
+
+  const coveredMuscles = Object.keys(setCountsByMuscle).filter((muscle) => setCountsByMuscle[muscle] > 0);
+  const coverage = coveredMuscles.length / Object.keys(TARGET_SETS).length * 100;
+
+  const progressionEventCount = windowProgressionEvents.reduce((sum, events) => sum + events.length, 0);
+  const historyDays = earliestDate ? daysBetween(earliestDate, date) + 1 : 0;
+  const progression = progressionEventCount > 0
+    ? clamp(45 + progressionEventCount * 18)
+    : (historyDays < 14 ? 45 : 35);
+
+  const recovery = recoveryScore(completedSessions, healthMetrics, windowStart, date);
+  const execution = clamp((completedSessions.length / 3) * 85 + completionRate * 15 - emptySessions * 20);
+
+  return {
+    stimulus: round(stimulus),
+    progression: round(progression),
+    recovery: round(recovery.score),
+    coverage: round(coverage),
+    execution: round(execution),
+    meta: {
+      completedSessions: completedSessions.length,
+      completedSetCount,
+      plannedSetCount,
+      completionRate: round(completionRate, 2),
+      emptySessions,
+      setCountsByMuscle,
+      coveredMuscles,
+      progressionEventCount,
+      recovery
+    }
+  };
+}
+
+function recoveryScore(completedSessions, healthMetrics, windowStart, date) {
+  let score = 88;
+  const sameMuscleWarnings = [];
+  const lastSeenByMuscle = new Map();
+
+  for (const session of [...completedSessions].sort((left, right) => left.date.localeCompare(right.date))) {
+    const muscles = new Set(session.exercises
+      .filter((exercise) => exercise.completedSets.length > 0 && TARGET_SETS[exercise.primaryMuscle])
+      .map((exercise) => exercise.primaryMuscle));
+
+    for (const muscle of muscles) {
+      const previous = lastSeenByMuscle.get(muscle);
+      if (previous) {
+        const gapDays = daysBetween(previous, session.date);
+        if (gapDays < 1) {
+          score -= 25;
+          sameMuscleWarnings.push({ muscle, gapDays, severity: 'high' });
+        } else if (gapDays < 2) {
+          score -= 12;
+          sameMuscleWarnings.push({ muscle, gapDays, severity: 'medium' });
+        } else if (gapDays < 3) {
+          score -= 4;
+          sameMuscleWarnings.push({ muscle, gapDays, severity: 'low' });
+        }
+      }
+      lastSeenByMuscle.set(muscle, session.date);
+    }
+  }
+
+  if (completedSessions.length >= 5) score -= 5;
+
+  const hrv = healthReadingsInWindow(healthMetrics, 'hrv', windowStart, date);
+  const restingHR = healthReadingsInWindow(healthMetrics, 'restingHR', windowStart, date);
+  const sleep = healthReadingsInWindow(healthMetrics, 'sleep', windowStart, date);
+  const availableSignals = [hrv.length > 0, restingHR.length > 0, sleep.length > 0].filter(Boolean).length;
+  if (availableSignals >= 2) score += 4;
+
+  return {
+    score: clamp(score),
+    sameMuscleWarnings,
+    availableSignals
+  };
+}
+
+function totalScore(components) {
+  return round(
+    components.stimulus * SCORE_WEIGHTS.stimulus
+    + components.progression * SCORE_WEIGHTS.progression
+    + components.recovery * SCORE_WEIGHTS.recovery
+    + components.coverage * SCORE_WEIGHTS.coverage
+    + components.execution * SCORE_WEIGHTS.execution
+  );
+}
+
+function dataQualityNotes({ healthMetrics, windowStart, date, earliestDate, completedSessions, noSignal }) {
+  const historyDays = earliestDate ? daysBetween(earliestDate, date) + 1 : 0;
+  const hrv = healthReadingsInWindow(healthMetrics, 'hrv', windowStart, date).length;
+  const restingHR = healthReadingsInWindow(healthMetrics, 'restingHR', windowStart, date).length;
+  const sleep = healthReadingsInWindow(healthMetrics, 'sleep', windowStart, date).length;
+  const availableRecoverySignals = [
+    hrv > 0 ? 'HRV' : null,
+    restingHR > 0 ? 'resting HR' : null,
+    sleep > 0 ? 'sleep' : null
+  ].filter(Boolean);
+  const missingRecoverySignals = [
+    hrv === 0 ? 'HRV' : null,
+    restingHR === 0 ? 'resting HR' : null,
+    sleep === 0 ? 'sleep' : null
+  ].filter(Boolean);
+
+  const confidenceScore = clamp(
+    (historyDays >= 28 ? 40 : historyDays >= 14 ? 28 : 15)
+    + (completedSessions.length >= 3 ? 30 : completedSessions.length >= 1 ? 18 : 0)
+    + availableRecoverySignals.length * 10
+    - (noSignal ? 20 : 0)
+  );
+
+  const confidence = noSignal || confidenceScore < 45
+    ? 'low'
+    : confidenceScore < 70
+      ? 'medium'
+      : 'high';
+
+  const notes = [];
+  notes.push(`History baseline: ${historyDays} day${historyDays === 1 ? '' : 's'} (${historyDays >= 28 ? 'high' : historyDays >= 14 ? 'medium' : 'low'}).`);
+  if (availableRecoverySignals.length > 0) {
+    notes.push(`Health recovery signals present: ${availableRecoverySignals.join(', ')}.`);
+  }
+  if (missingRecoverySignals.length > 0) {
+    notes.push(`Health recovery signals missing: ${missingRecoverySignals.join(', ')}.`);
+  }
+  notes.push('Intra-workout rest quality is not scored until set timing/rest metadata exists.');
+  if (noSignal) notes.push('No completed strength sets in the rolling 7-day window.');
+
+  return {
+    confidence,
+    confidenceScore,
+    healthSignals: {
+      hrvReadings: hrv,
+      restingHRReadings: restingHR,
+      sleepNights: sleep
+    },
+    notes
+  };
+}
+
+function driverCandidates(row, previousScoredRow) {
+  if (row.state === 'no_signal') {
+    return {
+      positive: [],
+      negative: [{ component: 'signal', text: 'No logged strength signal in the rolling 7-day window.', impact: 100 }]
+    };
+  }
+
+  const positives = [];
+  const negatives = [];
+  const meta = row.componentMeta;
+
+  if (row.components.stimulus >= 70) positives.push({ component: 'stimulus', text: 'Productive weekly strength stimulus is near target.', impact: row.components.stimulus });
+  if (row.components.coverage >= 70) positives.push({ component: 'coverage', text: 'Major muscle coverage is broad this week.', impact: row.components.coverage });
+  if (row.components.progression >= 63) positives.push({ component: 'progression', text: `${meta.progressionEventCount} progression signal${meta.progressionEventCount === 1 ? '' : 's'} in the window.`, impact: row.components.progression });
+  if (row.components.execution >= 80) positives.push({ component: 'execution', text: 'Session execution is strong for the week.', impact: row.components.execution });
+  if (row.components.recovery >= 80) positives.push({ component: 'recovery', text: 'Between-session recovery spacing is mostly clear.', impact: row.components.recovery });
+
+  const missingMuscles = Object.entries(TARGET_SETS)
+    .filter(([muscle]) => (meta.setCountsByMuscle[muscle] ?? 0) === 0)
+    .map(([, target]) => target.label);
+  if (missingMuscles.length > 0) negatives.push({ component: 'coverage', text: `${missingMuscles.slice(0, 3).join(', ')} missing from the rolling window.`, impact: 100 - row.components.coverage });
+  if (row.components.stimulus < 55) negatives.push({ component: 'stimulus', text: 'Completed working sets are below weekly target.', impact: 100 - row.components.stimulus });
+  if (meta.recovery.sameMuscleWarnings.length > 0) negatives.push({ component: 'recovery', text: 'Same-muscle sessions are clustered inside the recovery window.', impact: 100 - row.components.recovery });
+  if (row.components.progression < 45) negatives.push({ component: 'progression', text: 'Progression evidence is fading versus prior logged history.', impact: 100 - row.components.progression });
+  if (meta.emptySessions > 0) negatives.push({ component: 'execution', text: `${meta.emptySessions} empty strength session${meta.emptySessions === 1 ? '' : 's'} in the window.`, impact: 60 });
+
+  if (previousScoredRow?.components) {
+    for (const component of Object.keys(SCORE_WEIGHTS)) {
+      const delta = row.components[component] - previousScoredRow.components[component];
+      if (delta >= 12) positives.push({ component, text: `${component} improved ${round(delta)} points day over day.`, impact: delta });
+      if (delta <= -12) negatives.push({ component, text: `${component} dropped ${Math.abs(round(delta))} points day over day.`, impact: Math.abs(delta) });
+    }
+  }
+
+  return {
+    positive: positives.sort((left, right) => right.impact - left.impact).slice(0, 3),
+    negative: negatives.sort((left, right) => right.impact - left.impact).slice(0, 3)
+  };
+}
+
+export function buildIncrementScoreReplay(inputOrSnapshot, options = {}) {
+  const input = normalizedIncrementScoreReplayInput(inputOrSnapshot, options);
+
+  const progressionEventsByDate = buildProgressionEvents(input.sessions);
+  const earliestDate = input.sessions[0]?.date ?? null;
+  const rows = [];
+  let previousRow = null;
+  let previousScoredRow = null;
+
+  for (const date of dateRange(input.from, input.to)) {
+    const windowStart = addDays(date, -6);
+    const windowSessions = sessionsInWindow(input.sessions, windowStart, date);
+    const completedSessions = windowSessions.filter((session) => session.completedSetCount > 0);
+    const noSignal = completedSessions.length === 0;
+    const windowProgressionEvents = dateRange(windowStart, date).map((key) => progressionEventsByDate.get(key) ?? []);
+
+    const quality = dataQualityNotes({
+      healthMetrics: input.healthMetrics,
+      windowStart,
+      date,
+      earliestDate,
+      completedSessions,
+      noSignal
+    });
+
+    let row;
+    if (noSignal) {
+      row = {
+        date,
+        windowStart,
+        windowEnd: date,
+        state: 'no_signal',
+        score: null,
+        scoreDelta: previousRow?.score != null ? null : null,
+        deltaState: previousRow?.score != null ? 'lost_signal' : 'no_signal',
+        trend: 'no_signal',
+        components: {
+          stimulus: 0,
+          progression: 0,
+          recovery: 0,
+          coverage: 0,
+          execution: 0
+        },
+        componentMeta: {
+          completedSessions: 0,
+          completedSetCount: 0,
+          plannedSetCount: windowSessions.reduce((sum, session) => sum + (session.plannedSetCount ?? 0), 0),
+          completionRate: 0,
+          emptySessions: windowSessions.filter((session) => session.emptyStrengthSession).length,
+          setCountsByMuscle: {},
+          coveredMuscles: [],
+          progressionEventCount: 0,
+          recovery: { score: 0, sameMuscleWarnings: [], availableSignals: 0 }
+        },
+        topDrivers: { positive: [], negative: [] },
+        dataQuality: quality
+      };
+    } else {
+      const components = componentScores({
+        windowSessions,
+        windowProgressionEvents,
+        healthMetrics: input.healthMetrics,
+        windowStart,
+        date,
+        earliestDate
+      });
+      const score = totalScore(components);
+      const scoreDelta = previousRow?.score != null ? score - previousRow.score : null;
+      row = {
+        date,
+        windowStart,
+        windowEnd: date,
+        state: 'scored',
+        score,
+        scoreDelta,
+        deltaState: previousRow?.state === 'no_signal' ? 'rebuilt' : (scoreDelta == null ? 'baseline' : 'scored'),
+        trend: trendFor(scoreDelta, previousRow),
+        components: {
+          stimulus: components.stimulus,
+          progression: components.progression,
+          recovery: components.recovery,
+          coverage: components.coverage,
+          execution: components.execution
+        },
+        componentMeta: components.meta,
+        topDrivers: { positive: [], negative: [] },
+        dataQuality: quality
+      };
+    }
+
+    row.topDrivers = driverCandidates(row, previousScoredRow);
+    rows.push(row);
+    previousRow = row;
+    if (row.score != null) previousScoredRow = row;
+  }
+
+  const weeklySummaries = buildWeeklySummaries(rows);
+
+  return {
+    replayVersion: input.replayVersion,
+    formulaVersion: input.formulaVersion,
+    source: input.source,
+    extractedAt: input.extractedAt,
+    user: input.user,
+    dateRange: { from: input.from, to: input.to },
+    dailyRows: rows,
+    weeklySummaries
+  };
+}
+
+function trendFor(scoreDelta, previousRow) {
+  if (previousRow?.state === 'no_signal') return 'rebuilt';
+  if (scoreDelta == null) return 'baseline';
+  if (scoreDelta >= 3) return 'improving';
+  if (scoreDelta <= -3) return 'slipping';
+  return 'stable';
+}
+
+function buildWeeklySummaries(rows) {
+  const grouped = new Map();
+  for (const row of rows) {
+    const key = weekStart(row.date);
+    if (!grouped.has(key)) grouped.set(key, []);
+    grouped.get(key).push(row);
+  }
+
+  const summaries = [];
+  let previousScoredSummary = null;
+  for (const [startDate, weekRows] of [...grouped.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    const scoredRows = weekRows.filter((row) => row.score != null);
+    const lastRow = [...weekRows].reverse().find((row) => row.score != null) ?? weekRows.at(-1);
+    const averageScore = scoredRows.length > 0
+      ? round(scoredRows.reduce((sum, row) => sum + row.score, 0) / scoredRows.length)
+      : null;
+    const components = averageComponents(scoredRows);
+    const scoreDelta = lastRow?.score != null && previousScoredSummary?.score != null
+      ? lastRow.score - previousScoredSummary.score
+      : null;
+
+    const summary = {
+      weekStart: startDate,
+      weekEnd: weekEnd(startDate),
+      state: scoredRows.length > 0 ? 'scored' : 'no_signal',
+      score: lastRow?.score ?? null,
+      averageScore,
+      scoreDelta,
+      trend: scoredRows.length === 0 ? 'no_signal' : trendFor(scoreDelta, previousScoredSummary),
+      scoredDays: scoredRows.length,
+      noSignalDays: weekRows.length - scoredRows.length,
+      components,
+      topDrivers: aggregateDrivers(weekRows),
+      confidenceNotes: [...new Set(weekRows.flatMap((row) => row.dataQuality.notes))].slice(0, 5)
+    };
+
+    summaries.push(summary);
+    if (summary.score != null) previousScoredSummary = summary;
+  }
+
+  return summaries;
+}
+
+function averageComponents(rows) {
+  if (rows.length === 0) {
+    return { stimulus: 0, progression: 0, recovery: 0, coverage: 0, execution: 0 };
+  }
+
+  return Object.fromEntries(Object.keys(SCORE_WEIGHTS).map((component) => [
+    component,
+    round(rows.reduce((sum, row) => sum + row.components[component], 0) / rows.length)
+  ]));
+}
+
+function aggregateDrivers(rows) {
+  const rank = (drivers) => {
+    const byText = new Map();
+    for (const driver of drivers) {
+      const current = byText.get(driver.text) ?? { ...driver, impact: 0, count: 0 };
+      current.impact += driver.impact;
+      current.count += 1;
+      byText.set(driver.text, current);
+    }
+    return [...byText.values()]
+      .sort((left, right) => right.impact - left.impact)
+      .slice(0, 3)
+      .map((driver) => ({
+        component: driver.component,
+        text: driver.text,
+        count: driver.count
+      }));
+  };
+
+  return {
+    positive: rank(rows.flatMap((row) => row.topDrivers.positive)),
+    negative: rank(rows.flatMap((row) => row.topDrivers.negative))
+  };
+}
+
+function formatDelta(delta, state = 'scored') {
+  if (state === 'rebuilt') return 'rebuilt';
+  if (state === 'lost_signal') return 'lost signal';
+  if (state === 'no_signal') return 'no signal';
+  if (delta == null) return 'baseline';
+  return `${delta >= 0 ? '+' : ''}${delta}`;
+}
+
+function formatScore(score) {
+  return score == null ? 'no signal' : String(score);
+}
+
+function driverLines(prefix, drivers) {
+  if (drivers.length === 0) return [`${prefix} none`];
+  return drivers.map((driver) => `${prefix} ${driver.text}`);
+}
+
+export function formatIncrementScoreReplayMarkdown(replay) {
+  const lines = [];
+  lines.push(`# Increment Score Replay - ${replay.user.label}`);
+  lines.push('');
+  if (replay.user.ref) lines.push(`User ref: ${replay.user.ref}`);
+  lines.push(`Range: ${replay.dateRange.from} to ${replay.dateRange.to}`);
+  lines.push(`Formula: ${replay.formulaVersion}`);
+  lines.push(`Replay harness: ${replay.replayVersion}`);
+  lines.push(`Extracted at: ${replay.extractedAt}`);
+  lines.push('');
+
+  lines.push('## Daily Score Rows');
+  lines.push('');
+  lines.push('| Date | Score | Delta | State | Stimulus | Progression | Recovery | Coverage | Execution | Confidence |');
+  lines.push('| --- | ---: | ---: | --- | ---: | ---: | ---: | ---: | ---: | --- |');
+  for (const row of replay.dailyRows) {
+    lines.push([
+      row.date,
+      formatScore(row.score),
+      formatDelta(row.scoreDelta, row.deltaState),
+      row.state,
+      row.components.stimulus,
+      row.components.progression,
+      row.components.recovery,
+      row.components.coverage,
+      row.components.execution,
+      row.dataQuality.confidence
+    ].join(' | ').replace(/^/, '| ').replace(/$/, ' |'));
+  }
+  lines.push('');
+
+  lines.push('## Weekly Summaries');
+  lines.push('');
+  for (const week of replay.weeklySummaries) {
+    lines.push(`### Week Ending ${week.weekEnd}`);
+    lines.push('');
+    lines.push(`Score: ${formatScore(week.score)} (${formatDelta(week.scoreDelta, week.trend)})`);
+    lines.push(`Trend: ${week.trend}`);
+    lines.push(`Scored days: ${week.scoredDays}; no-signal days: ${week.noSignalDays}`);
+    lines.push(`Components: stimulus ${week.components.stimulus}, progression ${week.components.progression}, recovery ${week.components.recovery}, coverage ${week.components.coverage}, execution ${week.components.execution}`);
+    lines.push('');
+    lines.push('Drivers:');
+    for (const line of driverLines('+', week.topDrivers.positive)) lines.push(line);
+    for (const line of driverLines('-', week.topDrivers.negative)) lines.push(line);
+    lines.push('');
+    lines.push('Data quality:');
+    for (const note of week.confidenceNotes) lines.push(`- ${note}`);
+    lines.push('');
+  }
+
+  lines.push('## Calibration Notes');
+  lines.push('');
+  lines.push('- Provisional formula only; replace the adapter when `onemore-9ar` lands.');
+  lines.push('- Snapshot adapter is read-only and emits redacted user refs only.');
+  lines.push('- No raw user exports should be committed with generated reports.');
+
+  return `${lines.join('\n')}\n`;
+}