Suit And Dive Adjustment

Suit & Dive Adjustment (swim coaching data quality) — v4

v4 reflects the live schema (2026-06-20) + the T1.5 m2 column.

The T1.5 migration (20260620000002_add_m2_column_to_calibration_tables.sql) added the Welford M2 accumulator to both swimmer_suits and swimmer_starts. Without M2, the engine cannot do O(1) online Welford updates; recomputing from the full recorded_times history on every save is O(n) per write and loses precision versus the canonical incremental formula.

The Welford m2 rationale (the precision argument)

For each (swimmer, X, distance, stroke) row, the engine maintains:

• count (already have sample_count)
• mean (already have mean_time_ms)
• M2 (the new column — sum of squared deviations from the mean)
• stddev (cached in stddev_time_ms, derived from M2 each update)

The Welford online update formula is the canonical way to maintain running mean and variance in O(1) per observation:

count_new = count_old + 1
delta    = x_new - mean_old
mean_new = mean_old + delta / count_new
M2_new   = M2_old + delta * (x_new - mean_new)
variance = M2 / (count - 1)
stddev   = sqrt(variance)   # cached into stddev_time_ms

Without M2 stored, the engine cannot do incremental updates. It would have to recompute mean and variance from the full history of recorded_times for that (swimmer, X, distance, stroke) bucket on every save — O(n) per write, with precision drift as the sum gets large. The standard Welford is the answer; M2 is the state we need to keep.

The column is hidden (engine-only). The coach never sees m2 in the UI. The engine reads/writes m2 on every recorded_times insert for the matching bucket. stddev_time_ms stays in the table as a cached value (derived from m2 on each update) for backwards compat with the live swimmer_gears shape.

Schema drift discovery (2026-06-20, unchanged from v3)

When I tried to apply the v2 migration, it failed with:

ERROR: 42883: operator does not exist: uuid = text
HINT:  No operator matches the given name and argument types.
You might need to add explicit type casts.

The error came from the CREATE POLICY in v2's RLS, which used coach_id = auth.uid()::text. The live swimmers.coach_id is uuid (FK to coaches.id), not text. The migration file I read (20260423000000_rls_policies.sql) had the obsolete text-cast pattern; the live DB had been migrated past it. The v3 plan and v3 migration file corrected this by using the live 2-level join pattern (swimmer_id → swimmers.coach_id → coaches.auth_id = auth.uid()). T1 shipped on 2026-06-20.

Lesson (general, not just for Hydrolyze): before drafting a migration, query the live schema (information_schema.columns, pg_constraint, pg_policies) and read the actual state. Migration files are design-time documents; the live DB is the implementation that counts.

The live schema (v4 final)

workout_sets:

• suit boolean NOT NULL DEFAULT false
• start_type text NOT NULL DEFAULT 'in_water'

CHECK (start_type IN ('in_water', 'dive', 'backstroke_start'))

swimmer_suits (matches the live swimmer_gears shape + v4 m2):

• id uuid NOT NULL DEFAULT gen_random_uuid() — PK
• swimmer_id uuid NOT NULL REFERENCES swimmers(id) ON DELETE CASCADE
• suit boolean NOT NULL
• distance integer NOT NULL
• stroke text NOT NULL
• mean_time_ms double precision — nullable
• stddev_time_ms double precision — nullable
• m2 double precision NOT NULL DEFAULT 0 — Welford accumulator (T1.5, 2026-06-20)
• sample_count integer NOT NULL DEFAULT 0
• updated_at timestamptz NOT NULL DEFAULT now()
• UNIQUE (swimmer_id, suit, distance, stroke)
• INDEX on (swimmer_id, distance, stroke)

swimmer_starts (matches swimmer_gears + v4 m2):

• Same 10 columns, with start_type text NOT NULL replacing suit boolean
• UNIQUE (swimmer_id, start_type, distance, stroke)
• INDEX on (swimmer_id, distance, stroke)

RLS (live pattern, both tables):

CREATE POLICY "coach_own_swimmer_suits" ON swimmer_suits
  FOR ALL USING (
    swimmer_id IN (
      SELECT id FROM swimmers
      WHERE coach_id IN (
        SELECT id FROM coaches
        WHERE auth_id = auth.uid()
      )
    )
  );

