SleepStagerV2: decide the canonical cache clipping padding across platforms #43

Summary

Swift and Kotlin SleepStagerV2 use different clipping padding around a staged sleep window:

Both comments imply parity, but they encode different intended contracts. There is no clear oracle, so this must not be fixed automatically.

Static reproduction

Swift uses padLo=330, padHi=390. Kotlin uses PAD_LO=360, PAD_HI=420.

Cause

Swift clips to the documented reach of the widest feature window. Kotlin adds one 30-second epoch of safety margin on both sides.

Impact

The extra Kotlin rows appear outside feature reads, so ordinary stage output may remain unchanged. However, each platform fingerprints a different input window for its cache, which can change cache invalidation and performance.

Decision required

Choose and document one invariant:

1. exact feature reach: 330/390; or
2. one-epoch safety margin: 360/420.

Then align both implementations or record the difference as intentional.

Acceptance criteria

• Document the chosen half-open clipping interval and boundary derivation.
• Match the constants or add an explicit intentional exemption.
• Add automated pad-1/pad/pad+1 boundary tests for output and cache invalidation.
• Do not open an automatic parity-fix PR until the invariant is selected.

No hardware testing is required.