feat: correlate training volume/intensity history with strength score changes (personal MRV)

[JeffOtano]

Context

Requested by u/Pretty-Dimension-213 on r/tonalgym launch thread:

Do you look through historical workouts and programs and correlate to strength increases OR workouts where volume or power actually went down? That could tell you maximum recoverable volume.

Follow-up from the user: "Isn't it pretty easy for the models to analyze that?"

Current state

The coach tracks per-exercise performance (PRs, plateaus, regressions) across the last ~20 workouts and uses static literature-based volume ranges for programming. It does not correlate a user's training volume/intensity history with their strength score changes over time.

What's missing

An analysis layer that identifies a user's personal maximum recoverable volume (MRV) by finding where more volume stopped producing gains or caused regressions. The data is already available in Tonal's strength scores and workout history -- the missing piece is the analysis engine.

Possible approach

• Pull historical strength score timelines alongside weekly volume/intensity data
• Feed both to the model as a tool result and let it identify inflection points (where volume increases correlated with strength stalls or regressions)
• Use the derived MRV estimate to cap weekly volume in the programming engine instead of relying on static literature ranges

Notes

• This would make periodization significantly more personalized.
• The user pointed out the model should be able to handle this analysis directly, which aligns with the existing tool-driven architecture -- likely a new tool that surfaces the correlated data for the model to reason about.

[JeffOtano]

Investigation Results

Raw data already exists

The data needed for MRV correlation is already in the database:

Table	Key Fields	Link
strengthScoreSnapshots (schema.ts:445-456)	date, overall, upper, lower, core, workoutActivityId	Linked to specific workout
exercisePerformance (schema.ts:429-442)	movementId, date, sets, totalReps, avgWeightLbs, totalVolume	Per-exercise per-workout
completedWorkouts (schema.ts:411-426)	date, totalVolume, totalWork, targetArea	Session-level aggregate

The structural join key exists: strengthScoreSnapshots.workoutActivityId = exercisePerformance.activityId = completedWorkouts.activityId.

What the AI coach can access today

• getStrengthHistoryTool (tools.ts:99-113): up to 30 StrengthScoreHistoryEntry entries (date + per-region scores)
• getWorkoutHistoryTool (tools.ts:129-151): up to 20 workouts with session-level totalVolume
• getWeeklyVolumeTool (coachingTools.ts:298-344): sets per muscle group from current week's draft plans only - not historical actuals
• getWorkoutPerformanceTool (weekTools.ts:305-320): per-exercise history with PR/plateau/regression detection

Key gap: No tool joins volume trends with strength score deltas. The coach would have to reason across two separate tool calls with no structured output.

Existing volume analysis

• computeWeeklyVolume() (periodization.ts:223-254): counts sets per muscle group, but only from draft plans, not historical actuals
• VOLUME_LANDMARKS (periodization.ts:207-217): defines 10-20 sets/week hypertrophy targets per muscle group
• computeProgressMetrics (stats.ts:36-79): aggregates totalWorkouts, avgVolume, workoutsPerWeek over 50 workouts, but no correlation with strength scores
• detectPRs, detectPlateaus, detectRegressions (prDetection.ts): per-movement weight history, no connection to aggregate volume or strength scores

What needs to be built

1. Weekly volume aggregation from historical actuals
A query that sums exercisePerformance.sets grouped by muscle group and calendar week. Requires joining exercisePerformance with movements table (for muscleGroups[]). This join only exists today in computeWeeklyVolume (from plans) and dataExport.ts:194-202.

2. Volume-to-strength correlation function
Takes a time window (e.g., 4-week rolling), computes weekly sets per muscle group from exercisePerformance, correlates with strength score delta from strengthScoreSnapshots over the same window.

3. MRV estimation heuristic
Identifies the volume level per muscle group beyond which strength scores plateau or decline. Requires several mesocycles of data to be meaningful.

4. AI coach tool
A getVolumeStrengthCorrelation or getMRVEstimate tool that returns structured week-over-week volume vs score-change data. Without this, the LLM must reason across two separate tool calls, which is error-prone and token-expensive.

5. Volume type definitions
lib/volumeIntensityTypes.ts has no types for weekly volume time series, MRV thresholds, or volume-to-strength correlation output.

Key files

• convex/schema.ts:429-456 - exercisePerformance and strengthScoreSnapshots tables
• convex/coach/periodization.ts:207-254 - VOLUME_LANDMARKS, computeWeeklyVolume (plans only)
• convex/progressiveOverload.ts:47-75 - per-movement session history computation
• convex/stats.ts:36-79 - computeProgressMetrics (no correlation)
• convex/coach/prDetection.ts - PR/plateau/regression detection (structural model for correlation output)
• convex/ai/tools.ts:99-201 - strength history and workout history tools (separate, no join)
• lib/volumeIntensityTypes.ts - existing types, missing MRV/time-series types

[JeffOtano]

Implementation status on 2026-07-29:

• PR feat: add volume strength correlation tool #593 shipped the structured volume-to-strength correlation tool and is production-deployed at exact merge bb932bc66946f687836485cfccc7bb21c2b4259d.
• The coach can now inspect weekly historical actual-volume vs strength-score deltas in one bounded tool result.
• The programming engine still does not enforce a personal MRV cap. That is intentional until the observational output has enough history to distinguish a durable inflection from noise; green deployment is not evidence that an automatic cap is safe.