The engine implication (v4)

HistoricalTimePredictor.predict() becomes a 4-way match (swimmer, stroke, distance, intensity) + 2 calibration multipliers:

predicted = PB * intensity_mult * suit_mult * start_mult
sigma     = max(sampleStdDev(last5), sigmaFloor) + suit_uncertainty + start_uncertainty

Where:

• suit_mult = mean(suit=true at distance/stroke) / mean(suit=false at distance/stroke) — read from swimmer_suits joined to swimmer_id and (distance, stroke).
• start_mult = mean(dive at distance/stroke) / mean(in_water at distance/stroke) — read from swimmer_starts. The in_water row is the reference.

The Welford write path (T6, T7 in the v3 plan) updates the tables on every recorded_times insert using the formula above. The m2 column is the source of truth for variance; stddev_time_ms is the cached value. Without m2, the engine would have to recompute the mean and stddev from full history on every save — O(n) per write and losing precision.

The McEvoy reference (unchanged from v1/v2/v3)

Per the existing people/cameron-mcevoy page:

• McEvoy is a 50m free specialist. He races in textile suits (the

post-2010 FINA rules, no polyurethane). His competition PB is 20.88 in textile. The Cielo record (20.91) was in a tech suit; the difference is ~0.15% — at the limit of detectability from a single race. So for sprint textile racing today, the suit factor is small.

• But: McEvoy does most training in a suit (per the ASP Ep. 11

interview). Hydrolyze's coach-cohort won't. The training band for an unsuit-trained swimmer is shifted relative to McEvoy's suit-trained band. The prediction engine has to handle both.

• McEvoy's dive work: his take-off velocity went from 4.7-4.8 m/s to

a 5.32 m/s best (consistent 5.2). His 10m time dropped from 3.4s to sub-3.1s. The dive is a real, trainable, measurable component.

v1 → v2 → v3 → v4 evolution (design)

• v1 (proposed): Welford-with-m2 schema, RLS via obsolete

text-cast pattern. Never applied.

• v2 (proposed): user simplified to binary suit, 3-value start,

set-level only. RLS still inherited the text-cast pattern. The migration file 20260620000000_suit_and_dive_adjustment.sql is preserved as an OBSOLETE stub.

• v3 (proposed): user added the "components" framing. Schema

drift discovered; live schema is per-(swimmer, X, distance, stroke) stat (not Welford), with 2-level join RLS. T1 shipped with the corrected schema.

• v4 (shipped): T1.5 added the hidden m2 column for online

Welford updates. The schema is now complete: the engine has all the state it needs to do O(1) incremental updates on every recorded_times insert.

See also

• Cameron Mcevoy — the canonical sprint coach case
• Force Velocity Curve Swim Coaching — the F-V framing

the calibration is a precondition for

• RPE (Rate of Perceived Exertion) — the intensity

calibration that this sits alongside

• Hydrolyze Coach Analytics Brainstorm V4 — the

design evolution with the schema-drift discovery

• Hydrolyze Coach Analytics Brainstorm V3 — the v3

brainstorm (binary suit, 3-value start; superseded by v4)

• Hydrolyze Coach Analytics Brainstorm V2 — the v2

brainstorm (4-value enum; superseded)

• Hydrolyze Coach Analytics Brainstorm V1 — the v1

brainstorm (original)

• RPE nomenclature for Hydrolyze intensity — the

sibling intensity calibration

• supabase/migrations/20260620000000_suit_and_dive_adjustment.sql

— the v2 file (OBSOLETE stub, no-op)

• supabase/migrations/20260620000001_suit_and_dive_adjustment_v3.sql

— the v3 file (T1, shipped 2026-06-20)

• supabase/migrations/20260620000002_add_m2_column_to_calibration_tables.sql

— the T1.5 file (m2 column, shipped 2026-06-20)

• ios-native/Hydrolyze/Sources/Services/HistoricalTimePredictor.swift

— the engine file to extend

• ios-native/Hydrolyze/Sources/Services/CalibrationFactors.swift

— to be created in T2

• supabase/migrations/20260423000000_rls_policies.sql — the

STALE migration file (obsolete text-cast pattern); do not trust for live-schema work

Published and managed by TARS, an AI co-author built on Nathan's gbrain.