Read this before touching ring/BLE hardware code (app/src/main/java/com/pulseloop/ring/,
app/src/main/java/com/pulseloop/wearables/). Full detail: docs/qring-ble-adoption.md.
The owner's standing instruction (2026-11-04): open a PR for every change and, once it's verified
(CI green, the repo's own tests and checks run, no unresolved review threads), merge it yourself;
don't leave it waiting. Use a merge commit, the way main's history does.
Then release, every time (owner's correction, 2026-11-04: an earlier "only when asked" was a
mistake). After each merge to main, run the Release workflow (release.yml,
workflow_dispatch) with the next v{name}+{code} tag: check the releases list first, since
another session may have taken the next number, and confirm the release carries both the APK and
SHA256SUMS.txt. The merge rule is also in the Gabriel Design System's AGENTS.md; this release
rule is PulseLoop's.
Do not add a Co-Authored-By trailer to commits in this repo — not for Claude, not for any
other agent or tool. GitHub reads that trailer as a second author and lists the address as a
repository contributor, so an agent appears in the contributors graph beside the maintainer.
This was already the rule, stated in android/docs/crp-r11-hardening-plan.md §"Ground rules" and
android/docs/health-connect-integration.md §4, and it was still violated on 13 commits — because
those are task-specific plan documents that nothing loads automatically, and the rule was nowhere
an agent reliably reads. It lives here now for that reason. The Claude Code harness injects a
session reminder asking for the trailer; that reminder defers to the project's own instructions,
and this is one.
Applies to both repos. Leave the existing commits alone: rewriting them would orphan the release tags and the published APKs hanging off them.
When porting or fixing a ring's BLE protocol (connect/pairing sequence, GATT characteristic
writes, command framing, notification handling), reference the decompiled official vendor
Android app (decompiled-qring-official/, decompiled-jring-offical/, etc., at the repo
root) and match its actual behavior. Do not port iOS's CoreBluetooth sequencing — Android's
Bluetooth stack behaves differently (pairing/bonding flow, MTU negotiation, background
restrictions), and a straight iOS port has caused real pairing/data-collection bugs before.
ScanRecord.getManufacturerSpecificData() returns a SparseArray keyed by company ID, with the
ID removed from the value. CoreBluetooth hands iOS the raw block, company ID and all. Every
coordinator was ported from Swift and therefore matches a little-endian company-ID prefix
(TK5Coordinator 10786501, ColmiSmartHealthCoordinator 1078, LuckRingCoordinator 64ff,
RWfitProtocol.MANUFACTURER_HEX_PREFIXES d605…/d606…). RingBLEClient used to pass
valueAt(0) through untouched, so those prefixes could never appear and every manufacturer-data
fallback in the registry was dead code on Android — a ring whose name the catalog didn't
recognise matched nothing at all (issue #56, an Ale-Hop2211 E1C7 YCBT ring). It also read only
entry 0 despite a comment claiming otherwise.
Build AdvertisementInfo through AdvertisementMatcher (WearableDriver.kt), which restores the
company ID and offers every entry to each coordinator, registry order still outermost. If you
add a coordinator that matches manufacturer bytes, write the prefix in on-air layout (company ID
first) and cover it in AdvertisementMatcherTest.
Same lesson, different field: a name pattern is one convention, so keep it in one constant.
WearableModel.SMARTHEALTH_NAME_PATTERN gates two decisions in series — whether
modelForAdvertisedName returns a card at all, and whether ColmiSmartHealthCoordinator accepts
the name — and the two copies that used to exist drifted into the same bug.
decompiled-*/ is gitignored: a decompiled vendor app is the vendor's code, so read it locally and
cite it, never commit it. decompiled-jring-offical/ is JRing 2.0.8
(com.jaga.ibraceletplus.jyring), decompiled with jadx 1.5.1, and does have Java sources (an
older note calls it dex-only). Its SDK is com.sxr.sdk.ble.keepfit (BluetoothLeService,
IRemoteService).
Restart and factory reset for jring are the vendor's setDeviceMode (0x0E + an 8-byte key,
RingEncoder.makeDeviceModeCommand). The mode numbers are confirmed by the vendor buttons that
send them: 2 "Device off", 3 "Restart device", 4 "Factory reset" / "Reset device". "Restart ring"
in Ring & sync sends mode 3 and then reconnects (RingSyncEngine.restartDevice). For a family
without a verified reboot, it only reconnects. YCBT and LuckRing still have no reset; add one
the same way, from their own decompiles.
The same decompile shows the app passes the ring's BP and sugar through unchanged. The ring
computes them from the profile (0x02) and a cuff reference (0x33, default 120/80, write-only).
That reference is sent to the ring, never added to readings. The ring's 15-minute log of those
estimates is 0x55, gated on 0x20 bit 83. After each day's heart rate, JringHistorySync
imports it together with offline temperature (0x39, bit 10) and offline SpO₂ (0x40, bit 81),
in the vendor's order, and then the workouts the ring recorded in sport mode (0x25). Those are
offered on the Activity tab and added on a tap, like another device's workouts (RingWorkoutLog).
A unit that sets bit 10 is granted TEMPERATURE at runtime. Details: docs/jring-56ff-plan.md, "What the vendor app does with BP and sugar".
A jring workout's heart rate is the vendor's sport mode, not its 180-second check. 0x14 is
setHeartRateMode: bytes 1-4 a duration in seconds (0 = until stopped), byte 5 the sport mode.
14 b4… is the vendor's spot check, so workouts used to stream for three minutes. Workouts send
duration 0 and the sport's mode when 0x20 bit 56 (FUNCTION_SPORT_FROM_APP) is set, as
RunRecordActivity does. Details: docs/jring-56ff-plan.md, "Workout heart rate".
Read this before touching RingBLEClient's publishing, ComparisonRing or any driver that
publishes events itself. Full design: docs/ring-comparison.md.
- The comparison ring publishes to
ComparisonBus, neverPulseEventBus. The app's bus feeds persistence, the device row, the accuracy watcher, Health Connect, Strava and the sync coordinator, all of which are the main ring's. Only diagnostics cross over, marked[comparison ring]. - A driver publishes through
RingCommandWriter.publish, notPulseEventBusdirectly. The comparison client overrides it. A directPulseEventBus.publishBlockingin a driver leaks a second ring of that family into the user's history. comparison_readingsis read by the comparison screen and the accuracy check only. The check grades the second ring against the same reference and stores its rows asCMP:<metric>(ComparisonRingScoring), so the main ring's report cards, corrections and export pause never see them. Never read by a score, chart, export or the coach, and not in the backup. Corrections stay the main ring's: the second ring's numbers aren't used anywhere to correct.- Stop comparing forgets without unbinding (
clearSavedRing, notforget), so the ring stays paired to its own app.
This is the one rule in this file most likely to get silently reverted by a future "generalize to match the vendor app" fix. Read it before changing anything with "bond" in the name.
The real QRing app (decompiled-qring-official/.../DeviceCmdInit.java) bonds unconditionally
whenever a ring's 0x3C device-support reply sets supportBlePair — no per-model check.
PulseLoop deliberately does not copy this. RingBLEClient.bondActiveDevice() also requires
WearableModel.requiresOsBond == true for the resolved model — currently only COLMI_R09,
COLMI_R11, YAWELL_R11. Every other Colmi/Yawell model (notably the R10, which also
reports supportBlePair) stays GATT-only on purpose: bonding triggers a real OS pairing dialog
and puts the ring in the phone's paired-devices list, a UX cost not worth paying for a model that
already holds a stable link without it.
This has already regressed once in production, in the same release: a 2026-07-19 fix for issue #29 (R11 stuck on "Connecting") removed the allowlist in favor of QRing's blanket rule, which fixed the R11 but reopened the R10 pairing-dialog bug that a 2026-07-15 commit had deliberately fixed by introducing the allowlist. Corrected by restoring the allowlist and adding R11/Yawell R11 to it by name.
The rule: when a new model is confirmed (real hardware, or a specific credible user report)
to need an OS bond, add it to WearableModel.requiresOsBond's allowlist by name. Never widen
the condition to "whenever supportBlePair is set" to match the vendor app — that is exactly
the change that caused the regression, and it will cause it again for the R10.
A driver re-route can silently revoke a bond, too. DriverReroute.shouldRerouteToJring moves a
ring off its selected driver post-connect, and re-resolving the model against the JRING family lands
on the generic JRING entry, whose requiresOsBond is false. Root AGENTS.md records one hedged
suspicion — that the R11's full Colmi UART profile (6e40fff0/de5bf728) appears to be gated
behind an OS bond. Unproven, and about one model, but if it holds anywhere then a re-route fired on
a table missing that profile is self-sealing: it prevents the very bond that would reveal it, and
CONNECTED persists the jring family to LAST_WEARABLE_MODEL_KEY, so every later reconnect starts
there and the carousel can't undo it. That is why the re-route is scoped to
scanDetectedType == JRING: only connections where a generic-"SMART_RING" guess was actually
overridden. Don't widen it to "any driver whose services are missing."
See docs/qring-ble-adoption.md §5a for the full history and the decompiled source references.
Read this before touching EventPersistenceSubscriber's DeviceStateChanged branch.
No ring re-supplies more history than its own buffer holds, so the app's copy is the only durable one. A connect may delete nothing at all — not stored history, and (since the iOS-parity fix) not demo rows either. This is not a style preference — it was a data-loss bug three times, in three different shapes (issue #43, the sync-pass variant before it, and the demo-row purge below).
The original design deleted all sleep on connect and re-pulled it, carving YCBT out via
preservesSleepOnConnect because YCBT re-asserts CONNECTED mid-history. That premise was false for
everyone: CRP asks queryHistorySleep(daysAgo = 0), and jring calls makeHistoryQueryCommand() with
its default of 1 day (JringDriver.kt:105), so "delete
everything and ask again" capped stored sleep at a single night — a new night replaced the previous
one instead of joining it. Both the carve-out and the rebuild are gone. What protects a re-synced
day now is upsertSleepSessionAtomic, which reconciles one waking day at a time, idempotently, and
re-points legacy mis-keyed blocks itself — the blanket clear's own stated justification.
Stopping the deletion only stops further loss; it recovers nothing. A ring holds days the app
has never asked for, and asking is cheap because every reply is self-describing — CRP's sleep frame
carries its own day index in payload[0], which CRPDecoder.decodeSleep accepts up to 14, so a
night is dated from the reply rather than from the request, and a day the ring has no record of
simply produces no reply. CRPSyncEngine.sendSleepBackfill therefore pulls the prior week once
per connection (not per pass — runStartup is also the ~30-minute background sync, and this ring
funnels everything through one fdd2 channel).
jring had the same gap and a worse one underneath it (see "#73" below: byte 1 of 0x10 is a day
offset, so the app never asked for today at all). One day per request, so depth is a loop, not a
number. RingSyncCoordinator.syncWindowDays is not that control — despite the "must match
makeHistoryQueryCommand's default" comment it used to carry, it has exactly one use, sizing the
sync-progress window in beginSyncProgress, and it applies to every family. Don't cite it as a
per-family request depth; that mistake is what deferred this fix once already. Two things still make
jring harder than CRP: runStartup is also the ~30-minute background sync, so a wider window must be
gated to once per connection (historyBackfilled) or it re-pulls the whole span every half hour;
and 0x10 returns activity and sleep together — there is no sleep-only request — so each extra
day costs ~96 activity packets (15× 1-minute buckets per packet) on top of the night.
Consequence to keep in mind: nothing bulk-deletes real sleep any more, so a Forget followed by
pairing a different ring carries the previous ring's history over. If that ever needs to change,
it belongs on DeviceForgotten as a deliberate choice, not as a side effect of connecting.
RingConnectionState.CONNECTED also arrives from two unrelated places, and only one is a real
transition:
RingBLEClient's own connect event — always carriesdeviceType(activeCoordinatoris set byinstallDriver, which runs before the CCCD write that gates CONNECTED).RingEventBridge, which maps every decoder'sRingDecodedEvent.Statusto CONNECTED and never setsdeviceType. These are ordinary device-info replies: jring0x0C, LuckRing dev-info, YCBT status packets.runStartupre-sends them, andrunStartupis also the ~30-minute background sync — so they recur for the whole life of a connection.
isConnectTransition(event.deviceType) is that gate. It used to feed connectPurge; now that a
connect deletes nothing, connectPurge ignores its argument and returns ConnectPurge.NOTHING
unconditionally, so isConnectTransition has no production caller left — only
EventPersistenceIdentityTest. It is kept because the distinction is real and gets re-derived
wrongly each time someone needs it, and any future connect-time action wants exactly it. Be precise
about the gate's scope, because it is narrower than it looks: it decides only what a CONNECTED
event may delete. The row write below it — stateRaw = "CONNECTED", lastConnectedAt, lastSyncAt — is
outside the gate and still runs for every decoder Status, so a jring 0x0C reply does still
restamp the device row as freshly connected on each sync pass. That is harmless today; it is not
something the gate prevents, so don't cite it as if it were.
Demo rows are not purged on connect either — match iOS, don't "clean up" for it. The demo
purge was the last surviving fragment of the original "connect = clear everything and rebuild"
design, and it was gated only on "this is the BLE client's own connect". A paired ring
re-establishes its link constantly — measured at roughly one reconnect per five minutes on a COLMI
R10 — so every one of those re-ran clearDemo() and seeded demo data could never survive alongside
a paired ring. Captured live at 09:00:54 with the phone untouched: 772 measurements / 84 activity
days / 36 sleep sessions to zero. iOS has no connect-time demo purge anywhere — its only
deletion of seeded rows is user-initiated inside SeedData, and it handles the demo/real mix by
detecting it (isDemo, source == "mock", DataFreshness.demo) and adapting the UI. Demo data
coexisting with a real ring is an expected state. Demo rows are retired only from
Settings → Backup & data → Clear Demo Data.
ConnectPurge now has exactly one member, NOTHING, and the single-branch whens that switch
on it in EventPersistenceSubscriber and EventPersistenceIdentityTest read as dead code but are
not: they are what makes widening what a connect deletes a compile error instead of a one-line
edit. Don't "simplify" them away. Know the limit, though — it only catches an author who routes the
new deletion through the enum; a bare clearDemo() dropped into the CONNECTED arm still compiles.
The two tests named below are the actual enforcement.
Readers must choose between demo and real rows, because nothing separates them any more. The
purge was also, accidentally, the thing keeping seeded rows out of every unfiltered query. With it
gone the two coexist indefinitely, so DemoDataPolicy (data/DemoDataPolicy.kt) states the rule:
real wins — a reader surfaces demo rows only while the corresponding real series is empty, and
switches to the *Real DAO queries the moment the ring has synced anything. Derived values that
are persisted or exported — hrRestingBaseline, estimatedActiveCalories, Health Connect
records — read *Real unconditionally, since a demo-derived number outlives the demo data behind
it. When you add a query over measurements, activity_daily, or sleep_sessions, decide which
of those two it is; "it's just a read" was how a seeded 56 bpm night became a real user's auto HR
zone floor.
Two related things worth knowing before changing this area:
- Nothing bulk-deletes sleep any more, anywhere in the app. That connect path was the only caller, so there is no retention or pruning mechanism at all now — the tables grow without bound and a Forget doesn't reclaim them. Fine at current row sizes; a deliberate retention policy is a separate piece of work, not something to bolt back onto connect.
- One narrow delete path survives, in
reconcileWakingDay:if (groups.isEmpty())drops that day's rows. It should be unreachable —upsertSleepSessionreturns early on empty stages, so the replacements reaching it are never empty — but it is the one place a re-sync can still remove a stored night, so check it first if history goes missing again.
Corollary for new protocol work: a reply that merely reports something about the device (firmware,
serial, capabilities) is not a connection event. Give it its own RingDecodedEvent — as
FirmwareRevision does — rather than hanging it off Status.
An SR08 synced steps and HR but never a single night of sleep, however long it was worn. The
request depth looked fine; the day being requested was not. getDataByDay(int type, int day)
(IRemoteService.aidl) reaches BluetoothLeService.a(int, int), which writes the type into
bArr[0] — 1 → 16 (0x10, activity+sleep), 2 → 22 (0x16, heart rate), via the
WeatherUtil constants jadx happens to resolve those bytes to — and then the day argument
straight into bArr[1]. One day per call. The caller loops:
DupMainActivity.onGetMultipleSportData decrements P_SYNC_HISTORY_DAY on each day's sync-end and
calls getDataByDay(1, i6) again, counting down to 0.
Read as a count, our 0x10/03 asked for the day before last and 0x10/01 for yesterday, so no
pass ever requested today — and 0x10 is the only source of sleep, so last night could not
arrive. Steps and HR masked it: activity comes from the ring's automatic 0x03 push, and
makeHistoryMeasurementQueryCommand already hardcoded 16 00, i.e. offset 0. The one request that
asked for today was the one that worked, which is the clue that was sitting in the source the whole
time.
Two process notes worth keeping:
- The count reading came from a name that isn't in the vendor SDK. The KDoc cited Gadgetbridge's
triggerActivityReportByDays(); that identifier appears nowhere indecompiled-jring-offical/, only in our own files. A citation to a different project's helper is not vendor evidence — check the decompile, which for this family meansjadx --single-classagainstclasses2.dex, since only the.aidlfiles ship as sources. - Asking for the right day was only half of it — see below. The first fix enqueued the whole window in one pass and recorded the condition that would force the vendor's chain. That condition arrived within a day.
The day-offset fix alone did not restore sleep. On v2.9.1+54-rc1 the same SR08 still showed
45 minutes against an expected 6h30, and the reporter's capture says why: 10 00, 10 01,
10 02 and 16 00 all went out inside 176 ms, with 10 02 landing between two of today's
sleep packets. Four 0x11 packets arrived in total — three consecutive 15-minute blocks for today
(01:15–02:00, exactly the 45 minutes displayed) and one from the previous day. A second request
mid-stream truncates the first, so the window's days were cutting each other off.
JringHistorySync is the fix: one day at a time, the next request held until the current day's
stream goes quiet. Per day, 0x10/offset → settle → 0x16/offset → next day, which is the vendor's
own chain (getDataByDay(1, day) then (2, day), advancing on that day's sync-end).
- The activity/sleep leg is time-settled, not reply-driven, and that is forced. Nothing in the
0x10/0x11wire format marks the end of a day — both are bare runs of 15 one-minute samples. JYouPro is in the same position and does the same thing: a 2000 ms idle timer reset on each reply, which is wheresettleMs' default comes from. The heart-rate leg does have a real end marker (0x16subtype0xFF→HistorySyncFinished) and chains on it. LuckRingHistorySyncis the same machine for the same reason — port from it rather than inventing a third one. The jring version adds the second (HR) leg per day.- A re-entrant
start()is declined, and the caller is told.runStartupis also the ~30-minute background sync, so a pass landing mid-backfill is normal; restarting would abandon the in-flight day mid-stream, which is the truncation itself.startreturns whether it began a pass sohistoryBackfilledis only spent by a pass that ran — otherwise a connection can lose its backfill to a no-op and never ask for the older days again. - A day that answers nothing still gets its HR request.
16 00used to be unconditional and it is the request that always worked; a silent0x10must not take today's HR down with it. - The pass is dropped on disconnect (
JringDriver.connectionDidEnd). The writer outlives the driver, so a timer firing after the link dropped would land a stray0x10in the next connection — the same truncation, arriving from a connection that has already ended. - Timers are epoch-guarded (
JringHistorySync.armTimer).Job.cancel()does not retract a coroutine already past itsdelayand waiting on the monitor, and a stale settle firing into a live stream would re-create the bug from the inside. - The one remaining divergence from the vendor is order: it counts down to today, we lead with today — the day the user opened the app to see, and the one the reporter's prototype validated.
- Don't generalise this to other families.
YCBTHistoryTransferhas a terminal block with a CRC and a YCBT owner read the same history twice back to back byte-identically (11 frames, 1916 bytes) while this SR08 was truncating. Different transports, different failure modes.
Read this before changing anything in CRP* startup, sync, all-day-monitoring, or history code —
and before assuming a "Measure button broken" report is a code regression. Issue #29, 2026-07-22:
a reported HR-measure regression after enabling all-day monitoring (c4d61ca) turned out, on
capture analysis, to most likely be a wear/contact failure — not the code change.
How the mis-diagnosis happened (don't repeat it): the "HR stopped working after build 25"
report looked like the all-day-monitoring commit broke it, and a plausible "single-channel
starvation" story was constructed (the R11 does funnel handshake + timing config + queryAllHistory
- on-demand measures through one
fdd2-write/fdd3-notify path). But the capture contradicted it: during the failed 30 s measure the channel was idle ~18 s, the sleep "dump" was 2 frames, and the ring simply returned nog1/cmd9result. The decisive clue was twogroup 3 / cmd 7frames that appear only in the broken capture — which the vendor (g1/a.java) decodes asonWearStateChange(bArr[0] > 0), i.e. on-finger / skin-contact detection.g3c7 [00]= ring not worn. An optical sensor with no skin contact cannot read HR/SpO₂. This matched the user's own "it says keep your hand still" and hedged "I feel like I lost HR." The all-day change had no supporting evidence as the cause.
Rules / lessons:
-
Diagnose R11 issues from the rawPackets capture, not from "what changed." Decode the actual
group/cmdframes against the vendorg1/a.javaresponse dispatch before attributing a symptom to a recent commit. A known-good "measure button" capture (worn, HR returns ~19 s afterg1/cmd9 [01]) is the baseline to diff against. -
Wear state =
group 3 / cmd 7(onWearStateChange,payload[0] > 0). Decoded as of the wear-state fix:CRPDecoder→RingDecodedEvent.WearingStatus→PulseEvent.WearState. A spot measure in flight is ended byCRPSpotController(see "A CRP spot measurement ends on one result" below), which watches for the rawg3c7 [00]frame as well as the event, and the coordinator surfaces it asmeasureNotWornfor the "put the ring on" message. Gated to CRP — YCBT's wear polarity is unverified. A not-worn measure fails in seconds with guidance instead of spinning the full window silently. -
SpO2 works on the R11 — do not "fix" it by removing the capability. zaggash's 2026-07-23 capture (build 26) contains a real reading:
group 1 / cmd 11payload0x61= 97 %. It is slow and contact-sensitive — the successful measure took 48 s of silence before answering, and only 1 of 3 attempts in that session succeeded. A later session where every attempt failed is a contact problem, not absent hardware. COLMI's product page lists only a "Vcare VC30F heart rate" sensor; that is a marketing page, not a bill of materials, and reading it as proof of no SpO2 hardware already produced one PR that had to be closed (#40). -
HR success does not prove contact is good enough for SpO2. In that same capture HR returned a reading 3 seconds before all three SpO2 attempts — the two that failed and the one that succeeded. HR reads fine at contact quality SpO2 cannot use, so never gate SpO2 messaging on recent HR. "Put the ring on snugly" is the correct advice for an SpO2 failure even when HR just worked.
-
group 3 / cmd 7 [00]predicts measurement failure. It appeared ~4 s into every failed spot measure across both captures and never before the successful one, landing ~2 ms before thegroup 1 / cmd 11 [FF]no-reading sentinel. Keeping the fast-fail is right: it turns a 60 s dead wait into a ~4.5 s failure. Note the ring never emits[01]in either capture, so treat it as a failure signal rather than a literal wear flag — but its user-facing advice (improve contact) is correct either way. -
Read-backs exist — ask the ring instead of guessing.
querySupportSpO2Type(2/37) answers NOT_SUPPORT / SLEEP_OXYGEN / TIMING_OXYGEN, and the monitor-state queries2/6HR,2/7HRV,2/8SpO2,2/45stress,2/21temp each report the configured interval (0= off). These are how you tell "the monitor is switched off" apart from "this ring lacks the sensor". Send them once per connection, not per poll pass:runStartupis also the ~30-minute background sync. The R100 capture in issue #58 shows what a useful answer looks like and what silence means:2/6HR,2/7HRV,2/8SpO2 all replied05(5-minute interval, enabled) and2/21temp replied06, while2/45stress and2/37SpO2-type answered nothing across 22 sync passes — the same ring that also never answers the stress history query2/47. On that ring stress is absent, not switched off. Note the app still advertisesSTRESSfor it, becauseCRPCoordinator.capabilitiesis a static family set, not something the ring confirmed — a capability list is not evidence about an individual ring. -
Group 7 is Gomore, not device info — an opcode read off a decompiled builder is a guess until you check its caller. Firmware was queried on
7/1and never answered (23 sends, 0 replies), which read like ring firmware ignoring a valid vendor command. It wasn't: every builder inb1/rresolves to a Gomore call ind1/b.java(7/0querySupportGomore,7/1querySavedGomoreKey,7/2queryGomoreEUID,7/3sendGomoreKey,7/13queryGomoreVersion). The constants had been built by pairingb1/r's methods with opcodes positionally (a→0, b→1, c→13) — but jadx alphabetises method names, so letter order carries no meaning. The same slip mislabelled3/1(shutDown) asCMD_RESTART; restart is3/14. Resolve every opcode through itsd1/b.javacaller, never by position in the builder class. -
Firmware version is
3/3, replying with a bare UTF-8 string (g1/a.i1:onVersion(new String(payload, UTF_8))) —MOY-R1K3-2.1.6on zaggash's R11, matching the vendor app's Firmware-information screen. Decoded intoRingDecodedEvent.FirmwareRevision, which exists because neither older event fits:FirmwareVersioncarries anInt(the jring0xF6build), andStatusbridges toDeviceStateChanged(CONNECTED, …)— a connection-state event, which a firmware string is not. Sibling group-3 queries confirmed from their callers:3/0reset,3/1shutDown,3/4firmware hash,3/6real-time battery,3/7wear state,3/14restart,3/22binding reminder. -
Temperature history is
2/22, not2/48, and its layout is now CONFIRMED (issue #58).q.b(2,48)is the vendor'squerySleepState(d1/b.javaline 650); real temp history isi0.b(day, frameIndex)=q.c(2,22,[day,idx]), the same shape as the other timing histories. The R100 capture attached to issue #58 is the first non-empty temperature reply anyone has sent us, and it matches the vendor parsere1/mbyte for byte:[day][frameIndex]then little-endian 2-byte tenths of a degree Celsius per 5-minute slot, 72 slots/frame, terminal index 3 (four frames/day, like HRV), clamp 28.0–50.0 °C with anything outside meaning "no reading" (e1/m.a). Decoded inCRPDecoder.decodeTimingHistory. Note what the missing decode cost beyond the samples: with noTimingHistoryFramemarker emitted,CRPSyncEnginenever advanced the cursor, so the ring was asked for frame 0 on every pass and never for frames 1-3 — 18:00 onward of every day was unreachable. -
The multi-frame follow-up is hardware-validated (was open on rc3): HR asked frames (0,0)+(0,1) and got both; HRV asked (0,0)…(0,3) and got all four. HR history decoded 27 readings at 00:10–11:35 local (46–104 bpm), HRV 11 readings (30–56 ms), sleep 12 records across light/deep/REM — so the local-midnight anchoring is right and there is no UTC drift.
-
The single-channel contention theory is plausible but unproven — no capture has shown a spot measure starved by an active history dump. Don't treat it as established; if you suspect it, prove it from a capture where the channel is actually saturated during a failed measure. It is still the reason to keep per-pass traffic lean (see the read-backs above).
-
All-day "timing" vital history is DECODED (build 27, rc3), confirmed against zaggash's rc2 capture. Layout (vendor
e1/{f,d,g,l}.java, group 2): a query[day, frameIndex]returns[day][frameIndex][slots…], one 5-minute slot per sample (w0.b.a()/5),0= no reading. HR (cmd 15) / SpO2 (17) / stress (47) are one byte/slot, 144 slots/frame, terminal frame index 1 (two frames = 288 slots = 24 h). HRV (cmd 16) is a little-endian 2-byte value per slot, 72 slots/frame, terminal index 3 (four frames). Clamps: HR 40..200, SpO2 ≤100, HRV any positive, stress 1..100. Each slot's time =localMidnight(today − day) + globalSlot*5min(ring stamps against local midnight — a UTC-vs-local offset makes samples look "in the future" in a raw capture; that's expected, not a bug).CRPDecoder.decodeTimingHistoryemits oneHistoryMeasurementper valid slot (persisted idempotently,source="history") plus aTimingHistoryFramemarker that drivesCRPSyncEngine.handleto pull the next frame — the vendor's sequentialinsertBleMessage(<query>.b(day, index+1)). Still to hardware-validate on rc3: that the ring answers a direct[day, index>0]request (the multi-frame follow-up). In the rc2 capture SpO2 came back all-zero and stress didn't reply at all — confirm those all-day monitors are actually enabled on his ring before assuming a decode gap. -
Vendor divergences still open (verified from the decompile): the vendor can read monitor state (
queryTimingHeartRateState), so the engine's "no read-back → forceALL_ON_DEFAULTevery connect" premise is false — match the vendor (query state / apply saved config). And the vendor sends spot measures on a priority path (insertNotificationMessage) distinct from config/history (insertBleMessage). -
The R100 (issue #58) is a second CRP ring, and a more talkative one than the R11. White-label, ships with the same "Da Rings" app, firmware
MOY-R2E3-*, catalogued asWearableModel.R100. It advertises a usable name (R100/R100_<hex>) so it matches at scan instead of relying on the post-connectfddare-route. What its capture settles: temperature history decodes (above), all-day HR/HRV return real frames, all-day SpO2 returns almost entirely empty ones (2 frames with data against 44 empty — the ring records little, the decode is fine), and stress is unanswered on both its history and state opcodes. When a CRP question needs a non-empty capture, this ring is now the better source. -
A CRP spot measurement ends on one result, and it does not go through
HRSampleWindow(issue #88). The ring answersg1/cmd9(HR) org1/cmd11(SpO₂) with a single frame and then goes quiet. On a second R11 (firmwareMOY-R2Z3-2.2.1, not zaggash'sMOY-R1K3-2.1.6) HR arrived 15–17 s after the start:Time Dir Frame Meaning 20:28:03.187 TX fdda1007010901start HR 20:28:19.932 RX fdda100701094872 bpm 20:28:28.415 TX fdda1007010900stop HR HRSampleWindowwants six samples and calls 8 s of silence lost contact, so it threw that result away.CRPSpotControllerruns CRP spot HR/SpO₂ instead. What it relies on:- Every cmd-9/11 frame is terminal, an empty one included. The vendor dispatcher
g1/a.chandsframe[6..]toe1/f.b/e1/d.bwith no length check, both return 0 for an empty payload, and the app layer (v3/a.a,f4/b.a) turns 0 into "no value" and ends the measurement. (JADX flagsg1/a.cwith a type-inference warning;-m simpleand-m fallbackshow the same control flow.) - Its deadline starts when it sees the start command's outgoing
RawPacketon the bus. The bus does not replay, so the listener must be subscribed before the write is enqueued (it is launchedUNDISPATCHED): on an idle queue the packet can be published before a normally dispatched coroutine runs, and the countdown never started. A dispatch timeout backs this up, so a start that is never seen leaving the queue still ends the measurement. Without either, a silent ring left the UI measuring forever. - CRP has no transaction id. A late result of the same kind that lands inside a later request is indistinguishable from that request's own answer. History frames never complete a request.
- The stored row is
sourceRaw = "spot_result", not"spot". It must stay out ofadoptRingsCopyfor the five-minute-grid reason in "The ring owns a spot reading it logged itself" below. - A rejected result is still a health frame.
CRPDecodernames an out-of-band vital resultRejectedVitalResultso the export masks it; decoded to nothing it would be loggedunknownand exported whole.
- Every cmd-9/11 frame is terminal, an empty one included. The vendor dispatcher
-
Whenever you touch CRP measure/sync/all-day behavior, hardware-validate with the ring owner (zaggash) — and for a "measure broken" report, first get a capture of several Measure presses with the ring snug and still, to separate a contact failure from a real code bug.
A sleep reply's day index counts back from the ring's sleep day, and that day starts at 8 PM. An
R11's first night was stored twice: correctly by a morning sync, then exactly one day earlier by an
evening one, at a time before the ring had been delivered. The vendor dates a group 2 / cmd 14
reply from the moment it syncs: t3/n.onHistorySleepChange passes new Date() to f4/e.a, whose
f4/e.e moves it to tomorrow when f4/e.h reads 20 <= HOUR_OF_DAY, and j4/h.b then subtracts
the day index. So from 20:00 day 0 is the night about to begin and last night is day 1.
CRPDecoder.decodeSleep counted back from the phone's date alone, so every sync after 8 PM filed
last night under the day before.
Two things follow, and CRPSleepDayIndexTest pins both:
- A record starting at or after 20:00 is the evening before the reply's day, even when the reply never crosses midnight. Without that, a reply holding only evening sleep (a doze at the desk) was anchored on the evening after the waking day, which is in the future at a morning sync.
- The constant is 20, not
TimeUtil.wakingDayLocal's 19. That one is iOS's key for grouping stored sessions by waking day; this one is the ring's own boundary, read from the vendor. Merging them would move the decoder off the vendor to match a persistence convention.
The damage is not limited to a ring's first night. The background sync runs about every
30 minutes, so most evenings include a sync after 20:00, and each one filed that morning's night
24 h early, on top of the night before. The next morning's re-sync restores the real night, but
upsertSleepSessionAtomic only replaces the time range a packet covers. So the copy's blocks
outside that range stay, and every night grows by whatever the following night covered beyond it.
On the reporter's database, every one of the 37 stray blocks sits inside a block of the next
waking day's record at exactly +24 h, with the same stage. Their recordStartAt is that record's
minus 24 h. Sunday read 382 minutes asleep against a real 302, because 80 came from Monday's night.
On the ring's first night there was no earlier night to land on, so the copy stood alone as a whole
night on a day before the ring arrived.
The decoder fix stops new copies. Copies already stored are left alone, on purpose. A one-time
cleanup (SleepDayEarlyCopies, #110, CRP-only after #119) was tried and backed out before any stable
release, after the reporter ran it on a longer-history database (#109, 2026-10-13):
- It removed copies but could not restore what they had overwritten. By the time a night's copy is old, the next evening's sync has usually replaced that night's real stages with the copy, so deleting the copy left Sep 27 empty and cut Sep 29 from 425 to 79 asleep minutes.
- It ran once, before a later re-sync exposed more copies. A copy on Oct 9 only became detectable after a sync restored Oct 10, after the cleanup had marked itself done.
Recovering that history needs a trusted earlier snapshot, which the app doesn't have. Don't reintroduce a destructive cleanup without one. Test builds 2.10.3 (68–72) and 2.10.2 (73) did run it, so their testers' databases may already show those holes.
No sleep query goes out within 5 minutes of 20:00 (CRPDecoder.nearSleepDayRollover). The ring
dates a reply by its own clock and the decoder by the phone's when the reply lands; straddling the
turnover they disagree by a day and recreate the copy, after the repair has already run.
Not covered: a copy older than the ring's ~week of history whose source night was itself overwritten by the next evening's sync no longer fits inside it, so the all-or-nothing match leaves it in place.
Read this before touching HRSampleWindow, SpotMeasurementGate, or RingSyncCoordinator's
measure legs.
A YCBT ring ends a spot measurement itself with 04 0e [mode, status] — bArr[0] is the same
mode byte 03 2f started with, bArr[1] is 1 success / 2 failed / anything else cancelled
(vendor BaseMeasureActivity.onDataResponse, decompiled-smarthealth/.../BaseMeasureActivity.java:259).
The vendor reads no value out of that frame; on success it calls syncData() and pulls the
reading from history. We decode it the same way: RingDecodedEvent.MeasurementComplete carries the
mode and the verdict and nothing else, and SpotMeasurementGate honours it by token so a
completion can only end the measurement it names.
What the Ale-Hop2211 captures in #59 established about how these rings actually behave. None of
it is safe to assume away:
- Warm-up is not the same as the cached echo.
HRSampleWindowdrops the first 5 s because the ring answers instantly with its last stored bpm. That ring sent nothing for 14 s, then spent ~12 s on a pre-converged plateau (47 47 47, 46 46 46) before stepping to the real rate (84 … 81) at ~26 s. A whole-window median picks the plateau every time: it is both the majority of the window and the most self-consistent thing in it. Never settle a median over everything collected. - Which settle rule a run gets is decided by whether the ring ended it
(
HRSampleWindow.settled(ringChoosesLastSample), wired to the ring's04 0esuccess verdict on this run, not to the family's ability to send one). A run that hits our ceiling without a04 0eis one the ring never finished, so it falls back to the consistency gate whatever the family. A ring that ends its own measurement logs the last plausible sample of the run (vendor bandHEART_RATE_VISIBLE_MIN..MAX= 40..220), so the app reports that. RC-3 feedback on #59 established it directly: three spot measurements captured with no stop command, each read back out of the ring's memory before any app touched it, stored value == last streamed sample 3/3 (65, 58, 72). It is a discriminating test here, unlike SpO2 where tail and last coincide — the rate is still climbing when the ring stops, so every tail-weighted rule lands below the ring's answer (94 against the ring's 93 on rc5, and up to 18 bpm out on those captures). Disagreeing with the ring is not a better number, it is a second number: the ring's copy arrives on the next sync and ours yields to it (issue #60). A ring with no completion signal keeps the tail rule, because nothing chose its last sample — the leg just ran out of window. Don't widen the last-sample rule to every family; that is the same over-generalisation rc5 had to correct for the ring-copy rule. - The ring's stored sample is not a converged reading, and that is not ours to fix. It stops while the value is still rising (34.2 s, 49.2 s, 34.2 s across those three runs), so "which sample did the firmware choose" and "is that sample any good" have different answers and only the first is the app's. The reporter raised this himself and argued against correcting for it: inventing a better number app-side would disagree with the row the ring re-supplies.
- These rings stream in bursts. Three samples about a second apart, then 4-6 s of silence. The contact-lost gap was 3 s, so it fired mid-measurement on a ring that was working perfectly and aborted the leg before the sensor had converged at all. It is 8 s now. Size this against the burstiest cadence in a capture, never against the average one.
- SpO2 is not heart rate, and the HR rules must not be copied onto it. RC-1 feedback on #59
included an instrumented SpO2 capture from the same ring, and every property differs: samples
start at t+13 s, there is a 24 s silence in the middle (against HR's 4-6 s), the run lasts
50 s (against 35), and the values rise to a peak of 99 then decline to 94 rather than
converging. So: there is no cached echo to discard here, the HR contact-gap would abort it
outright if it were ever applied to this leg, and HR's tail rule would report the decline.
Spo2SampleWindowsettles on the last plausible sample (vendor band 70–100), because that is what the ring itself logs. Three sources agree (RC-2 feedback on #59): five captures read back against the ring's own history matched the last sample 5/5 (a median matched 4/5); the one run that collapsed 98 → 87 is stored by the ring as 87, so it was a bad measurement, not a rule failure; and the vendor app (BloodOxygenMeasureActivity.onEvent) never settles at all — it shows each frame and on04 0ere-reads the ring's history. Don't put a median or a tail rule back: anything cleverer than the ring disagrees with the row the ring will later re-supply. There is still no value-based early exit for this leg — the collapsing run's late burst changed the answer, so "a value in hand" is not "done"; only04 0e(or the ceiling) is. - A window ceiling is per family (
RingSyncEngine.spotHeartRateSeconds,spotSpo2Seconds). YCBT HR is 45 s because that ring self-terminates at ~35 s; YCBT SpO2 is 75 s because five captures put its04 0eat t+63.1 s (the default 60 s timed out just before it); everyone else keeps 30 s / 60 s. This is only safe because the leg ends on04 0e— raising the default for families that never send one would make every measurement visibly slower for nothing. 04 0esuccess is not an abort for BP and HRV. Those legs read no value out of the push (the vendor re-syncs history), and HRV has no live-value frame at all, so treating success as "stop polling" turned a measurement the ring called successful into a failure. Only the ring's failure verdict ends them early (pollForValue's abort predicate tests== false).
Collecting a whole run is gated on the ring saying when it is done
(RingSyncEngine.signalsMeasurementCompletion, true only for YCBT). Don't widen it: a leg that
waits for a completion signal no family sends just idles out its window, and the CRP R11 answers a
spot SpO2 with one value after ~48 s of silence and nothing further — waiting past it would turn a
working measurement into a minute-long stare at a progress bar. Families without the signal keep
"first plausible value wins" for SpO2. CRP is outside both rules: its spot legs are run by CRPSpotController and end on the
ring's one result frame (see the R11 section above).
A spot measurement's output is one reading, not a stream. While one is settling, the
coordinator closes a gate on that kind's live samples and publishes the settled value once,
spot = true (which the closed gate lets through). The gate is a bus event (PulseEvent.LiveSampleGate), not a shared
flag: EventPersistenceSubscriber collects behind the ring on its own dispatcher, so a flag read at
write time let every sample already queued in the bus through the moment it flipped — the event is
ordered against the samples it governs. Before any of this, every converging PPG estimate was stored
as its own heart-rate row stamped with the moment it arrived — a failed measurement left a whole
train of readings that were never the user's heart rate (this is what prompted issue #60). A live
workout is the opposite case: there the stream is the data, so a measurement that runs during
one neither closes the gate nor publishes a second row for a reading the stream already stored.
The gate reopens when the ring stops sending, not when the leg ends (LiveGateReopen). Told to
stop, a Colmi ring sends one more 0x69 reading and only then its 0x6A acknowledgement — in
QRing's captures and ours alike. Reopening as the leg ended put that trailing reading on an open
gate, so every Colmi HR and SpO₂ spot measurement stored two rows a few hundred ms apart (HR
85 + 86, SpO₂ 98 + 98 on a Ring 2 Pro). The leg now arms the reopen before sending its stop, and
the ring's acknowledgement (PulseEvent.RealtimeStreamStopped) pays it, with a 2 s timeout in case
it never comes. The wait is opt-in per stop: only when the engine reports that the stop it just sent
will be acknowledged (RingSyncEngine.stopAwaitsAck, Colmi only). Every other family — and a Colmi
stop that sent nothing — reopens at once, because waiting there would drop the first ~2 s of a
workout's samples after every leg. Don't move the reopen back to the end of the leg to "simplify"
it, and don't make the timeout unconditional.
A spot HR measurement is refused while a workout is running. The live-sample gate is one switch
per kind, so whichever of the two closed it decides whether the other's samples are stored, and the
leg sampled that decision once at the start. Running both meant either the workout's samples were
dropped for the length of the leg, or — if the workout started inside it — the leg's converging
samples were stored as workout rows and its settled value never published. A workout starting mid-leg
now aborts the leg, and the gate is reopened unconditionally in the finally because the leg is what
closed it; leaving it closed would silently drop that workout's samples for the rest of the session.
The workout screen is already showing live bpm, so refusing costs nothing. Streamed HRV / stress /
temperature (measureVital) is refused and aborted the same way, for a blunter reason: 0x69 <type>
takes over the ring's one realtime engine, so the workout would get no bpm at all. No unit test:
RingSyncCoordinator needs a BLE client and has no harness.
YCBTHistoryTransfer.handleTerminal used to require the terminal block's packet count to equal the
one the header declared. The ring contradicts its own estimate one frame later, so that check threw
away whole record types. On the reporter's Ale-Hop2211 (COLMI_SMART_HEALTH, firmware 2.04) the
05 09 header declared 5 packets for 840 bytes and the ring then sent 6 — it packs whole
20-byte records into each frame (7 × 20 = 140) instead of filling it, so the header's
ceil(bytes / frame) estimate is one short. Bytes and CRC were correct on every transfer; we
nacked, retried once, and skipped the type.
What that cost: the composite 05 18 record is the only source of SpO₂ history on this family —
the dedicated 05 1a query was sent ten times in one session and never answered once — so hourly
SpO₂ vanished while HR survived from 05 15. Respiratory rate, HRV, BP, temperature and blood sugar
ride in the same record. It only bites above one packet, which is why the record imported while the
day was young and stopped once it grew, and why it looked like a regression introduced by a release
that had touched nothing nearby.
The vendor doesn't check the count either: at Sync_Block_Verify (128) DataUnpack reads the two
count bytes into locals it never compares, sizes its buffer from the terminal's length, and
accepts on crc16_compute(...) == crc alone. So: size the buffer from the header if you like, but
validate against the terminal's byte count and the CRC. The CRC is the integrity check; a packet
count is an estimate, and this firmware proves it can be wrong.
The general lesson, because this shape recurs here. A silent "reject and skip" on a
self-consistency check is much harder to see than a decode bug: the frames arrive, the log shows
them as unknown (which is what every accumulating history frame looks like — 427 sleep frames in
the same export say unknown and sleep imports fine), and nothing fails anywhere. When a whole
metric is missing but its neighbours are not, check what the transfer did with the block before
suspecting the parser.
A YCBT ring closes a sleep session when the wearer gets up and opens a new one when they settle,
so one night can be two af fa records minutes apart (00:12–03:18 and 03:21–07:24 in the report).
SleepSegmentation merges those into one stored row, which is right. What was wrong: a complete
record used to be treated as authoritative for every block of every row it overlapped, so on the
next sync pass the second record landed on the merged row and wiped the first record's three hours
with its own stale copy — the night read 4 h 06. completeSessionSurvivors now retires only the
contiguous run of blocks the packet's interval sits in (overlapping blocks, plus anything abutting
end-to-start with no gap, in both directions). A shortened re-send still retires its own stale head
or tail; a neighbouring session across even a one-minute gap is untouched. The vendor
(DataUnpack case 4 → one Sleep row per af fa block, queryByYearToDay returns a list) never
lets one record displace another. YCBTHealthRecords.sleep also resynchronises on the af fa magic
now, so a record with a wrong declared length can't swallow the sessions after it.
A session's totalMinutes is time asleep, not the span from its start to its end. Merging is
what made the two diverge: one row covering both records also covers the minutes between them, so
the reporter's night read 8 h 10 (23:51–08:02) against the 268 + 140 minutes its two records
declared, 6 h 48. The vendor draws the same distinction and the reporter found where —
SleepActivity:695 builds each history entry as deepSleepTotal + lightSleepTotal + remTotal,
carries wakeDuration separately, and takes startTime from the first record of the day and
endTime from the last, never conflating the two. asleepMinutes(blocks) (SleepInsights.kt) is
the single definition; spanMinutes is the other number. Three things to keep straight:
- It is "every stage except AWAKE", not "DEEP + LIGHT + REM". Same sum on a ring that labels
its stages (YCBT's sleep tag 4 is AWAKE), but
SleepStage.UNKNOWNis theelsebranch of every decoder here — an unrecognised stage byte inside a sleep record. Naming three stages would drop minutes that were slept, and could zero a night on a ring we decode only partly. - Anything positioning against wall-clock time scales by
spanMinutes. The hypnogram's x axis did usetotalMinutesand would silently compress and mislabel every tick otherwise. - Stored rows were repaired once (
DataRepairs.repairSleepDurationsIfNeeded, prefs keysleepAsleepMinutesRepair.v1), because ring history only reaches back about a week and a re-sync would leave older nights reading the old way forever. It recomputes from each session's own blocks and skips a session with none rather than zeroing it —byDayandearliestDayboth filtertotalMinutes > 0, so a zero hides the night.
A zero-length segment must not shadow a real one. The vendor de-duplicates segments on
sleepStartTime (DataUnpack case 4 keeps the first it sees) and the ring emits zero-length
segments, so a zero-length segment sharing a start with a real one used to take its place and drop
it. All four duplicate starts in the reporter's thirteen-record night dump are exactly that — a
zero-length LIGHT ahead of a real 76–105 s segment — and since placeStages reads an unclaimed
minute as wake, the dropped minutes surfaced as wake instead. The vendor has the same de-duplication
and does not care, because its headline comes from the header's own totals rather than from the
segment array; ours is counted off the timeline, so it does. Zero-length segments are skipped before
the de-duplication now.
The record's header declares its own time asleep, and it agrees with the timeline. When
deepSleepCount (+12) reads 0xffff, the three following u16s are seconds, in the order
rapidEyeMovementTotal (+14), deepSleepTotal (+16), lightSleepTotal (+18) — REM first, not
deep — and wakeDuration is the summed length of the 0xf4 segments (DataUnpack.java:1736-1805).
Otherwise +14 is lightSleepCount, deep/light are minutes×60, and REM is absent. On the reporter's
dump deepSleepCount is 0xffff on 13/13 records and deep+light+rem agrees with the timeline we
count to within a minute on 12 of 13. So the counted timeline is sound; if a headline ever needs to
be independent of placement and rounding, the declared totals are there. Note the record length at
+2 is bytes, not minutes — it reads plausibly as a minute count (244, 164, 268, 140) and was
misread that way for several rounds of this issue.
A complete record retires only what its interval overlaps — abutting blocks are left alone. The
rule used to grow its run across any block meeting it end-to-start, so that a shortened re-send could
retire its own stale tail. But a block carries no record identity — sessionId is the merged row,
shared by every record of the night — so "my stale tail" and "the neighbouring record" are the same
shape from the same side, and two records meeting with no gap read as one run: the second wiped the
first. The reporter's ring closes one record and opens the next 33 seconds later, so whether the two
round to the same minute is a coin toss, and losing it costs a whole session. The trade is a stale
tail surviving a genuine shortening, which is minutes rather than hours and rarer than it was now
that a re-send reproduces the record's declared bounds instead of a drifted end.
The block now carries its record's start, so the identity that was missing above exists
(SleepStageBlockEntity.recordStartAt, v28, stamped by buildStageBlocks — see #68 below). It is
the fix this section predicted for the stale-tail trade, and completeSessionSurvivors can take it
whenever the tail actually bites.
Showing a split night's individual records was the fair ask left open by #63. The card itself is easy; the boundary is the whole problem, and it is the third time this one gap has cost a feature.
This firmware reopens a record roughly a minute after closing one — 33 seconds on the #63
capture, 05:57 → 05:58 on the #68 reporter's Sept 9 — and blocks within one record are rounded
onto the same minute grid, so an ordinary rounding seam between two blocks of one record is the same
width as a genuine record boundary. That is not a threshold problem, it is the absence of the
information: sessionId names the merged row, shared by every record of the night, so from stored
data alone "next record" and "next block" are indistinguishable. sleepRecordRuns shipped with
minGapMinutes = 2 and merged a genuinely split night (no card at all); 1 minute would have grown a
spurious second record on every unsplit night instead. Both answers are wrong because the question
was unanswerable.
So the import stamps it. buildStageBlocks is the one place that knows — it is handed the record's
declared start — and sleepRecordRuns groups by recordStartAt rather than measuring gaps. The gap
rule survives only as the fallback for rows written before the column, and it is all-or-nothing
per night: one stamped record beside a legacy block would read as two records whatever the truth.
SleepRecordRunsTest keeps the discriminating pair — the same one-minute gap asserted as a boundary
in one test and as a seam in the other — because that pair is what no threshold can satisfy and what
a future "simplify this to a gap check" would break.
The general lesson: when a merge destroys provenance, recover it at the point of the merge, not at the point of display. Three separate fixes here tried to re-derive a record boundary downstream.
The QRing app never touches the realtime-HR commands during an activity. SportRunningActivity
sends PhoneSportReq.getSportStatus(1, sportType) = 0x77 01 <type> on entry and consumes the
ring's own unsolicited 0x78 telemetry (DeviceNotifyRsp: [dataType][status][durMin×2][bpm] [steps×3][metres×3][cal×3] after the opcode) until 0x77 04. No timer, no keepalive — the ring
drives the cadence, which is the near-constant LED and ~10 s readings the reporter sees there.
ColmiSyncEngine.startWorkoutHeartRate does the same. Rules that matter:
- Don't re-send the start mid-workout. The coordinator restarts the stream after every spot measure; on this path that must be a no-op or the ring's own sport record resets.
- Silence gets one resume (
0x77 03), then the session is given up for the plain HR stream (sportWatchdogTick), as it is when the ring rejects0x77outright (the error-flag reply). Those two are sticky for the engine's life (sportRejected), like the0x1Erefusal — the ring has shown it will not run a sport session at all. A0x78status 3 is not one of them: it is the vendor's own "this session finished" push, which its running screen answers by closing the screen. It ends the session for the rest of that workout (sportEndedByRing) and the next workout starts a fresh one; making it sticky would let one ring-side timeout cost every later workout the protocol this issue exists to add. The old0x1E→0x69path is unchanged underneath and is what a fallback lands on. 0x77on the command channel isPhoneSportReq; the same number as a big-data action is interval temperature on the other characteristic. They are unrelated.- Every
0x78frame decodes to aSportTelemetryevent first (kindsport_telemetry, in the redactor's masked set), with the bpm as a separateHeartRateSampleonly when plausible. A warm-up frame has bpm 0 but still carries live steps, distance and calories; returning nothing for it made itunknownand exported it in clear — the decode-gap-becomes-privacy-gap failure the diagnostics section below warns about. - Untested on hardware as of this note: the reporter (issue #64, Colmi R09) has the ring.
History measurements are keyed history:<kind>:<timestamp> and written with upsert, on purpose:
re-syncing a day the ring still holds must update the same row rather than duplicate it (see the
measurement-duplicate bug). That idempotence is also what would undo a deletion — delete the row and
the next sync writes it straight back, with nothing failing anywhere.
So measurement_deletions (v24) remembers the deletion, EventPersistenceSubscriber.upsertUnlessDeleted
is the single gate every deterministic-id write goes through, and MeasurementDeletion owns the two
rules callers must not have to remember: tombstone anything regenerable, and delete a blood-pressure
reading as both of its rows. A live reading's id is a fresh UUID nothing regenerates, so it is
deleted without a tombstone — MeasurementDeletionDao.record applies that split, and
MeasurementDeletionTest guards the id-prefix agreement that makes it work.
Tombstones ride in the archive (PulseArchive.measurementDeletions) because a restore wipes every
table first; without them a backup round trip would forget the deletions while the ring still holds
the days behind them.
The ring owns a spot reading it logged itself. RC-1's doubled rows (two HR rows per
measurement, same minute, 79/82) are the ring logging the spot reading into its own history —
confirmed on RC-2 by reading five SpO2 runs back out of the ring's memory at the exact times they
were taken — which a later history sync imports as a history:<kind>:<ts> row next to the UUID row
we stored for our settled value. Our row is stored with sourceRaw = "spot", and
EventPersistenceSubscriber.adoptRingsCopy deletes it when a history sample of the same kind lands
within 90 s: the ring's row wins because it is the one that regenerates on every sync (so it is the
one a tombstone can hold down).
Only a reading the ring itself completed may take part, and the gate is at write time. A row is
marked "spot" only when the ring reported that run's success (04 0e, carried on the event as
ringWillLogIt, which RingSyncCoordinator sets from the run's own verdict — a ring that ends a
measurement with its own verdict is one whose vendor app reads the value back out of history).
Everything else stores a plain "live" row exactly as before, with nothing that could delete it.
This is per run, not per family: a YCBT run that times out at our ceiling with no 04 0e was
never logged by the ring, and marking it "spot" would let the next sync delete it in favour of an
unrelated all-day grid sample. A history sample the user has tombstoned adopts nothing either — it
is re-sent on every sync, and letting it retire spot rows would delete a retaken reading each time. Do not widen this to all families: CRP and Colmi record all-day
HR/SpO2 on a five-minute grid, so with a ±90 s match window most spot measurements would have an
unrelated grid sample within reach and the user's own reading would be deleted in favour of it.
A deleted spot row needs a range tombstone, because its id is a UUID. The split above —
tombstone the regenerable ids, delete the UUIDs outright — is right for a "live" row and wrong for
a "spot" one: a "spot" row exists precisely because the ring logged that measurement itself and
will hand it back under a history: id on the next sync. Tombstoning by id alone let the ring's copy
walk straight in, so the reading came back and had to be deleted twice. The ring stamps its log to
the minute rather than to our settled instant, so the tombstone cannot name the id it must suppress:
MeasurementDeletionDao.record writes a spot:<kind>:<ts> row instead and isSpotDeleted matches
it the way adoptRingsCopy matches the pair it reconciles — same kind, within ±90 s. A measurement
retaken inside that window inherits the suppression: it is stored and displayed (it is our own row,
not a history write) but never adopts the ring's copy. That is the same ±90 s ambiguity
adoptRingsCopy already carries, and it fails towards keeping a reading the user asked for.
Known limit, worth stating when a user asks: a reading already exported to Health Connect stays there. The export doesn't retain HC record ids, so there is nothing to delete against.
The backup archive is the only way data reaches a new phone: android:allowBackup is off, so
nothing in SharedPreferences moves with Android's own backup. Room tables go through
DataArchiveService; preferences go through ArchivedSettings, an allowlist of files.
Drinks is why this exists. Its entries were archived, but its on/off switch was a preference that
defaults to off, so after a phone change every drinks surface hid itself and the history looked
lost, and the plan, start date and AUDIT-C result were gone. DrinkPrefs.adoptRestoredHistory
repairs phones already restored that way (entries present, Drinks never switched on there).
- A new preference that holds what the user entered or chose about their data (a switch that
decides whether data shows, a plan, a log kept as JSON) goes on the
ArchivedSettingsallowlist in the same change. Device state stays off it: ring pairing, Health Connect grants and watermarks, notification scheduling, algorithm and scoring versions. - The encrypted store
pulseloop_securerides by key, not by file (SECURE_KEYS): it mixes the user's choices with this phone's state. The coach's whole setup is carried at the owner's request, API keys included (every provider's key and model, and the custom API's address, key and model), plus calibration, physiology, units and check-in hours. The archive is plain JSON, so the Backup screen warns that the file exposes those keys. Don't drop the keys to make the file "safer" without asking: losing the coach setup on a phone change is what was reported. - The EPDS answers are deliberately not carried (
postpartum'sepdskey; see postpartum mode). The life stage is. body_measurementsandfindingsare deliberately not in the archive either: Health Connect re-imports the first, and the second is recomputed.
ActivityBucketDeletion is the tombstone rule applied to intraday step blocks, and it has one more
thing to get right than MeasurementDeletion does. A tombstone guards the history path; today's
number does not come from the history path. The ring also pushes PulseEvent.ActivityUpdate
carrying its own cumulative count for the day — seconds apart, and again on every reconnect — and
EventPersistenceSubscriber.upsertActivityDaily ratchets the day up against it with maxOf. That
counter still includes the deleted block, so a restated 7,000 went back to 8,000 on the next frame:
the delete looked like it worked and then silently undid itself, which is the exact failure the
restate-without-the-ratchet rule exists to prevent.
So the day remembers what it removed. ActivityDailyEntity.deletedSteps / deletedDistanceMeters
(v27) are subtracted from every later cumulative reading before the ratchet
(ActivityBucketDeletion.ratchetAgainstRing, which lives with the deletion rules rather than in the
write path — a reader looking at the ratchet has no reason to suspect a deletion changed what the
ring's counter means). They ride the archive for the same reason the measurement tombstones do.
This is also why the feature is only offered on today: it is the only day whose counter is still
moving.
Calories are dropped, not corrected. A bucket carries steps and distance and no calorie field,
so there is nothing to subtract from the ring's own daily figure — and that figure demonstrably
counted the block the user removed. The day's calories is cleared instead, which makes
DailyCalorieEstimator.deviceReportedCalories fall through to the app's own estimate, recomputed
from the surviving buckets at deletion time rather than at the next completed sync. An estimate
consistent with the restated day beats a device figure known to be wrong. activeMinutes is not
touched: it is credited by ActivityRollup from workouts, not from step buckets.
DerivedStress computes a stress figure from HRV for rings whose hardware never reports one — the
R100 answers neither the stress history query nor its monitor-state read-back (22 sends, 0 replies,
while every other state query on that ring answered), so stress there is absent rather than switched
off. The app advertised it anyway, because a capability list is a static per-family constant and not
something an individual ring confirmed, and the user got a card that could never fill.
The rule that matters more than the formula: it is labelled wherever it is shown. The card reads
"Estimated from HRV — your ring doesn't measure stress", and VitalsState.stressIsDerived carries
the fact so no future surface can render it as a measurement by accident. A derived figure presented
as measured would be worse than the empty card it replaces — a user comparing it against the vendor
app's number is entitled to know which of the two they are looking at.
It is scored against that user's own recent HRV, not a population: HRV varies several-fold between individuals, so an absolute cutoff labels whole people permanently stressed or permanently calm. Median and median-absolute-deviation rather than mean and standard deviation, because ring HRV history is full of obvious outliers and one of them must not redefine the scale. It returns null below twelve baseline readings rather than a default, for the same reason the battery estimate in #65 refuses to answer: an unearned number on a health screen is read as a measurement.
Derived stress only fills in where the ring returned no stress at all. It never overwrites or blends with hardware readings.
"No stress at all" is a question about the ring, so ask it of the whole history. Gating on the
24 h chart window instead meant an empty window decided it, and windows go empty for ordinary
reasons — the monitor switched off for a day, a ring re-paired this morning, a quiet night. A ring
that does measure stress then showed a derived number captioned "your ring doesn't measure stress",
which is a false statement about that user's hardware. The gate is
measurementDao().hasReal(STRESS).
Labelled wherever it is shown means the chart too. The figure reaches three surfaces — the
Vitals card, the Today tile, and the vitals/stress detail chart — and the detail screen builds its
own series straight from Room rather than from VitalsState, so it needs the derivation wired in
separately (VitalDetailViewModel.derivedStressIn) and carries DetailState.isDerived into the
same amber disclaimer card BP and glucose use. Two related traps: a derived score has no "0 means
nothing measured" sentinel, so the card's >= 10 floor must not be applied to it (a genuinely calm
day scores below 10), and the scores skip the first readings for want of a baseline — so they
cannot be zipped positionally onto the HRV series. DerivedStress.scored returns each score with
the index of the reading behind it for exactly that reason.
DiagnosticsRedactor.maskPacketHex masks a health frame's payload but keeps the leading bytes that
say which record it is — 6 for CRP (FD DA 10 len group cmd), 4 for YCBT, 1 elsewhere. Masking
from byte 1 made every health frame in a report indistinguishable, which is why issue #58's capture
could not answer whether an all-day SpO₂ reply carried samples. Those header bytes are the same ones
the app writes when it asks for the record, and outbound queries are exported unmasked, so keeping
them costs no privacy.
The inverse failure is worth remembering too: CRP temperature frames were exported with their
values intact, because an undecoded frame fell through to command_ack, which isn't in
HEALTH_KINDS. A decode gap silently became a privacy gap. When you add a decoder for a frame that
carries physiological values, check that its decodedKind is one the redactor masks.
The export carries no database rows, and that is deliberate — don't add them, and don't ask a
reporter for stored-row detail through it. DiagnosticsExporter emits app info, device info,
logs, raw packets, crashes and logcat, and nothing else. Issue #74's "Next" section asked a reporter
for "the timestamps of the heart-rate rows stored around that minute, and whether they carry the
spot flag" — a question the format cannot answer, so the ask was made twice and answered neither
time. The reporter (@Albabit, #74) gave the reason the section should stay absent: a diagnostics
file people paste into public issues is not where health readings should end up. That is the same
principle maskPacketHex already enforces one layer down, so a measurements section would undo
deliberately, in clear, exactly what the masking exists to prevent. When you need to know what the
app stored, ask what the user sees on screen — for "is the user shown a bad reading?" that is also
the better evidence, since it answers the question the issue is actually about.
The header length must come from the packet's own family, and a half-assembled frame has no header at all. Two further shapes of the same failure, fixed together:
- Masking used to use the connected ring's family for every stored packet, so a report exported
after switching rings masked the old family's frames with the wrong header length — and CRP's is the
longest, so a Colmi frame masked as CRP kept five bytes of samples.
raw_packets.deviceTypeRaw(v25) records the family at capture time (PulseEvent.RawPacket.deviceType), and a row from before it existed masks from byte 1: less useful, never wrong in the direction that leaks. - A CRP reply spanning several notifications only decodes when its last chunk lands, so every chunk
before that reached the log as
unknown— which is deliberately exported whole, because control and pairing frames decode to nothing and are what most connection reports are taken for. Half an all-day health reply left in clear that way.RingDecodedEvent.FramePendingnames a chunk instead, and the two cases mask differently:frame_startkeeps its family's header (it is there, and it is what identifies the reply),frame_chunkkeeps byte 0 and nothing else, because the middle of a frame is payload from byte 0 on.
Capture is application-scoped and bounded — keep it that way. DiagnosticsSubscriber is started
once from PulseLoopApplication and is the only writer of raw_packets and wearable_logs. For a
long time it was never started at all: the Debug console showed "0 packets captured" beside 778
stored CRP packets, and Ring Events lived in composable state that vanished on navigation. Three
things to preserve:
- Nothing in the UI owns capture. The Debug screen reads Room through
DiagnosticsViewModeland acts on the app's ownRingBLEClient/RingSyncCoordinator. A screen that builds its own client is talking to a second, unconnected ring stack. - Both tables are capped (
DiagnosticsRetention: 1,000 packets, 2,000 log rows, trimmed every 50 inserts so a DELETE stays off the per-packet path; up to 49 over between trims). They ride in the data archive, and a verbose driver logs every attempt and every reply, so an unbounded table grows for the life of the install. - Verbose transport logging is a driver opt-in (
WearableDriver.verboseTransportDiagnostics, on for CRP only), and its log lines carry the frame's route (diagnosticRoute) — never its payload. An undecoded frame is still loggedunknownand exported whole, per the section above.
A gap is a waking only if it is real time, and the Bedtime window outranks the hour rule (issues #111, #105)
- Sub-minute holes are seams.
YCBTHealthRecords.placeStagescloses any hole shorter than 60 s of real time between a record's segments, and between them and the record's own bounds. The ring leaves a one-second hole between segments, and rounding each end to the minute grid independently could still leave a whole AWAKE minute in it (315.48 → 315, 315.5 → 316). - Every gap between two records is a waking, at least one minute (
betweenRecordAwakeMinutes). The old rule dropped gaps under 2 minutes as the #63 "reopen seam". The #111 reporter checked all 19 gaps on their YCBT ring since late August: the shortest were 52, 79 and 88 s, the 52 and 88 s ones were get-ups they had logged, and none was a reopen without waking. The ring starts a record on a whole minute, so a short gap's length depends on where the last one ended; no threshold separates seams from get-ups. The gap is rounded, not truncated (a stored end is its start plus whole minutes, ±30 s from the ring's; truncation lost a 2m07 waking). Back-to-back records (gap 0, e.g. Jring's 15-minute packets) count nothing. - The hypnogram draws the counted gaps (
hypnogramBlocks), display-only. Never feed those blocks toawakeMinutes, which counts the gaps itself. - An hour-plus gap inside the wearer's Bedtime window stays one night (
SleepGapBridge). Off unless the schedule or Bedtime tracking is on — the two are independent since #126; Bedtime windows decide when the night has any, else the clock window if the schedule is on. The sync's reconcile andSleepRecordDeletion's restate must segment with the same bridge, or a record delete would split a night the next sync merges back.
Editing (#82) can extend a record over time the ring missed, not only shorten it. The added minutes
are stored as SleepStage.ADDED blocks — not UNKNOWN, which is a stage byte the ring did
record and we can't read.
- In time asleep, out of everything that judges stages.
asleepMinutesalready admits them (it excludes only AWAKE). Every score or stage share usesmeasuredAsleepMinutes/ dropsaddedMinutes:sleepStageScoreinreconcileWakingDayandSleepRecordDeletion.restateSession, andSleepScore.calculate. Health Connect getsSTAGE_TYPE_SLEEPING. The hypnogram draws them as a hatched band, not a lane. - They carry the ring record's
recordStartAt, sosleepRecordRunskeeps them in that record and the covered gap stops counting as a between-record waking (#81) with no special case. - One function maps a record through an edit:
editedRecordBlocks(SleepRecordExtension.kt).SleepRecordDeletion.editand the import's edit gate both call it, so a re-sync writes back the edit's blocks with the samestartAts. It ignores existing ADDED blocks and re-derives them from the bounds, and snaps the bounds inwards onto the record's own minute grid. Don't hand-build ADDED blocks anywhere else. - Limits (
recordEditLimits): back to the previous record's end, forward to the next record's start, otherwise 2 h past the ring's own bounds, never across the 7 PM waking-day turnover, and a record must keep one measured minute. At import, a stored extension is also clamped clear of any other stored record, so the ring's measurement always beats an extension. - Known divergence: the edit path only sees stored blocks. Re-extending over minutes an earlier edit trimmed off makes them ADDED until the next sync, which restores the ring's real stages there.
RingBLEClient, RingSyncCoordinator, EventPersistenceSubscriber and the other app-lifetime
services live in AppServices, one set per process. Never remember { … } one in a composable.
MainActivity declares no android:configChanges, so the Activity — and PulseLoopApp's whole
composition with it — is rebuilt on any configuration change: a dark-theme switch (Pixel's Bedtime
mode does one overnight), locale, font scale, rotation. When these were remembered there, every
rebuild made a second RingBLEClient. The first was never destroyed and kept both the ring's GATT
link and processConnectionOwner, so the new one could only log "Connection skipped: another
PulseLoop BLE client owns GATT" every second and show Disconnected over a ring that was still
connected. That matches #113's log (Ale-Hop YCBT ring, process up five days), though the
recreation itself wasn't captured. Each rebuild also put another persistence subscriber and sync
coordinator on the event bus, so every frame was persisted and handled twice.
AppServices.get(context)builds the set from the application context, so none of it pins an Activity.- The one-shot startup in
PulseLoopApp(callback wiring,start()s, the stale-state reset, the auto-reconnect) runs for the process's first composition only (claimStartup()). Re-running the stale-state reset would write DISCONNECTED over a live link. - A recreated Activity's first
ON_STARTis not the startup's, so it does runreconnectIfNeeded().
Read this before touching health/accuracy/, the export's held-back records, or anything that
reads AccuracyCorrections. Full design and the "As built" notes: docs/accuracy-check-plan.md.
The feature compares the ring with another device's Health Connect records for a few days, holds back the duplicate exports meanwhile, and can correct a consistent bias. Each rule below is there because breaking it fails silently:
- Every reference read filters on
DataOrigin. Without it PulseLoop's own earlier exports, or a third app re-syncing them, get compared with the ring and the report reads "perfect agreement". A bridge app (Health Sync) can still echo PulseLoop's export back under its own package, which no origin filter catches. That is what the HR echo check is for (an exact second-and-beat match on most samples); keep it running on every scoring pass. - The reference's readings are never stored.
accuracy_check_daysholds aggregates only. It would be the first foreign health data in the archive, and the diagnostics export rule (no readings in text people paste) applies to the "Copy summary" and "Share" texts too. - Held-back exports are filtered by data time, and the watermark still advances past them.
Don't "fix" this into holding the watermark. That is what makes Skip-these-days the default
with nothing to undo, and what keeps a window record that is updated later (a re-synced night)
out of Health Connect. Export-them-too rewinds watermarks under
HealthConnectExportWorker.passMutex; a rewind outside the mutex can be overtaken by a pass in flight. The pause set follows the reference device, never the ring's capability list, so a ring swap can't open a duplication gap. - Corrections are read-time only, and never reach Health Connect. Stored rows stay as the
ring sent them; it re-sends its history, so a rewritten row wouldn't stay rewritten anyway.
A derived figure that is also exported keeps a raw copy for the export:
estimatedActiveCalories(raw, exported) vsestimatedActiveCaloriesAdjusted(shown), andhrRestingBaseline(raw, exported) vsCorrections.baseline()at read time. The display helpers (DailyCalorieEstimator.displayActiveCalories/displayCalories) must not be used by an exporter. The caption saying figures are corrected lives in Settings, not on the tabs (owner's call: on Today it was a line shown on every visit for something set once). The Accuracy check row reads "Adjusting your ring" while corrections are on, and its screen lists them; the detail screens (vital detail, workout summary) keep theAdjustedCaption, and a widget tile itsadjustedflag. The coach reads through the corrections too and is told so; a workout's stored samples and summary stay raw because Health Connect and Strava get them. - Corrections belong to one ring (BLE address) and only exist after a consistent-bias verdict. Don't widen them to "Inconsistent": a slider that moves the average of an erratic ring is exactly the false fix the verdict exists to refuse. Sleep stages, onset/wake, HRV and calories are report-only on purpose: vendors compute them differently, so a difference there doesn't show which device is wrong.
- A day or night is compared only over the time both devices were on. A flat battery or a
charger mid-day used to pass the 500-step "worn" test and read as the other device
over-counting by everything after.
AccuracyComparison.offGapsfinds each device's off stretches (no data for over 90 minutes), but only for a device that logs heart rate at least every 75 minutes (judgeable); for one that doesn't, quiet and off look alike and it is taken as worn. A partly worn day's steps and distance are cut to the shared hours (the ring's 15-minute buckets against the reference's records); calories can't be cut, so such a day drops them; under 12 shared hours the day doesn't count. A night either device stopped inside drops sleep, resting HR and HRV. Heart rate and SpO₂ need nothing: they only pair readings taken minutes apart. The day notes say which device was off and from when. When a rule change like this one alters a finished check's result, bumpAccuracyScorer.SCORING_VERSION: finished checks otherwise keep their stored result forever, and an outdated one is re-scored once by itself (app launch, or opening the accuracy screen). Corrections already accepted are not touched by a re-score. - Reaching back over past days moves grading, never the pause (
historyFrom, v39). Grading starts atgradeFrom;startedAt, the day count and everypausedFromstay at the real start. Never before the ring was paired, for the same no-device-id reason as the next rule. - A running check ends the moment a different ring is paired (
AccuracyRingWatcher, started fromPulseLoopApplication). Ring rows carry no device id, so a later sweep could not split the two rings' data.
Read this before touching coach/ondevice/ or the ON_DEVICE provider. Design and as-built
notes: docs/on-device-model-and-mcp-plan.md, Part 1.
- No tools and no writes on this provider.
OnDeviceResponsesClientnever offers the request's tools and never returns a function call, so no write tool or confirm card can come from it;PulseLoopApp's flags also turn off web search and live measurements for it. A 1B model can't run the tool loop; don't wire it in "to see if it works". - Safety runs before the model.
OnDeviceSafety.routesends crisis, emergency and medicine/dose questions to fixed replies (CVV 188, SAMU 192, "ask your doctor or pharmacist") without loading the model. Those replies are written in the router, not throughtr(): no voice catalog may rewrite them. New keywords go in both languages, already normalized, with a test. - The reply is always a complete
coach_response. The client wraps the model's plain text (coachResponseJson) soparseFinalaccepts it on the first try. Asking the 1B model to write JSON itself would spend repair rounds of slow generation and still fail. - Only the coach chat may use it. Any other
text.format(meal estimate, lab report, summary) is refused: a small model must not read a lab report or estimate a meal. - The model is never in git, the APK or the backup. It is downloaded on request, kept in
noBackupFilesDir, and re-downloadable; the data archive must not pick it up. Only the provider choice (coach_provider_mode) rides inArchivedSettings. - Every download is SHA-256 checked against the
.sha256published beside it on the pre-release, and is Wi-Fi only by default (setAllowedOverMetered(false)); mobile data is the user's explicit choice. - Keep
MAX_TOKENSat the figure the file is proven with (1280). A prompt past the window crashes natively, which is whyOnDevicePrompt.fitmeasures with the model's own tokenizer.
Read this before touching health/source/ or the export's exclusions. Full design:
docs/health-connect-source.md.
A user without a PulseLoop ring can pick another device's app (Oura, Samsung Health, Fitbit) and PulseLoop imports it from Health Connect into the ring's own tables. Three rules hold it together, and each one fails silently if broken:
- Every read carries a
DataOriginfilter for the chosen package. Unfiltered, PulseLoop's own earlier exports come straight back in as "new" data, and two apps' steps sum into the same slot. - It goes through
EventPersistenceSubscriber.ingest, not around it. That path is what gives an import deterministic ids, the user's deletions, and the waking-day sleep reconcile. Writing rows directly would re-create every duplicate and resurrection bug the ring path already fixed. - While it is on, the export holds back every type, for all time (
exportExclusions, throughExportPause). Exporting would write the source app's own data back to Health Connect under PulseLoop's name. Don't narrow it to "the types the source writes": a type the source starts writing next month would then echo.
It is exclusive with a paired ring: a DeviceIdentified turns it off.
Read this before touching coach/anthropic/. AnthropicClient runs the coach on Claude with
the user's own key, translating the app's Responses-shaped request the way the other adapters do.
Each rule below is a 400 on every turn if broken:
- No sampling parameters, no prefill, no forced
tool_choice(API version2026-10-21, and the 5.5 models reject forced tool use). Effort goes inoutput_config.effort. - Claude's reply goes back unchanged, thinking blocks included: the 5.5 models tie thinking to
the conversation. The client stores each reply's whole
contentand replays it before its tool results; don't rebuild it from the parsed text. - Structured-output schemas go through
claudeSafeSchema:additionalProperties: falseon every object, no numeric, length or array-size constraints. A caller's own schema (meal estimate, lab report, summary) is sent the same way. - Web search isn't sent, and Settings hides its switch for Claude. Its key and model ride in the
backup with the other providers' keys (
ArchivedSettings.SECURE_KEYS).
Read this before touching mcp/ or ui/screens/McpSettingsUi.kt. Threat model:
docs/mcp-threat-model.md. Settings › Connected apps › AI tools on your network runs an MCP
server on the phone (port 8765, POST /mcp) so the user's own Claude Desktop or Cursor can read
their data. Each rule fails silently if broken:
- The tools are an explicit allowlist (
McpCoachTools.ALLOWLIST), never "whatever the registry holds with writes off":ToolRegistry's always-on set already contains writes (log_meal,set_goal,log_drink,save_food_preference,set_drink_plan) and a cache-writing network call (search_food_database). Add a name only after reading its implementation;McpAllowlistTestfails on a write name and on any coach tool nobody has classified. Calls run with all three flags off andcoordinator = null. - Never a tool for API keys, raw packets, diagnostics, lab-report PDFs or the EPDS answers.
summaryreusesCoachContextBuilder.buildbut drops labs, postpartum, drinks and the goal plan; keep it that way. - Refusal order is part of the design:
Originheader → 403, then token → 401, then path and method, all before a tool runs. Peers outside loopback/private/link-local/100.64/10/ULA are closed before a byte is read, and nothing binds a public address or a mobile-data interface. - Bounds stay: 4 connections, 15 s, 8 KB head, 256 KB body, no chunked bodies, no JSON-RPC batches, one tool call at a time.
- Tokens are shown once and stored as SHA-256 only, in
mcp_serverpreferences. That file, and the on/off switch in it, are device state and security material: never add them toArchivedSettings— a restore on a new phone must start off with nothing paired. - Off by default, foreground while on, and back by itself only when the user chose it. A
timed session:
START_NOT_STICKY, auto-off after the chosen hours (1/4/8; on Android 15+ the choices stop at 6 h and a stored 8 reads as 6,McpConfig.autoOffHours, because adataSyncservice gets about 6 h a day there and ends throughonTimeout— keep that override), and stopping for any reason clears the switch. Always on (McpPrefs.alwaysOn) is the user's explicit choice behind a confirm dialog: no auto-off,START_STICKY,specialUseforeground type on Android 14+ (no daily limit, may start at boot; needs thePROPERTY_SPECIAL_USE_FGS_SUBTYPEproperty), andMcpBootReceiverrestarts it after a reboot or an update only when it was left on. Only the user's Stop clearsenabledthen. Never make always on a default, never skip the dialog, and never hide the ongoing notification: it is how someone sees that their health data is reachable. The notification's tap stops it. - The
instructionssay it is not a diagnostic tool and the numbers are estimates — the same rule the coach follows. Keep them in step with the coach's prompt. - The protocol, HTTP, address and token code has no Android imports and is JVM-tested; keep new logic there rather than in the service.
The app speaks English and Brazilian Portuguese (Settings → Language, ui/i18n/L10n.kt). There
are no string resources for UI text: a composable writes Text(tr("Save")), and tr looks the
English up in assets/i18n/pt-BR.json, falling back to the English when there is no entry. So:
- New UI text: wrap it in
tr()and add the pt-BR entry to the catalog in the same change. An unwrapped string, or a wrapped one with no entry, silently stays English for Portuguese users. Rewording an English string orphans its translation the same way; update the key too. - Translate where text is shown, never where a value is defined. A literal that is also
compared (
zone.label == "High", awhenover labels) must stay English; wrap the display site instead (Text(tr(zone.label))).MetricThresholdsandHeartRateZoneslabels work this way. - Not inside an enum constructor or an object-level
val: those evaluate once, so a language change wouldn't show until the process restarts. Use a getter (val label get() = tr(en)). - Never date patterns or format keys.
tr("EEE d MMM")would let a translation break parsing. Dates already localise through the defaultLocale, whichL10nsets. - A string built by a template (
"Day $n") can't be a key. Split it into a translated part and the value, or leave it English. Many still are; templates and service-layer text (insights, notifications) are the known gaps. - The coach answers in the app's language through
L10n.coachInstruction(), appended to its prompts.
F*cking Health (Settings → Language) is English with attitude: AppLanguage.FUCKING_HEALTH_EN
reads assets/i18n/en-FH.json first and falls back to the plain English key, and Voice.FUNNY
gives the coach and its notifications the persona through L10n.coachInstruction().
- A voice rewrites only some strings, on purpose. A missing entry shows plain English, which is right for settings, units, metric names and anything technical.
- Safety text is never rewritten. Crisis lines, clinician/pharmacist advice, warnings,
disclaimers, pregnancy/postpartum, medication and alcohol-support text keep their plain wording;
FuckingHealthCatalogTestfails if one appears in the catalog. The coach drops the act for the same topics (FUNNY_VOICE). - The joke wraps the content. Same facts, same values (
{0}placeholders), same advice. Roast habits, never the person. Swearing is censored (f*cking), and the test checks that too. - The Portuguese voice is "Saúde do C*ralho" (
FUCKING_HEALTH_PT):pt-BR-FH.jsonlayered onpt-BR.json, so a string it doesn't rewrite reads as plain Portuguese. It was written natively (prra, cralho, m*rda), not translated from the English jokes, and the same test covers it.
Read this before touching service/Postpartum.kt or ui/screens/PostpartumUi.kt. Research and
sources: docs/postpartum-breastfeeding-research.md.
- Only she switches it on, in User Profile → Life stage (baby's birth date, feeding). It turns
itself off two years after the birth date (
Postpartum.active). - It never claims detection. Not mastitis, fever, depression, preeclampsia, milk supply or returning fertility; the ring's numbers are context. The alcohol time is an estimate (CDC: at least 2 h per 14 g standard drink), said as one. The LAM card is information, not contraception advice. Medications get e-lactancia/LactMed links and "ask your clinician", never a verdict.
- The mood check-in is the EPDS, verbatim (
assets/epds.json, with its citation). Don't paraphrase items: the validated wording is the instrument. The Portuguese text is the Pelotas 2004 cohort's (Santos et al., 2007); its per-option scores were mapped by meaning from the English scoring because the publication prints none, so have a clinician confirm them. Any answer above 0 on item 10 shows CVV 188 and SAMU 192 at once, whatever the total. Cut-offs: 10 (possible), 13 (likely), from the Brazilian validation. - Answers stay on the phone: SharedPreferences only, not the data archive, diagnostics or Health Connect.
- The calorie allowance is tracked, not guessed (
appliedCalorieBonus): the intake goal moves by the difference between what the stage calls for and what was added before, so weaning or switching off takes exactly that back. - No F*cking Health jokes here: postpartum text is on the voice's safety list.
Read this before touching service/LabReports.kt, ui/screens/LabReportsUi.kt or the coach's
labs block. Any lab report (blood, urine, hormones, anything) is added as a PDF from
My Health → Lab reports, and every marker is charted exam by exam.
- Pages go to the model as images, not as a PDF (
PdfRenderer, 1600 px, up to 10 pages), so every coach provider reads them, the custom/local one included. The PDF is sent once, when the user adds it; afterwards the coach reads the stored values (LabContext), never the file. - Nothing is saved until the user checks it. The read lands on a review screen where every value, unit and range is editable and rows can be removed. Don't add an auto-save path.
- The flag is computed, not taken from the model: a numeric value with a printed range is judged
against that range (
LabReports.flagFor); the model's marking only stands when there is no number or no range. The range is the lab's own and is stored per result, because labs and methods differ. - One marker, one key, across labs and languages (
markerKey, from the model's snake_case Englishkey, normalised). The chart follows the key, so a key change splits a marker's history. - It never diagnoses. No condition named, no value called fine or dangerous beyond "inside / outside
the lab's range", anything outside the range or trending badly goes to "your doctor", and never a
medication, supplement or dose. The coach's
LabContext.noteand its prompt line say the same; keep them in step. Goals change only throughset_goalafter the user agrees to the exact numbers. - The coach's use of the results is a switch on the Lab reports screen (
LabPrefs.coachUses). - Reports, results and each PDF (as base64) ride in the backup archive, and the switch rides in
ArchivedSettings. Deleting a report removes its results (FK cascade) and its PDF file.
Every change to the app's UI updates the design files in the same piece of work, and every change agreed on the design files is built into the app. The owner reviews and annotates the app on a Claude Design canvas, so a canvas that drifts from the app sends feedback against screens that no longer exist, and an app change missing from the canvas is invisible in review.
- The canvas: https://claude.ai/artifact/CUizVK8X1fJsNQ7kxUeiEg — one artboard per screen
(
project/<Screen>.dc.html), rows grouped by user journey with "how you get here" notes, and aFlowMap.dc.htmlartboard whose lanes and arrows follow the navigation. A new screen gets a board, a slot in its journey's row, a note, and a card in the flow map; a removed or renamed screen loses or renames all four. Links between boards (<a href="X.dc.html">) follow the app's real navigation. - The design system's source of truth is a repo:
gabrielbr/Gabriel-Deisgn-System, shared
with GVoice/GMind and audited on every change. Its
pulselooplayer generatesui/theme/GTokens.kt, andPulseColors/FairyMode.Paletteread every colour from it: noColor(0x…)literals there. A token, colour, type size or dither value changes in that repo first; then copy the generatedGTokens.ktin and run itsscripts/drift.py --pulseloop <this repo>until it reports 0 differences. - The design-system artifact: https://claude.ai/artifact/P1nRuiJhuffYq9pnNbHe5q — the tokens
above, the Bayer dither from
ui/theme/Dither.kt, Ubuntu Mono, and the web components the canvas mounts. A token changed in the repo is changed there too, and the canvas's copy (project/ds/pulseloop/) is refreshed. - Design → app: an annotation or design edit the owner agrees to is implemented in Compose, released through the normal flow, and only then reported as done.
- Read before writing. The owner edits the canvas by hand; read the boards you will change from the canvas first and edit those, never republish an older local copy over them.
- If a session cannot reach the canvas, say so in the PR description instead of skipping it silently.
PulseLoop is one of the apps the design-system repo governs (its pulseloop layer). Its AGENTS.md
"Rules every design decision follows" bind this app; where PulseLoop still differs, the
difference is recorded in that repo's docs/divergences.md (D-4 dark only, D-11 update
checksum, …), not here. Don't add a divergence in the app: add it there first, with its plan.
-
Four skills on every screen and flow. Every new or changed screen, flow, sheet, notification or widget is designed with, and then audited against, all four skills in
.claude/skills/, in this order:- ux-user-flows: first, decide what happens and in what order. Write the flow (entry points, steps, branches, every state, exits) and run its §13 flow review checklist.
- impeccable: shape, critique and polish while designing, then its native
auditandcritique, with the five dimensions scored and findings P0–P3. - graphic-design-fundamentals: plan with it, then its §13 checklist.
- less-is-more: the five questions on every element; what was cut; taps on common actions never rise.
Where a skill's general advice and this design system differ (target sizes, the one mint action, the frame), the design system wins.
Use them while working, not only at the end. If a skill won't load, read its
SKILL.mdand references and apply it by hand, and say so. The audit file has one section per skill. Fix any P0 or P1 finding, and anything the checklist fails, before merging. -
Where the audit goes:
audits/YYYY-MM-DD-<version or topic>.md, fromaudits/TEMPLATE.md(the design system's template), linked from the PR. A UI PR without one isn't merged. -
The skills are vendored (
.claude/skills/VENDORED.mdnames the design-system version). Re-copy them when a design-system release changes one; never edit the copies here. -
Every release publishes
SHA256SUMS.txt, and the in-app updater installs a download only when its SHA-256 matches that file and its signing key matches the installed app (the design system'sdocs/self-update.md).
Read this before adding a card, a row or a screen. The app is organised in two layers, and most clutter came from ignoring one of them:
- Where a thing lives follows what the user came to do. Logging (meal, drink, dose, period,
tags, workout) is one job, so it has one door: the "Actions" button on every tab
(
LogSheet, opened throughLaunchRequests.openLog). Today's Meal/Drink chips open the same sheet at a step; don't grow a second logging path on a new screen. The sheet is for now: Ask the coach, then meal, drink and medicine as one row of icons (the same kind of entry, so side by side), Period only for a profile whose sex is"female", tags, and starting a workout. - A past entry is added on its own screen, never from the Actions sheet. A past workout comes from Activity's "Log Past Activity", a past meal from the Nutrition tab's day arrows, a past period from Cycle. The owner asked for exactly this after the sheet briefly grew "For an earlier day" and "Past workout" rows: the sheet stops being one short list the moment it grows a "past" twin of each action.
- The tabs are Today, Vitals, Activity, Sleep, Nutrition. Nutrition took the Coach's tab
because seeing and back-filling meals was buried; the coach is the first row of the Actions
sheet and a pushed screen with its own back arrow. Don't put it back on the bar to "restore" it. Programs the user switched on
(cycle, meds, postpartum) surface on Today (
ProgramsRow), and Rest Mode is offered where "I'm unwell" happens (RestModeLine), not only in a menu. - Inside a screen, summary first, detail on tap. A screen leads with one summary and its primary action; everything else is a row that opens. A new section added inline at full weight is how My Health became a wall.
- My Health's door is the header, on every tab (
AppHeader+service/HealthHeadline.kt). The greeting is the eyebrow; under it one line says the most important thing first: lab markers outside their range in the latest report (opens Lab reports), then a radar sign (opens What changed), then "Learning you" before the 14-night baseline, then the weakest health area. It points at what to look at and never names a condition. It is one line, ellipsised, and keeps its last text while the next is read, so the header never changes height or blanks. Sleep, Vitals and Activity each end with one in-context row into My Health; Today has none. - One open section per screen. Today shows every card the user kept, always, with no "Show
all" fold (owner's call); trimming Today is Customize cards' job. My Health keeps health areas open and folds Trends, Habits and Stress into
closed sections (
Section(summary = …)), and the radar to one line unless it flags something. A new card should usually be a closed section, not another open one. - Repeat a figure only when the question differs. Last night's sleep on Today (am I okay?) and on Sleep (why?) is fine; the same sleep three times on Today is not. The alcohol-clearance card on Postpartum stays even though Drinks has one: "can I feed now?" is asked on that screen.
- Notifications are reachable whether or not the coach is on. Most of them (daily guidance, battery alerts) never needed it, and gating the row on the coach hid them all.
- Settings groups are jobs, named as jobs (
SettingsScreen): My ring, Notifications, Goals & tracking, AI Coach, Connected apps, Me, Data & privacy. A new setting goes where someone arriving with that job would look — sleep-hour rules sit with the sleep goal, every unit sits on the profile, the ring is unpaired from Ring & sync only — and a content screen is never a Settings row (Drinks used to be one). - A goal saved anywhere goes through
GoalSync.afterManualSave— it is what stops the field following the coach, sends the step goal to the ring and republishes the widget.
The rings give no raw accelerometer, so ActivityClassifier guesses from step cadence and
burstiness and from heart-rate level and unevenness. Every type is ranked; the user always picks.
Rules a change must keep:
- Nothing is logged without a tap. A wrong workout reaches Health Connect and Strava.
- The user's answers win. A confirmed suggestion stores its features with the chosen type
(
activity_detection→learned, newest 200, in the backup). Close earlier answers outweigh the rules, so don't tune the rules to override them. - "Not this" holds by overlap, not by key (
ActivityDetection.open): a re-detection with shifted bounds or a changed guess must not resurface a dismissed stretch. - Steps and heart stretches merge into one window (
mergeActive), so a run is never also offered as cardio. - Another device's workouts are suggestions too (
OtherDeviceWorkouts): read from Health Connect with a ring paired, never PulseLoop's own package, accepted under theirhc-id so the export skips them, and they win over a ring guess for the same time. Off while Health Connect is the data source (that importer already brings them in). - The heart rule is built for a 5-minute grid (
heartSessions): it survives a 12-minute dip and needs three raised readings and a raised average. Don't go back to ending a stretch on one low reading: that is what split strength sessions into pieces too short to count. - Notify once, recent only (
ActivityDetectionNotifier): after a sync'sdone, for activity ending in the last 12 h, never twice for the same stretch, behind its own switch and channel. Today shows the newest as one line; the Activity tab's card is where it is answered.
Typing a meal's name in the Log Meal form offers foods logged before (service/FoodHistory.kt,
MealEntryDao.recentReal): one per food, names compared without case or accents, with the
numbers from its newest log; names starting with the text first, then most-logged, then most
recent. Nothing under two letters, and demo rows never appear. A pick fills name, meal type and
macros, all still editable, and the saved meal keeps the original's provenance (barcode code,
serving, AI-estimate source); changing a number marks it userEdited, as a barcode pick does.
- Type sizes come from
PulseType.SCALE(12, 14, 16, 20, 24, 28, 32, 40). 12sp is the floor for anything that carries meaning;PulseTypeScaleTestfails on any other inline size in any source file. The tracked caps label over a card or section isPulseType.eyebrow(12sp, 1sp tracking,textSecondary) everywhere — don't hand-roll another letter-spacing. - Mint is the brand and the thing to tap, nothing else.
success(good, in range, connected) is its own green, REM is cyan, connecting is amber. The readiness and activity score rings are coloured by their band (the score's own meaning), not by the brand colour. - One card radius: 8dp. Tiles and vital cards used to be 20/30dp.
- Every button is a
PulseButton(ui/components/PulseButton.kt, v2.11.57): one composable with a style (Filled, Tonal, Outlined, Text) that holds the design system's button rules — 52dp minimum height and the 97% press scale. Never call Material'sButton,FilledTonalButton,OutlinedButtonorTextButtondirectly, and don't give a button a fixed.height(): it is a minimum so a long pt-BR label grows the button.PulseButtonTestfails on a direct call. - One filled accent per screen: the Actions button. A screen's own primary action is a tonal button (Activity's Record).
- Landscape keeps the header (compact, one row): it is the only route to Settings and the
ring. From 600dp the tabs move to a
NavigationRailand tab content caps at 720dp. - The ring pill opens the ring's screen (
settings/wearable); the gear opens Settings. - Tabs have no title of their own: the tab bar names the screen. Pushed screens use
CenterAlignedTopAppBar, and a row's trailing arrow isChevron(), never a "›" glyph. - The window theme is dark (
Theme.PulseLoop), so cold start doesn't flash white, and predictive Back is on (enableOnBackInvokedCallback).
Read this before restyling a screen. Plan and tokens: docs/new-look-plan.md. The owner chose
(2026-11-16) a calmer, shadcn-style look for PulseLoop only: dark only, mint kept, Inter.
- Its tokens and components are in
ui/calm/. A converted screen usesCalmColors,CalmType,CalmShapeand theCalm*components, neverPulseColorsgreys or literal sizes. Sizes stay onPulseType.SCALE, buttons are stillPulseButton, text still goes throughtr(). NewLook.ondecides, per screen. Off by default until every screen has moved; then the default flips and the old styling is deleted in one PR. Don't flip it early.- A state over time is a
StateTimeline, not a new chart. Its layout isStateTimelineModel, which is pure and tested. - It departs from the design system on purpose. Record that in the design-system repo's
docs/divergences.mdwhen a session can reach it.
- Every navigation destination goes through
DitherTransitionBox(theme/DitherTransition.kt), viascreen(...)/paddedComposable(...)inPulseLoopApp. A new route registered with a barecomposable(...)skips the wipe and pops in. The wipe draws both screens from one Bayer mask (incoming keeps the swept cells, outgoing keeps the rest), because the navigator puts the outgoing screen on top for a back press; a reveal drawn only on the incoming screen would be hidden there. NavHost's own fade (0.99 alpha) exists only to keep both screens composed forDURATION_MS. It sweeps diagonally, top-left to bottom-right, in 750 ms: 420 ms read as a flicker. Fairy mode uses a smooth gradient, like every other dither. - Rings are drawn, not photographed (
RingArtView): a dithered band turning about a tilted axis, the same for every model. A dark model tint falls back to the accent, since it would vanish on the page. - In-screen motion uses
theme/Motion.kt:sweepInfor rings, gauges and bars (fill from empty on first show, glide between values) andpressScalefor tappable cards. Collapsible sections expand withAnimatedVisibility. Prefer these over one-off specs, so the app moves one way. - All of it runs on Compose's clock, which honours the system "Remove animations" setting; don't
drive motion from a hand-rolled
delayloop that would ignore it.