WattFlow Freshness audit

Exacte codeflow van Freshness.

Dit document beschrijft Freshness zoals het nu in de code staat, niet zoals we het marketingmatig zouden samenvatten. We lopen letterlijk langs AppModel, AppleHealthService, FreshnessCalculator, FreshnessSnapshotStore, FreshnessUserSignalsStore, FreshnessPromptGenerator en FreshnessTrainingAdvisor.

Ga direct naar inputs Ga direct naar morning lock Open leesbare gids Open trainingsgids

1. Scope en bronbestanden

Deze audit legt uit wat de huidige code exact doet op 13 april 2026. Het is dus geen wensdocument en ook geen vereenvoudigde supporttekst. Waar een detail belangrijk is voor de werking, staat het hier erin: opslagkeys, lookbackvensters, ankerregels, selectievolgorde, drempels, caps en latere trainingsimpact.

2. Orchestratie in de app

Alle echte Freshness-berekening loopt via AppModel.refreshFreshnessIfAvailable(...). Daar worden de randvoorwaarden gecontroleerd, Apple Health-inputs opgehaald, subjectieve signalen geladen, de calculator gestart en de uitkomst opgeslagen voor de rest van de app.

2.1 Refreshvoorwaarden

let inputs = try await AppleHealthService.shared.loadFreshnessAnalysisInputs()
let currentCheckIn = inputs.first.map { FreshnessUserSignalsStore.loadCheckIn(for: $0.analysisDate) }
let recentCheckIns = FreshnessUserSignalsStore.recentCheckIns()
let recentFeedback = FreshnessUserSignalsStore.recentFeedback()
let personalizationProfile = FreshnessUserSignalsStore.loadPersonalizationProfile()

let computed = FreshnessCalculator.compute(
    inputs: inputs,
    previousState: previousState,
    subjectiveCheckIn: currentCheckIn ?? nil,
    recentCheckIns: recentCheckIns,
    recentFeedback: recentFeedback,
    personalizationSeed: personalizationProfile
)

2.2 Snapshots en opslag

2.3 Subjectieve laag

De subjectieve laag bestaat uit twee losse sporen: een check-in voor vandaag en feedback achteraf. Beide leven in FreshnessUserSignalsStore in de gedeelde suite group.app.ergtrainer.shared.

3. Inputlaag uit Apple Health

AppleHealthService.loadFreshnessAnalysisInputs(dayCount: 35) bouwt standaard 35 analysedagen op, maar kijkt daar ruimer voor terug zodat baselines en anchorselectie voldoende geschiedenis hebben.

3.1 Queries en lookback

3.2 Slaapepisodes en ankers

Slaap is het anker van de hele engine. Health-samples worden eerst samengevoegd tot slaapepisodes, daarna kiest de code per analysedag precies één anker. Dat anker bepaalt analyse-datum, recovery-window, HRV-context en de scheiding tussen gisteren en vandaag.

if let mainSleep = eligibleEpisodes.first(where: {
    $0.asleepDurationSeconds >= 3 * 60 * 60
        && anchorHour(for: $0.interval.end, calendar: calendar).map { 3...12 ~= $0 } == true
}) {
    quality = .anchoredSleep
} else if let fallbackSleep = eligibleEpisodes.first(where: { $0.asleepDurationSeconds >= 2 * 60 * 60 }) {
    quality = .fallbackSleep
} else {
    quality = .inferredMorning
}

3.3 Per-dag intervallen

De activity periods bevatten niet alleen Health-energie en stappen, maar ook alle overlappende workouts. In FreshnessActivityPeriod worden die workouts eerst genormaliseerd zodat dubbels of zwaar overlappende sessies van hetzelfde type samenvallen in één cluster. Daarna gebruikt de code effectiveActiveEnergy als max(activeEnergy, workoutEnergyFloorKilocalories). Daardoor kan een workout nooit “verdwijnen” als Health toevallig minder actieve energie teruggeeft dan de workout zelf al bevat.

3.4 HRV filtering en selectie

De code gebruikt Apple Health SDNN, maar maakt daar in de calculator een log-getransformeerde readiness-proxy van. Niet elke HRV-sample mag mee. De selectie is bewust streng om workoutvervuiling uit de ochtendcontext te houden.

3.5 Overige signalen

