feat(oura): active calories from the ring's own MET stream, behind a default-off Experimental toggle (#2242)

[pipiche38]

Replaces #2273, rebased onto current main. The eight commits there (four layers plus three fixes from the hardware days) are folded into four commits, one per layer, each fix inside the layer it corrects; the end tree is the same as #2273's head. #2273's thread keeps the two hardware read-outs in full. Refs #2242.

What

On an Oura day DailyMetric.activeKcalEst is today computed by the HR-only Keytel path over the ring's sparse banked HR; against Oura's own numbers it correlates at r ≈ −0.1. The ring already streams its own minute-by-minute activity intensity (0x50, MET), which NOOP has only ever kept as a diagnostic JSONL sidecar. This PR persists that series and, behind a default-off Experimental toggle, scores the day's calories from it with Oura's documented rule.

1. Pure estimator — Calories.estimateDayEnergyFromMET / estimateDayEnergyFromMet: active = Σ_{MET ≥ 1.5}(MET − 1.5) × 0.0175 kcal·kg⁻¹·min⁻¹ × weight, resting = the same revised Harris–Benedict the HR path uses over the covered minutes only, coverage reported over the window the caller passes. Missing minutes are unknown — never extrapolated to activity, never banked as rest. A re-served minute counts once: two samples are the same minute when |Δ| × 2 < min(epochS) (a re-served twin lands 2–5 s off its first copy under another session anchor; the ring's own grid steps back a second between records, so a real successor is 59–61 s on). Kotlin pinned to Swift by oracle (the real Calories enum compiled standalone, stdout pasted verbatim into MetCaloriesOracleTest, 84 lines).
2. Storage — ouraMetSample(deviceId, ts, met REAL, state, epochS) keyed (deviceId, ts): GRDB v47-oura-met-sample, Room MIGRATION_40_41 (schema 41), same column order, pinned in schema_oracle.json, on the device-scoped delete lists on both sides. Insert drops a twin by the same integer rule (OuraMetSample.droppingTwins / OuraMetSampleEntity.droppingTwins). epochS is carried per row so a cadence other than 60 s scales rather than skews.
3. Engine selection — analyzeDay gains dayMet (+ dayMetNow, caloriesDiag). MET present ⇒ activeKcalEst = MET total when the stream covers ≥ 50 % of the window (today: of the hours elapsed); below that the number is withheld rather than substituted by the HR path. nil/empty keeps the HR path byte-identical for every WHOOP and pure-function caller. One always-on log line per MET day.
4. Writer, day-cycle fold, toggle + copy — OuraLiveSource fans each anchored 0x50 record out to the table, only while the toggle is on (an OFF install's DB and scores are unchanged). The day-cycle fold (DayCycleIntelligenceIntegration, Android PhysiologicalStepCycleEngine) takes the same decision analyzeDay takes over its own window instead of writing Keytel over it. Settings gains "Experimental · Oura Calories" (Oura-paired only), strings in all locales, README Oura table row, OURA_PROTOCOL.md §6.13 update. The toggle joins the day-cache config signature so a flip re-scores every cached day.

Why this formula, and why no fitted constant

Oura's support page says active calories are "the portion that exceeds 1.5 MET". Taken literally, at the textbook MET→kcal definition (1 MET = 3.5 ml O₂·kg⁻¹·min⁻¹ ≈ 0.0175 kcal·kg⁻¹·min⁻¹), it reproduces the Oura app's own active_calories on the export's per-minute MET series with r = 1.0000 and 0.6 kcal/day RMSE over 75 current-era days (r 0.9999 / 3 kcal over 396 pre-2025 days), zero intercept, the wearer's weight being the only input. The constant was identified by that comparison, not fitted to it — nothing here is calibrated to a vendor number.

Validation (the "tracks a varying input" bar)

• Decode → day sums: the NOOP 0x50 decode reproduces the export's Σ(MET) on 10/10 clean days within 1–8 % (16 days, 16,839 overlapping minutes).
• Timestamp semantics settled: a 0x50 record's timestamp is the END of its last sample — every record length n aligns to the export best at exactly −n minutes (85 % exact minute matches, r 0.90; read forward: 23 % / 0.57). The writer stamps sample i at utc − (n − i)·60, so a record straddling midnight lands on the right days. Documented in §6.13.
• Replay through the estimator (08-13 → 08-26 sidecars): on every day without a confirmed workout NOOP's active kcal is the Oura app's figure to 0.8–1.5 % (n = 8, r = 1.000; the residual is the profile weight).
• The one systematic difference, on purpose: a confirmed workout in the Oura app has its minutes rewritten to the activity type's average MET (two golf rounds read a flat 4.2–4.3 where the wire carries the ring's 2.6–2.9). That is a label, not the sensor, so on such a day NOOP reads 10–27 % below the Oura app. The Settings caption says so.

Still an estimate of true expenditure (Kristiansson et al. 2023: free-living AEE MAPE 46–90 %), labelled as one.

Hardware (Gen 3, iOS, toggle ON)

• 2026-09-16: log MET path - coverage 72% (1035 samples), active 203 kcal — checked by hand against the stored rows (Σ(MET−1.5) = 184.1 MET-min × 0.0175 × 63 kg = 202.9). Two defects found that day, both fixed inside layers 1/2 and 4 here: a minute re-served under a second session anchor counted twice (+8 %), and the day-cycle fold wrote Keytel over the MET decision. With the twin rule: active 183.6 kcal vs the Oura app's 187 (−1.8 %). Details: feat(oura): active calories from the ring's own MET stream, behind a default-off Experimental toggle (#2242) #2273, comment 5713756097.
• 2026-09-17: the stored row carries the MET decision (activeKcalEst 1397.2, the fold's wake-to-wake window, 0.3 % from the calendar line); store dedupe 1,197 rows = 1,197 distinct minutes. It also exposed the ring's one-second grid step, which the first twin rule read as a twin; with the half-period rule the same rows give 245.7 kcal vs the Oura app's 247 (−0.5 %), no workout that day. Details: feat(oura): active calories from the ring's own MET stream, behind a default-off Experimental toggle (#2242) #2273, comment 5727135808.

Verification (on the rebased head)

• swift test: StrandAnalytics 2068/0, WhoopStore 617/0 (schema oracle + device-scoped-table guard included). Strand (macOS) and NOOPiOS both BUILD SUCCEEDED; DayCycleRecoveryTests 10/0 under xcodebuild test.
• Android: compileFullDebugKotlin, testFullDebugUnitTest 6393 run, 8 failures — the dev Mac's French-JVM-locale formatting tests plus one FP artefact, which fail identically on a branch without this change; every test this PR adds or touches is green (MetCaloriesOracleTest, AnalyticsEngineMetCaloriesTest 4/4, DayCycleMetCaloriesTest 3/3, OuraMetSampleMigrationTest 4/4, OuraMetSampleTwinTest 3/3, DayCacheConfigFieldTest 7/7, SchemaOracleTest, WhoopDatabaseUpgradeTest); WhoopDatabaseUpgradeTest runs v40 → v41 through the real chain against the committed schema; IntelligenceEngineJacocoBudgetTest green — the Android read lives inside the existing readDaySkinAndWristOff suspension point because a new suspend call in analyzeRecentOnCpu spills ~700 instructions of continuation state.
• i18n_audit --ci OK, doc_comment_lint OK.

[ryanbr]

Thanks @pipiche38. The schema work is exactly right, and that is the part of a change like this that usually goes wrong. Every pin agrees: roomVersion 41 in @Database and SCHEMA_VERSION, MIGRATION_40_41 both defined and registered in ALL_MIGRATIONS, roomSchemas/41.json added, GRDB v47-oura-met-sample, the new table described "platform": "both", and the two schema_oracle.json copies byte-identical at 15bb95c6c200708e59ab2e08e85a61d4b0320660e433cde17cd606f19f36ffe0, which the oracle's own readme requires.

Withholding the estimate below the coverage floor instead of falling back to the HR path, and judging today's coverage against elapsed hours rather than 24 h, are both the right calls.

One blocker.

The parity ledger fails

parity-governance only runs when Tools/ is touched, so CI stays green on this. main is clean, so these are the branch's:

add-unpaired-function: android/app/src/main/java/com/noop/data/WhoopDao.kt::ouraMetSamples/4#1
add-unpaired-function: android/app/src/main/java/com/noop/data/WhoopDao.kt::countOuraMetFor/1#1
add-unpaired-function: android/app/src/main/java/com/noop/data/WhoopRepository.kt::insertOuraMetSamples/1#1
add-unpaired-function: android/app/src/main/java/com/noop/data/WhoopRepository.kt::ouraMetSamples/4#1

com/noop/data is inside the inventory globs and Packages/WhoopStore/Sources is too, so the Swift side in OuraMetStore.swift should pair with these rather than sit beside them. If the names and arities already correspond, a Swift twin: reference on each Kotlin declaration resolves it; where they genuinely differ in shape, a disposition is the honest answer.

This is the third PR this week to hit that gate with CI green, so the gate is the problem as much as any one branch. I will look at making it visible on PRs that do not touch Tools/.

I have not finished reading the MET arithmetic itself. The schema, the toggle default and the withholding rule are reviewed; the energy maths and its oracle are not yet, and I will come back to those.

[ryanbr]

Coming back with the MET arithmetic I said I had not read. It holds up, and the two places it could have gone badly wrong are both handled deliberately.

The one that would have been serious

activeKcalEst = met.totalKcal reads like a category error: the estimate carries restingKcal, activeKcal and totalKcal separately, and the field is named activeKcalEst. Assigning a total to it would inflate every ring day by a whole resting day the moment the toggle went on, which is a change nobody would attribute to a calories toggle.

It is correct. estimateDayCalories is documented as a "Backward-compatible total-kcal facade for the stored daily metric" and returns estimateDayEnergy(...).totalKcal, so the HR path already puts a TOTAL in that field. activeKcalEst is a pre-existing misnomer and your MetEnergyEstimate doc says it matches the split "so the persisted totalKcal keeps its meaning". Both paths also build their active share the same way, as the excess over resting rather than the gross rate, so the two agree in structure and not only in units. Worth the paragraph because the name invites the wrong conclusion and the next reader deserves to find the answer written down.

The constant

0.0175 is arithmetic, not a fit, and it checks: 3.5 ml O₂·kg⁻¹·min⁻¹ at 5 kcal per litre is 0.0035 L × 5 = 0.0175 kcal·kg⁻¹·min⁻¹ exactly. 1.5 MET is Oura's own documented floor rather than a tuned knob. r = 1.000 at 0.6 kcal/day RMSE over 75 days is what you would expect if the rule IS their rule, which is a much stronger claim than a good fit, and your wording keeps the distinction.

The twin-skip is the other thing I checked: (s.ts - lastStart) * 2 < min(s.secPerSample, lastPeriod), integer, with ties broken to the LOWER reading, so a minute served twice by a re-drain cannot count twice in either coverage or energy. Withholding below 50% coverage instead of substituting the HR path is right, and scoping today's coverage to elapsed hours rather than 24 h is the detail that stops it withholding every morning.

What is left

The branch is dirty against main now, and that one is mine: 44ef71ebe repaired the parity authority, which touches parity_twin_map.json and parity_ledger_baseline.json, so your fifth commit collides with it. The governance suite is 49 of 49 on main again, and the drift was the ledger's own "debt decreased; baseline cleanup is optional" line that the suite asserts is empty.

Rebase onto 44ef71ebe and re-run --refresh-derived. Do not hand-merge parity_twin_map.json: it is generated, and a hand merge produces a file that matches neither tree. Resolve it to main's copy and regenerate. I did exactly that on #2293 half an hour ago and its parity-governance check is green, so the path is known to work. Say the word if you would rather I pushed the rebase for you.

[pipiche38]

Thanks @ryanbr, for the arithmetic read and for pushing the rebase. I had done the same thing locally (resolved to main's copy, re-ran --refresh-derived), and my tree matched your 9d30eb47d byte for byte, including both derived files. So I kept your push and added one commit on top.

58ded8940: the misnomer, written down. You're right that the name invites the wrong conclusion, so both analyzeDay sites now say it at the assignment: activeKcalEst holds a TOTAL, because the HR path's estimateDayCalories already stores estimateDayEnergy(...).totalKcal there. Comment only.

The ledger, from your first review. The full run on this branch listed more than the four you pasted: the toggle adds parameters to existing unpaired functions, and each new arity counts as a new identity. Here is how each one was handled.

Paired with twin claims:

• WhoopRepository.insertOuraMetSamples ↔ WhoopStore.insertOuraMetSamples
• WhoopRepository.ouraMetSamples ↔ WhoopStore.ouraMetSamples. The claim sits on the Repository function because the DAO's @Query pushes its declaration past the 4-line window the ledger uses to attach a claim.
• AnalyticsEngine.analyzeDay, IntelligenceEngine.analyzeRecent and DayCycleIntelligenceIntegration.compute, whose parameter lists grew here.

Removed: WhoopStore.ouraMetSampleCount and WhoopDao.countOuraMetFor. The Swift one was only called from tests, and the Kotlin one had no caller at all. The store tests now count through ouraMetSamples.

platform_specific, where the shapes really differ:

• the Room @Insert and @Query primitives under the paired Repository functions (on Apple, the SQL runs inside the one GRDB function);
• DeviceRegistryDao.deleteOuraMetFor, because Swift clears the table through DeviceRegistryStore's table-name list;
• MIGRATION_40_41.migrate, because its GRDB twin is the v47-oura-met-sample closure, and the schema oracle already pins the pair;
• readDaySkinAndWristOff and PhysiologicalStepCycleEngine.compute, the two JVM 64 KiB extractions. The first already documents itself as deliberately one-sided.

One leftover: the message of 9d30eb47d still says the authority was migrated with --migrate-authority. That was true before 44ef71ebe, but on top of it the plain refresh is what ran. It is only commit text, so I have left it alone rather than force-push over your push.

Verified on the tree as pushed: parity_ledger.py OK; parity_ratchet.py 0 errors; test_parity_* OK; StrandAnalytics 2068/0; WhoopStore 617/0; StrandTests DayCacheConfigField and DayCycleRecovery 17/0; Strand (macOS) and NOOPiOS build after the rebase over the SettingsView rework; Android compiles, and the full suite (6402) has the same 8 failures that reproduce on a clean main checkout; doc lint and i18n_audit --ci clean.

[ryanbr]

Thanks @pipiche38. I checked the three things you said you did rather than taking them on trust, and all three hold: 58ded8940 is comment-only (4 insertions, every one a comment line), ouraMetSampleCount and countOuraMetFor are genuinely gone, and the twin claims are where you describe, including ouraMetSamples sitting on the Repository function because the DAO's @Query pushes the declaration past the claim window. The ledger account is the most complete one anybody has written on a PR here.

You are also right about 9d30eb47d's message. --migrate-authority was what the tree needed before 44ef71ebe; on top of it the plain refresh is what ran, and the message is stale. That is mine, not yours, and leaving it rather than force-pushing over my push was the right call. The squash message is what lands on main, so I will make that one accurate and the branch text can stay as it is.

The rebase no longer conflicts on generated files, it conflicts on meaning

main has moved. The rescore work from PR 2293 landed a few hours ago, and it caches the Effort and calories of a sleep-to-sleep cycle that has already ended, rather than re-reading a day of heart rate every pass. Its key is

loadKey = "\(window.onset)-\(window.endExclusive)|\(hrWitness.joined(separator: ","))"

and hrWitness is a per-owner count and newest timestamp of the HEART RATE in the window. Nothing else.

Your change makes that cycle's calories come from the MET stream instead. Put together, an ended cycle's calories are cached under a key that does not witness the MET series at all, and two things follow:

• A later drain that banks more MET minutes inside an ended window leaves the HR witness unchanged, so the cache keeps serving calories computed from the thinner earlier stream.
• On the first pass after the toggle goes on, cycles already cached under the HR-only key keep serving the HR figure and never recompute from MET.

That second one is the failure your own hunk says you already fixed once: "the log said 1220 kcal, the export held 743". that cache is a second route to the same outcome, and neither PR has the bug alone.

What it needs

A MET witness in the key, mirroring the HR one: a (count, maxTs) aggregate over ouraMetSample for the owner and window, appended to loadKey next to hrWitness. WhoopStore.hrFingerprint(deviceId:from:to:) in Reads.swift is the exact shape, index-only, two aggregates.

There is an irony in that: ouraMetSampleCount, which you removed as dead in answer to my first review, is close to the primitive this now wants. It WAS dead when you removed it. The need only appeared when that work merged ahead of you, so this is the merge order costing you a function rather than a wrong call at the time.

I have aborted my rebase rather than resolve this one, because picking a side here is a design decision about your feature and not a mechanical merge. Tell me if you would rather I pushed the witness myself and you reviewed it, or you take it.