@sunsteel/contracts 0.86.0 → 0.87.0

package/dist/index.js

@@ -10,7 +10,9 @@ var REP_TYPES = ["FIXED", "RANGE"];
 var PROGRESSION_SCHEMES = [
   "NONE",
   "DOUBLE_PROGRESSION",
-  "DYNAMIC_DOUBLE_PROGRESSION"
+  "DYNAMIC_DOUBLE_PROGRESSION",
+  // ROUT-17: an 8-step block by percentage of a reference max and target RIR.
+  "LINEAR_PERIODIZATION"
 ];
 var MUSCLE_GROUPS = [
   "PECTORAL",
@@ -593,6 +595,224 @@ function requiredToFinish(kind) {
   return k === "WORKING" || k === "DROP";
 }
 
+// src/linear-periodization.ts
+var LP_BLOCK_STEPS = 8;
+var LP_WORKING_SETS = 3;
+var LP_REST_SECONDS = 180;
+var LP_REFERENCE_MAX_KG = 1e3;
+var EASY = { rirMin: 2, rirMax: 3, amrap: false };
+var AMRAP = { rirMin: 0, rirMax: 0, amrap: true };
+var HARD = { rirMin: 1, rirMax: 2, amrap: false };
+var LP_STEPS = [
+  { step: 1, percentage: 0.63, sets: [EASY, EASY, AMRAP] },
+  { step: 2, percentage: 0.66, sets: [EASY, EASY, AMRAP] },
+  { step: 3, percentage: 0.69, sets: [EASY, EASY, AMRAP] },
+  { step: 4, percentage: 0.72, sets: [EASY, EASY, AMRAP] },
+  { step: 5, percentage: 0.75, sets: [HARD, HARD, HARD] },
+  { step: 6, percentage: 0.78, sets: [HARD, HARD, HARD] },
+  { step: 7, percentage: 0.81, sets: [HARD, HARD, HARD] },
+  { step: 8, percentage: 0.85, sets: [HARD, HARD, HARD] }
+];
+function lpStep(step) {
+  const index = Math.min(Math.max(Math.trunc(step) || 1, 1), LP_BLOCK_STEPS);
+  return LP_STEPS[index - 1];
+}
+var LP_RECOVERY = { percentage: 0.7, sets: 2, reps: 5 };
+var tidy = (value) => Math.round(value * 1e6) / 1e6;
+function roundToIncrement(value, increment) {
+  if (!(increment > 0)) return tidy(value);
+  const steps = value / increment;
+  const floor = Math.floor(steps + 1e-9);
+  const fraction = steps - floor;
+  return tidy((fraction > 0.5 + 1e-9 ? floor + 1 : floor) * increment);
+}
+function roundDownToIncrement(value, increment) {
+  if (!(increment > 0)) return tidy(value);
+  return tidy(Math.floor(value / increment + 1e-9) * increment);
+}
+function lpLoadKg(referenceMaxKg, percentage, incrementKg) {
+  return roundToIncrement(referenceMaxKg * percentage, incrementKg);
+}
+var LP_PHASES = ["BLOCK", "RECOVERY", "FINISHED"];
+function startLinearPeriodization(referenceMaxKg, cycle = 1) {
+  return {
+    referenceMaxKg,
+    phase: "BLOCK",
+    step: 1,
+    cycle,
+    samples: [],
+    finishedAt: null,
+    estimatedMaxKg: null,
+    nextReferenceMaxKg: null
+  };
+}
+function linearPeriodizationProblem(state) {
+  if (!Number.isFinite(state.referenceMaxKg) || state.referenceMaxKg <= 0 || state.referenceMaxKg > LP_REFERENCE_MAX_KG) {
+    return "The reference max must be above 0";
+  }
+  if (!LP_PHASES.includes(state.phase)) {
+    return "Unknown block phase";
+  }
+  if (!Number.isInteger(state.step) || state.step < 1 || state.step > LP_BLOCK_STEPS) {
+    return "The block step must be between 1 and 8";
+  }
+  if (!Number.isInteger(state.cycle) || state.cycle < 1) {
+    return "The block number must be 1 or more";
+  }
+  if (state.phase === "RECOVERY" && !((state.nextReferenceMaxKg ?? 0) > 0)) {
+    return "A recovery step needs the next block's reference max";
+  }
+  return null;
+}
+function lpPrescription(state, incrementKg) {
+  if (state.phase === "FINISHED") return [];
+  if (state.phase === "RECOVERY") {
+    const loadKg2 = lpLoadKg(
+      state.referenceMaxKg,
+      LP_RECOVERY.percentage,
+      incrementKg
+    );
+    return Array.from({ length: LP_RECOVERY.sets }, () => ({
+      loadKg: loadKg2,
+      target: null,
+      reps: LP_RECOVERY.reps
+    }));
+  }
+  const step = lpStep(state.step);
+  const loadKg = lpLoadKg(state.referenceMaxKg, step.percentage, incrementKg);
+  return step.sets.map((target) => ({ loadKg, target, reps: null }));
+}
+function lpWorkingSets(sets) {
+  return sets.filter((set) => setKindOf(set) !== "WARMUP");
+}
+var LP_ESTIMATE_STEPS = [7, 8];
+var LP_ESTIMATE_MAX_REPS_TO_FAILURE = 10;
+var LP_ESTIMATE_MIN_SETS = 3;
+function lpRirMidpoint(target) {
+  return (target.rirMin + target.rirMax) / 2;
+}
+function lpSampleRir(sample) {
+  const target = lpStep(sample.step).sets[sample.set - 1] ?? HARD;
+  return lpRirMidpoint(target);
+}
+function lpSetEstimateKg(loadKg, reps, rir) {
+  return loadKg * (1 + (reps + rir) / 30);
+}
+function lpEstimate(samples, incrementKg) {
+  const sets = samples.filter((sample) => LP_ESTIMATE_STEPS.includes(sample.step)).map((sample) => ({ ...sample, rir: lpSampleRir(sample) })).filter(
+    (sample) => sample.reps >= 1 && sample.loadKg > 0 && sample.reps + sample.rir <= LP_ESTIMATE_MAX_REPS_TO_FAILURE
+  ).map((sample) => ({
+    ...sample,
+    estimateKg: tidy(lpSetEstimateKg(sample.loadKg, sample.reps, sample.rir))
+  })).sort((a, b) => a.step - b.step || a.set - b.set);
+  if (sets.length < LP_ESTIMATE_MIN_SETS) {
+    return { estimatedMaxKg: null, sets };
+  }
+  const values = sets.map((set) => set.estimateKg).sort((a, b) => a - b);
+  const middle = Math.floor(values.length / 2);
+  const median = values.length % 2 ? values[middle] : (values[middle - 1] + values[middle]) / 2;
+  return { estimatedMaxKg: roundDownToIncrement(median, incrementKg), sets };
+}
+var LP_PROGRESS_THRESHOLD = 0.025;
+var LP_PROGRESS_CAP = 0.05;
+var LP_NEXT_BLOCK_KINDS = ["PROGRESS", "REPEAT", "RESET"];
+function lpRecommendation(referenceMaxKg, estimatedMaxKg, incrementKg) {
+  if (!(estimatedMaxKg && estimatedMaxKg > 0) || !(referenceMaxKg > 0)) {
+    return { kind: "REPEAT", nextReferenceMaxKg: referenceMaxKg, change: null };
+  }
+  const change = estimatedMaxKg / referenceMaxKg - 1;
+  if (change >= LP_PROGRESS_THRESHOLD - 1e-9) {
+    const capped = Math.min(
+      estimatedMaxKg,
+      referenceMaxKg * (1 + LP_PROGRESS_CAP)
+    );
+    const next = roundDownToIncrement(capped, incrementKg);
+    return {
+      kind: "PROGRESS",
+      nextReferenceMaxKg: next > referenceMaxKg ? next : referenceMaxKg,
+      change
+    };
+  }
+  if (change < -LP_PROGRESS_THRESHOLD - 1e-9) {
+    return {
+      kind: "RESET",
+      nextReferenceMaxKg: roundDownToIncrement(estimatedMaxKg, incrementKg),
+      change
+    };
+  }
+  return { kind: "REPEAT", nextReferenceMaxKg: referenceMaxKg, change };
+}
+function sameLpPosition(a, b) {
+  if (!a || !b) return !a && !b;
+  return a.phase === b.phase && a.step === b.step && a.cycle === b.cycle && Math.abs(a.referenceMaxKg - b.referenceMaxKg) < 1e-6;
+}
+function advanceLinearPeriodization(state, logged, context) {
+  if (state.phase === "FINISHED") return null;
+  const prescribed = lpPrescription(state, context.incrementKg).length;
+  for (let set = 1; set <= prescribed; set += 1) {
+    if (!logged.some((entry) => entry.set === set && entry.completed)) {
+      return null;
+    }
+  }
+  if (state.phase === "RECOVERY") {
+    return startLinearPeriodization(
+      state.nextReferenceMaxKg ?? state.referenceMaxKg,
+      state.cycle + 1
+    );
+  }
+  const samples = LP_ESTIMATE_STEPS.includes(state.step) ? [
+    ...state.samples.filter((sample) => sample.step !== state.step),
+    ...logged.filter((entry) => entry.completed && entry.set <= prescribed).map((entry) => ({
+      sessionId: context.sessionId,
+      step: state.step,
+      set: entry.set,
+      loadKg: entry.loadKg,
+      reps: entry.reps
+    }))
+  ] : state.samples;
+  if (state.step < LP_BLOCK_STEPS) {
+    return { ...state, step: state.step + 1, samples };
+  }
+  return {
+    ...state,
+    phase: "FINISHED",
+    samples,
+    finishedAt: context.finishedAt,
+    estimatedMaxKg: lpEstimate(samples, context.incrementKg).estimatedMaxKg,
+    nextReferenceMaxKg: null
+  };
+}
+function continueLinearPeriodization(state, choice) {
+  if (state.phase !== "FINISHED") return null;
+  if (choice.recovery) {
+    return {
+      ...state,
+      phase: "RECOVERY",
+      nextReferenceMaxKg: choice.referenceMaxKg
+    };
+  }
+  return startLinearPeriodization(choice.referenceMaxKg, state.cycle + 1);
+}
+function lpStoredSets(state, incrementKg) {
+  if (!state) {
+    return Array.from({ length: LP_WORKING_SETS }, () => ({
+      repType: "FIXED",
+      reps: null,
+      weight: null,
+      rir: null,
+      kind: "WORKING"
+    }));
+  }
+  const prescription = state.phase === "FINISHED" ? lpPrescription({ ...state, phase: "BLOCK", step: LP_BLOCK_STEPS }, incrementKg) : lpPrescription(state, incrementKg);
+  return prescription.map((set) => ({
+    repType: "FIXED",
+    reps: set.reps,
+    weight: set.loadKg,
+    rir: set.target ? set.target.rirMin : null,
+    kind: "WORKING"
+  }));
+}
+
 // src/plate-loading.ts
 var CANONICAL_SCALE = 1e4;
 var DENSE_CAPACITY_LIMIT = 2e5;
@@ -1225,7 +1445,9 @@ var NOTIFICATION_KINDS = [
   "TRAINING_PARTNER_ENCOURAGEMENT",
   // NOTIF-07: selected activity from a partner who currently shares it.
   "TRAINING_PARTNER_SESSION",
-  "TRAINING_PARTNER_ACHIEVEMENT"
+  "TRAINING_PARTNER_ACHIEVEMENT",
+  // ROUT-18: an LP exercise finished its 8-step block.
+  "LINEAR_BLOCK_FINISHED"
 ];
 var NOTIFICATIONS_LOOKBACK_DAYS = 30;
 var NOTIFICATIONS_RETENTION_DAYS = 90;
@@ -1412,6 +1634,14 @@ var API_ERROR_MESSAGES = {
   SWAP_SESSION_NOT_ACTIVE: "Exercises can only be swapped in an active session",
   SWAP_SETS_COMPLETED: "This exercise already has completed sets. Swap it before completing any.",
   NOTES_DISCARDED_SESSION: "A discarded workout cannot take notes",
+  // ── Linear periodization (ROUT-17 to ROUT-19) ──────────────────────────
+  LINEAR_BLOCK_INVALID: "This exercise's block is not valid: {reason}",
+  LINEAR_BLOCK_EXTRA_SET: "An exercise on an 8-week block takes no extra sets",
+  LINEAR_BLOCK_KIND_FIXED: "The working sets of an 8-week block cannot change kind",
+  LINEAR_BLOCK_LOAD_FIXED: "The load of an 8-week block is prescribed and cannot be changed",
+  LINEAR_BLOCK_SWAP_ROUTINE: "An exercise on an 8-week block can be swapped for this workout only",
+  LINEAR_BLOCK_NOT_LINEAR: "This exercise is not on an 8-week block",
+  LINEAR_BLOCK_NOT_FINISHED: "This exercise's block has not finished, so there is nothing to choose yet",
   // ── Corrections (LIVE-17) ──────────────────────────────────────────────
   CORRECTION_NOT_COMPLETED: "Only a completed workout can be corrected",
   CORRECTION_NOT_LATEST: "Only your most recent workout can be corrected",
@@ -1641,6 +1871,19 @@ export {
   INCHES_PER_FOOT,
   LENGTH_UNITS,
   LIMITED_SHORTFALL_KG,
+  LP_BLOCK_STEPS,
+  LP_ESTIMATE_MAX_REPS_TO_FAILURE,
+  LP_ESTIMATE_MIN_SETS,
+  LP_ESTIMATE_STEPS,
+  LP_NEXT_BLOCK_KINDS,
+  LP_PHASES,
+  LP_PROGRESS_CAP,
+  LP_PROGRESS_THRESHOLD,
+  LP_RECOVERY,
+  LP_REFERENCE_MAX_KG,
+  LP_REST_SECONDS,
+  LP_STEPS,
+  LP_WORKING_SETS,
   MAX_SETS_PER_EXERCISE,
   MEASURABLE_GOALS_MAX,
   MEASURABLE_GOAL_DIRECTIONS,
@@ -1782,6 +2025,7 @@ export {
   WEIGHT_UNITS,
   WORKOUT_SESSION_STATUSES,
   accountExportFileName,
+  advanceLinearPeriodization,
   apiError,
   apiErrorMessage,
   applyDeload,
@@ -1792,6 +2036,7 @@ export {
   canLinkToNext,
   cmToFeetInches,
   cmToInches,
+  continueLinearPeriodization,
   countsAsWork,
   countsForProgression,
   customExerciseProblem,
@@ -1821,6 +2066,17 @@ export {
   isWithinQuietHours,
   latestBodyWeight,
   leadWorkingWeight,
+  linearPeriodizationProblem,
+  lpEstimate,
+  lpLoadKg,
+  lpPrescription,
+  lpRecommendation,
+  lpRirMidpoint,
+  lpSampleRir,
+  lpSetEstimateKg,
+  lpStep,
+  lpStoredSets,
+  lpWorkingSets,
   matchesDeletionConfirmation,
   messageBodyLength,
   normalizeDashboardLayout,
@@ -1833,10 +2089,14 @@ export {
   requiredToFinish,
   resolveActiveTrainingBlock,
   resolveRoutinePlan,
+  roundDownToIncrement,
+  roundToIncrement,
   routineDayLabel,
+  sameLpPosition,
   sessionCorrectionWindow,
   setKindOf,
   setLogValuesDiffer,
+  startLinearPeriodization,
   summarizeBodyProgress,
   trainingBlockCovers,
   warmUpLoad,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sunsteel/contracts",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ezee969/sunsteel-contracts.git"