4. Score-engine in FreshnessCalculator

FreshnessCalculator.compute(...) werkt in vaste lagen: historie afleiden, baselines bouwen, statuses scoren, componenten combineren, confidence en illness toepassen, morning readiness locken en daarna eventueel intraday begrensd bijsturen.

4.1 Historievensters en baselines

4.2 Sleep component

De sleep component bestaat uit vier deelscores en wordt daarna gewogen opgeteld. De gewichten zijn hard in code: duur 0.45, fragmentatie 0.25, consistentie 0.20 en diepe slaap 0.10.

Daarna krijgt de hele sleep component status normal bij >= 80, deviated bij >= 65 en anders strongDeviation.

4.3 Recovery component

Recovery is een combinatie van HRV-score, rusthartslagscore en HRV-stabiliteit. De HRV-score gebruikt niet de ruwe milliseconden, maar een log-proxy op de gekozen representatieve HRV. De stabiliteit kijkt naar de coefficient of variation van de geselecteerde HRV-samples.

De onderlinge gewichten worden niet hard als vaste percentages gebruikt, maar afgeleid uit het personalisatieprofiel: HRV-gewicht wordt geclamped naar 0.18...0.38, rusthartslag naar 0.14...0.30 en stabiliteit staat vast op 0.16. Daarna wordt genormaliseerd.

4.4 Load context

Load is in Freshness niet simpelweg “hoeveel heb je bewogen”, maar een combinatie van duidelijke workoutbelasting, actieve energie, stappen en een straf voor late trainingen.

loadUnits =
    (clearWorkoutMinutes / 8.0)
    + (clearWorkoutEnergy / 70.0)
    + movementSupport
    + lateWorkoutBonus

Het uiteindelijke loadScore start op 100 en gaat naar beneden via carry-over load (0 / -10 / -22), load state (-2 / 0 / -6 / -12) en eventueel late training. Het resultaat wordt geclamped naar 35...100.

4.5 Caution, illness en confidence

De confidence wordt niet alleen als label getoond, maar trekt de score echt terug richting de neutrale waarde 82 via confidenceAdjustedScore.

4.6 Subjective laag, trends en personalisatie

De check-in wordt vertaald naar een subjectieve score via vermoeidheid, spierpijn, stress en slaapkwaliteit. De gewichten zijn hard: fatigue 0.32, soreness 0.22, stress 0.20, sleep quality 0.26. Het resultaat wordt geclamped naar 25...95.

let tooHighCount = feedback.filter { $0.scoreFeedback == .higherThanExpected }.count
let tooLowCount = feedback.filter { $0.scoreFeedback == .lowerThanExpected }.count
let scoreBias = clampInt(tooLowCount - tooHighCount, lower: -6, upper: 6)

let lateTrainingSensitivity = lateTrainingSensitivity(today: today, history: history)
let recoveryHalfLifeDays = clamp(
    1.0 + lateTrainingSensitivity * 0.8 + max(0, hrvNoise - 0.12) * 2.5,
    lower: 0.8,
    upper: 2.5
)

Het neutral profiel start op: HRV 0.34, rusthartslag 0.22, slaap 0.28, subjective 0.08, load 0.18, caution 0.18, met een neutrale recoveryHalfLifeDays van 1.2 en lateTrainingSensitivity = 0.0.

lateTrainingSensitivity zelf wordt bepaald uit de laatste 10 analysedagen. Alleen dagen met late clear workouts tellen mee. Vervolgens kijkt de code hoeveel van die late dagen minder dan 6,75 uur slaap hadden en hoeveel een representatieve HRV onder 55 ms lieten zien. De ratio van die twee tellers bepaalt de sensitiviteit, geclamped naar 0.0...0.7.

5. Morning readiness en intraday

Hier zit de kern van het model. De score begint niet als een dagscore die continu zweeft, maar als een morning readiness die eerst moet “locken”. Pas daarna mag Freshness overdag nog beperkt omlaag of licht omhoog door dutjes.

5.1 Raw morning readiness

weightedMorningReadiness = weightedAverage([
    (sleepComponent.totalScore, componentWeights.sleep),
    (recoveryComponent.totalScore, componentWeights.recovery),
    (loadScore, componentWeights.load),
    (subjectiveScore ?? 75, componentWeights.subjective)
])