Keeping this issue open for the remaining product gate: validate the correlation output on users with sufficient history, define the minimum evidence/recency/confidence contract, then apply only confidence-qualified caps with the existing literature landmarks as a fallback.

[JeffOtano]

Live production validation on 2026-07-29 after #593:

• Read-only evaluation covered six users selected for substantial Strength Score history; no user identifiers are included here.
• One user produced medium-confidence provisional output across 21 paired weeks: upper rho 0.155 (flat), lower rho -0.151 (flat), core rho 0.482 (positive).
• One user produced low-confidence provisional output across 14 paired weeks: upper rho 0.236 (positive), lower rho -0.118 (flat), core rho 0.003 (flat).
• The other four users remained insufficient, with 0, 0, 1, and 6 paired weekly observations despite 17–24 Strength Score observations. Unmapped movement counts ranged from 1 to 8.

This proves the tool returns bounded, interpretable output on real production histories and fails closed when volume coverage is sparse. It does not justify an automatic MRV cap: only two of six sampled histories were provisional, only one reached medium confidence, and the result is observational rather than causal. Keeping #86 open for the confidence/recency contract and a larger mature-history cohort before any programming-engine cap is considered.

[JeffOtano]

Implementation PR #604 merged as f77ab603baecf4b216dedac6db6cd224081bdd30. The production Vercel build completed its Next.js build, then Convex deploy-time TypeScript rejected Array.prototype.at under the Convex compiler target. Recovery PR #606 replaces it with compatible indexed access; both root and convex/tsconfig.json typechecks, 2,277 tests, lint, formatting, Knip, build, and the high-severity audit gate pass locally. Production deployment proof remains pending until #606 clears required review and deploys.

[JeffOtano]

Production recovery and eligibility-contract proof on 2026-07-29:\n\n- Recovery PR #606 merged at 1a83ef2617b2170c98443478727956e93dcdcc2a.\n- Exact-SHA Vercel deployment dpl_83RmdobDhT4qnds3YYYxL8hL5Nxt reached READY. Its logs show the Next build, Convex TypeScript pass, schema validation, and production function push all completed.\n- A read-only production validation selected six users by substantial Strength Score history without exposing identifiers. Across 18 regions, 9 failed closed as insufficient and 9 produced provisional output.\n- Of the 9 provisional regions, 8 were advisory_only: seven lacked a negative relationship and three included unmapped movements (reasons can overlap).\n- Exactly one lower-body region returned eligible_for_mrv_estimation: 22 paired observations, latest paired week 6 days old, medium confidence, negative direction, zero eligibility reasons.\n\nThis proves the 16-week, 28-day recency, movement-mapping, and negative-direction contract is live on real histories and discriminates rather than blanket-qualifying users. It still does not estimate or enforce an automatic MRV cap; one eligible region in this bounded cohort is not enough evidence to turn an observational relationship into a causal programming ceiling. Keeping #86 open for a larger eligible cohort and an estimator validation before any hard-cap behavior.

[JeffOtano]

Final automatic-cap integration review on 2026-07-29:

• Current production analyzer computes a regional Spearman association over completed totalVolume; it does not identify a volume inflection point or emit an MRV threshold.
• The programming engine controls weekly sets per individual muscle/exercise. A regional weight-volume range cannot be converted into that control unit without a declared attribution policy, especially for multi-muscle movements.
• Production validation currently has 1 eligible region out of 18 and no held-out threshold-stability result. Reusing correlation or observed min/max as a cap would turn a potentially confounded association into causal programming behavior.
• Clean-main verification passed: dual-target typecheck and 23 focused correlation/tool/periodization tests.

No cap code was added. The existing fail-closed tool contract remains correct. The next executable gate is a predeclared set-based threshold estimator plus read-only validation across non-overlapping periods and a larger eligible cohort. If that produces a stable threshold, the first code slice should expose an optional backward-compatible advisory ceiling; automatic planner enforcement remains a separate runtime-safety gate with literature landmarks as fallback.

[JeffOtano]

Production estimator validation after PR #608 on 2026-07-29:

• PR feat: estimate personal MRV set thresholds #608 merged at cc14eceaff69522f5068df75c2411135809bea4b, and the exact-SHA Git-backed production deployment reached READY.
• Build evidence shows the optimized Next.js build and TypeScript completed, followed by Convex TypeScript, schema validation, and the production function push. No Vercel runtime errors were recorded from the merge time through this validation.
• A read-only production evaluation selected six users with the most longitudinal Strength Score history; no user identifiers are included here. All six returned the new per-muscle estimator payload.
• Across 54 muscle estimates, all 54 failed closed as insufficient_data with not_enough_non_overlapping_history; paired observations ranged from 0 to 3, versus the predeclared minimum of 12 observations in each non-overlapping half. No threshold was advisory or qualified_for_enforcement.
• The regional correlation layer remained observational: 6 of 18 regions were provisional, and all 6 were advisory_only.

This proves the set-based estimator is deployed, executes against real production histories, and withholds thresholds when the training/validation evidence contract is not met. The stable-threshold cohort gate is not satisfied, so #86 remains open and no automatic programming cap is enabled.