[pipiche38]

The problem

A Test Centre export is capped at 20 MB and the Oura raw-wire sidecar (oura-raw.jsonl, the only
file a protocol fact can be re-derived from) kept losing the night to it, three separate ways —
measured across the August capture corpus, where 11 of 31 nights' sidecars did not contain the
morning drain and the offline reframer refused them (analysis/oura-hypnogram-ledger.md):

1. Proportional-to-size capping handed 53.9 % of the budget to a bulky research dump and left the
   raw wire capture with 1.9 % — 8 min of an 8.4 h night (…-260809-0716.zip).
2. The sidecar rolled mid-drain: a size-based roll could split one capture session across two
   files, and the export only ever shipped the live one — a 30-second session, while the night sat in a
   generation nothing looked at (…-260810).
3. Largest-wins between generations: once generations were kept, the bundler picked the biggest,
   which is not the newest — a morning export could ship a stale, older night while the current one
   was smaller and got dropped (worse than the omission count suggests: the tool silently reports the
   wrong night when the sidecar happens to hold an older drain).

The fix, in the order the commits landed

1. capEntries shares the cap max-min fairly (water-filling), not in proportion to size: a modest
   stream ships WHOLE, the bytes come off the stream that is merely bulky. Pure, tested
   (testFairAllowancesIsWaterFillingAndNeverBreachesBudget, testSmallHighValueSidecarSurvivesABulkyNeighbour).
2. OuraRawDump is scoped to ONE capture session and never rolls mid-drain — a roll happens only
   at session boundaries, so a drain is always in one file.
3. A RING of raw-sidecar generations is kept (.jsonl.1, .jsonl.2, …) instead of one live file,
   and normalizedOuraEntryName recognises a numeric generation suffix so the bundler can see them.
4. OuraSidecarGenerations.mergePlan (new, pure, package-level in WhoopStore, 14 tests): the
   generations behind one entry name are merged oldest → newest under the ceiling, so the cap's
   keep-the-tail trim preserves the newest capture. Replaces largest-wins. Deterministic regardless of
   directory-listing order; ordered by kinds, not discovery.
5. Test-fixture adaptation for this branch (see the header note).

Scope

Apple-only. Android's TestBundleAssembler.kt exports no Oura sidecars at all today (its
OuraMotionDump/OuraRealStepsDump write files nobody exports) — a wider, pre-existing gap noted on
#2151, not a twin of this. OuraSidecarGenerations is package-level and has no Kotlin twin because
the Android bundler has nothing to merge yet.

Verification

• macOS Strand: BUILD SUCCEEDED + StrandTests 1767/0 (1 pre-existing skip) — app-target
  Swift, verified via xcodebuild … test; TestBundleAssemblerTests and OuraRawDumpSessionTests
  green. WhoopStore swift test 560/0, OuraSidecarGenerationsTests 14/14.
• doc_comment_lint.py OK.
• Hardware: this exact behaviour has shipped on integration/oura-full since 2026-09-05. The
  09-05/09-06 morning export was the first off the fixed build and carried the right night's drain,
  closing the ledger's "limitation 4"; every nightly raw==stored ledger row since (09-06 → 09-12)
  is computed from sidecars this fix kept.

Relates to #1716 (the holed-hypnogram investigation this capture-coverage defect was found under).

[ryanbr]

Thanks @pipiche38, and welcome. This is careful work: three distinct failure modes, each measured against a real corpus rather than reasoned about, and each fixed separately. The one I would have missed is the third, because a largest-wins bundler does not merely drop a night, it ships the WRONG one and says nothing.

One blocker, and it is not visible from your PR

The parity ledger fails on this branch:

FAIL compact baseline drift in finding add-unpaired-function|...
  OuraSidecarGenerations.swift:39: new one-sided swift function ...::entryName/1#1
  OuraSidecarGenerations.swift:51: new one-sided swift function ...::classify/2#1
  OuraSidecarGenerations.swift:93: new one-sided swift function ...::mergePlan/3#1

Packages/WhoopStore/Sources is inside the ledger's Swift scan, so a new file there with no Kotlin twin is debt the governance gate wants declared.

You could not have known, and your 15 green checks are not wrong: that gate is path-filtered to Tools/parity_* and Tools/tests/**, so it does not run on product changes. It is the same filter that has put a red check on three other contributors' PRs this week for drift they did not cause. A daily run on main landed yesterday (#2142), so the first thing to see this would be that, the morning after merge.

The good news: your rationale is already the right one, it just needs recording

Tools/PARITY_GOVERNANCE.md gives exactly three ways to resolve a new one-sided declaration: implement the twin, an experimental disposition with an issue and an expiry, or a durable platform_specific disposition with a concrete rationale.

Yours is the third, and I verified the claim rather than taking it:

• android/app/src/main/java/com/noop/testcentre/TestBundleAssembler.kt mentions Oura zero times
• OuraMotionDump and OuraRealStepsDump are constructed by OuraLiveSource, so they write, and are referenced by no exporter, so nothing ships them

"The Android bundler has nothing to merge yet" is exactly true, and that is a concrete platform rationale rather than a shrug.

What is needed is an entry in Tools/parity_dispositions.json naming the three identities, the platform, and that reason. The registry is manually reviewed on purpose and regeneration cannot populate it, so it has to be written rather than generated.

Happy to add it if you would rather not touch the governance registry on a first PR, or to review yours.

Notes, none blocking

capEntries is the widest part of this. Water-filling changes every export, not only the Oura path, so it is the piece most worth a second reader. The property your test asserts, that a modest stream ships whole and the bytes come off the merely bulky one, is the right shape, and CI ran those tests.

The scope note is accurate and worth keeping in the commit. TestBundleAssembler.kt exporting no Oura sidecars is a real, wider gap and belongs to #2151 rather than here.

I cannot build the Apple app target on this machine, so the Swift side of my review is reading plus your CI: 15 of 15 green, including test (WhoopStore) and both app builds.

[ryanbr]

Correcting my own comment: the disposition I told you to write does not clear this, and there is nothing for you to do.

I quoted PARITY_GOVERNANCE.md, which lists three ways to settle a new one-sided declaration, and assumed the third applied without testing it. I wrote all three entries in the documented platform_specific shape, exact identities, matching identity_sha256, and re-ran the ledger. Same failure, unchanged.

The reason is in build_compact_baseline:

if finding.rule not in BASELINE_REASONS:
    raise ValueError(f"finding {finding.identity} has no reviewed compact-baseline disposition")

It raises for any rule outside a fixed set of five, and consults no registry on the way. add-unpaired-function is not among the five, so a typed disposition is never reached. The message says "has no reviewed compact-baseline disposition", which is what led me to a registry that this path does not read.

What actually settles it

Re-deriving the authority, which is a maintainer action. Once the three functions are part of the base inventory they stop being NEW, and _new_unpaired_diagnostics has nothing to report. Verified on your branch:

OK no NEW parity ledger findings (295 baselined; 258 Swift files ...; 1873 Swift functions ...)

257 files to 258, 1870 functions to 1873, and findings unchanged at 295. So nothing is being waved through: your declarations enter the recorded inventory, and no new debt is accepted.

So the plan is to merge this and re-derive behind it, the same way main was re-derived yesterday. Your PR does not need another commit.

Worth saying, since it is not your problem but it cost you a review round

The documented process and the code disagree for this rule, and the error text points at the registry that cannot help. That is a governance bug rather than a fact about your change, and I will file it. Your Apple-only rationale is still exactly right and belongs in the merge message, it simply is not expressed as a disposition entry.

Everything else in my review stands. Nice work.