rawMorningReadiness =
    weightedMorningReadiness
    - cautionPenalty
    + subjectiveModifier
    + trendAdjustment
    + profile.scoreBias

adjustedMorningReadiness =
    applyIllnessCap(
        confidenceAdjustedScore(rawMorningReadiness, confidence, neutralScore: 82),
        illness
    )

Belangrijk: voor de huidige dag kan de subjectieve component volledig uit de morning readiness-berekening vallen als er geen check-in is. In dat geval krijgt subjective gewicht 0 in de genormaliseerde componentgewichten.

5.2 Lockvoorwaarden

if expectsMorningHRV == false, hasAnchorContext, hasCoreSignals { lock }
else if expectsMorningHRV, hasAnchorContext, hrvReady { lock }
else if hour >= 9, hasAnchorContext, hasCoreSignals { lock }
else if hour >= 11 { lock }
else { keep collectingMorningSignals }

5.3 Provisional en reuse

5.4 Intraday begrenzing

Zodra de ochtend gelockt is, kan de score nog verschuiven door huidige dagbelasting en dutjes. Maar dat mag alleen binnen strakke grenzen:

• Base intraday adjustment: low 0, medium -4, high -8.
• Extra state correctie: spike risk -2, underloaded +1.
• Dutjesbonus: 20-39 min +2, 40-59 min +3, 60-89 min +4, 90-120 min +3.
• Cap: de candidate freshness mag nooit boven de morning readiness uitkomen.
• Wijzigingslimiet: geen wijziging bij delta van 2 punten of kleiner, maximaal 2 intraday wijzigingen per dag, maximaal 10 punten per wijziging.

Daardoor wordt Freshness expres niet een springerig live dashboard. Overdag mag hij wel reageren, maar alleen als het verschil materieel genoeg is en binnen de begrenzingen blijft.

6. Outputs van de engine

De output is niet alleen een integer score. DailyState bevat ook illness, general load, confidence, morning lock metadata, trainability en verschillende explanationvelden. Daarnaast wordt een detail snapshot gebouwd voor de signaalkaarten en een widgetsnapshot voor homescreen en complicaties.

6.1 DailyState en snapshots

6.2 Huidige UI-oppervlakken

6.3 Promptgenerator

Naast de deterministische advisor bouwt WattFlow ook een compacte contextprompt. Die probeert niet zelf de score opnieuw te berekenen, maar geeft een externe AI alleen de huidige herstelcontext mee.

User freshness: 64
Morning readiness: 68
Trainability: 61 (controlled)
Illness: none
General load: medium
Confidence: 0.78 (moderate)
Caution: mild
Main reason: ...
Score changed: ...

Upcoming workouts:
...

Request:
Adjust plan, keep structure, reduce overload.

7. Effect op training en planning

De Freshness-score is niet alleen informatielaag. Elke plansessie loopt langs FreshnessTrainingAdvisor. Die kijkt niet alleen naar de ruwe score, maar ook naar illness, caution, general load, confidence en trainability.

7.1 Advisor thresholds

Intensieve sessies worden in deze advisor gedefinieerd als categorie .vo2max, .omslagpunt of .test. Dat is dus een inhoudelijke workout-categoriecheck, niet alleen een drempel op IF of TSS.

7.2 Reduce versus replace

8. Auditnotities en grenzen

• Geen medische engine: illness is een trainingscontextlaag, geen diagnose.
• Geen Health, geen Freshness: sync uit of niet geautoriseerd ruimt de snapshots op.
• Slaap blijft de baas: zonder bruikbare slaap valt de code terug op inferred morning anchors, maar dat is expliciet een lagere kwaliteit.
• Confidence doet echt mee: het is geen cosmetisch label; de score wordt echt teruggetrokken richting 82.
• Late training telt dubbel door: niet alleen via carry-over load, maar ook via lateTrainingSensitivity en een extra loadstraf.
• Subjectieve laag is echt, maar UI-route is nu minder zichtbaar: engine, AppModel en opslagpad zijn aanwezig; de huidige viewcode toont vooral de objectieve signaalkaarten.

Deze audit volgt de actuele Freshness-implementatie in de codebasis van WattFlow op 13 april 2026. Als code en UI opnieuw verschuiven, hoort juist deze pagina als eerste mee te veranderen.