Session Card — Module X3: Sensors & Biometrics

Planning artifact. A future build session opens this card, reads the referenced plan docs and the latest session-handoff for the target cell, builds exactly one cell, then writes its own handoff. No production code lives here.

Purpose

Module X3 gives Health Debug its device-sensor bridge and the body-metrics feature that sits on top of it. The ToGO backend gains a biometrics ingest path plus a body-metrics module (its own ToGO plugin) that stores raw health samples verbatim and computes a baseline-from-earliest-reading progress model server-side. The native clients read the device health stores on-device only — Apple via HealthKit, Android via Health Connect — serialize new samples to JSON, and push them to ToGO; they also write Health Debug's own confirmed logs back into the device store for ecosystem parity. The web client renders read-only body-metrics display cards. Consistent with the two Core Opinions, no client ever interprets a biometric (no thresholds, no trend copy, no "your weight is concerning"): samples are transported and rendered verbatim, all analysis is backend behavioral-pattern analysis only, and any surfaced conclusion always defers to "Consult your doctor." This is a cross-cutting module, so it runs alongside the Apple/Android engine sessions (doc 13 §4), and — like every module — its backend session must land before any client session.

Engine / feature parameters relevant to this module

Use these exact values. Do not invent numbers. Items are tagged [spec-fixed], [legacy precedent — PENDING ratification], or [PENDING DESIGN].

• Body-metrics scope (backend, superset): Weight, Body Fat %, Body Water %, Heart Rate, Skin Temp, Sleep. [spec-fixed]
• Progress model: baseline is the earliest logged reading; progress is computed from that baseline forward, server-side (a legacy precedent reused; clients never compute it). [legacy precedent — PENDING ratification]
• Apple HealthKit read scope → push: Weight (bodyMass, direct), Body Fat % (bodyFatPercentage, direct), Body Water % (no first-party HealthKit type exists — source undefined), Heart Rate (heartRate, direct), Skin Temp (appleSleepingWristTemperature and/or bodyTemperature — mapping undefined). Apple's §5 read scope has no Sleep read. [spec-fixed scope; Water% + Skin Temp mapping = PENDING DESIGN]
• Apple HealthKit write-back: exactly two things — (1) burned active calories (backend-provided figures), (2) completed hydration (each server-accepted 250 ml water log written as a dietary water sample). Only server-confirmed entries; samples tagged with the backend entry ID for idempotency. [spec-fixed]
• Android Health Connect read scope → push: Weight, Body Fat %, Heart Rate, Sleep (sessions/wake time). Android has no Body Water % and no Skin Temp. Permission groups requested at point of use. [spec-fixed]
• Android Health Connect write-back: hydration (accepted 250 ml unit → Hydration record) and nutrition/food (categorical model → quantitative Health Connect record mapping is unresolved). Only backend-accepted logs are mirrored; a cooldown- or cap-rejected hydration tap is never written. [spec-fixed; nutrition mapping = PENDING DESIGN]
• Cross-scope reconciliation: Apple lacks Sleep read; Android lacks Water % + Skin Temp. The unified backend body-metrics scope must tolerate per-platform partial coverage without treating an absent type as an error. [PENDING DESIGN — open question]
• Hydration write-back units carried from M1: 250 ml logging unit, 5000 ml/day cap, 30-second cooldown are enforced server-side by the Hydration engine; X3 clients only mirror the accepted result, never re-decide it. [spec-fixed]
• Legacy weigh-in window 07:00–11:00 existed in the legacy notify.go for weigh-in nudges. It is a legacy precedent only, not a greenfield spec constant — do not bake it into the body-metrics module without ratification. [legacy precedent — PENDING ratification]
• Schema rule: health_samples and daily_summaries — every column NOT NULL with an explicit default; all migrations strictly expand-contract; sqlc + Atlas; raw samples stored verbatim (raw-sensor push model). [spec-fixed]

Session table

Surfaces in scope for X3: backend → web → apple → android (per the surface order; mcp, chrome, desktop are out of scope for this module — biometrics do not surface in a browser popup, the brief names no MCP body-metrics tools, and desktop reuses the web cards). Backend precedes all clients.

Session ID	Surface	Scope (this one session builds)	Entry deps	Done criteria (doc 13 §5 template)	Plan docs to read
S-<date>-X3-backend-NN	backend	Biometrics ingest endpoint(s) + the body-metrics module as its own ToGO plugin: accept batched biometric samples (Weight, Body Fat %, Body Water %, Heart Rate, Skin Temp, Sleep) and store them verbatim in health_samples; roll per-day state into daily_summaries; compute the baseline-from-earliest-reading progress model server-side; expose a read endpoint returning that computed state. No interpretation/thresholds.	M0.1–M0.4 (kernel/config, TOGO auth, plugin framework, expand-contract migration harness)	Backend-engine template: module registered on the kernel as its own plugin; health_samples + daily_summaries migrations are expand-contract with every column NOT NULL + explicit default; ingest is idempotent (same batch/key ⇒ one row, replayed result) and stores raw samples verbatim; read endpoint returns server-computed baseline/progress state (no client math); unit tests encode the baseline-from-earliest + progress logic literally and pass; integration test against real Postgres passes (idempotent-replay, cross-user isolation 404-not-403); no threshold/interpretation logic anywhere (analysis defers to backend AI + "Consult your doctor"); no protocol constant leaks outside the module's core/ package.	13 §3/§4/§5; 04 (§1 layout, §3 sqlc+Atlas, §4 NOT-NULL rule, §5 expand-contract, §8 plugin purity, §9 testing); 03; 01 (Core Opinions); 12 (legacy health_samples, weigh-in precedent)
S-<date>-X3-web-NN	web	Body-metrics display cards: render the server-computed body-metrics state (latest reading + baseline + progress per type) fetched from the X3 read endpoint. Read-only; no logging, no interpretation.	S-<date>-X3-backend-NN; M0.5 (web shell + typed API client + auth), M0.6 (theme), M0.7 (i18n/RTL)	Client-engine template: cards render the X3 endpoint state and never compute baseline/progress locally; thin-client/SSOT audit passes (grep finds no biometric thresholds, no baseline math, no protocol constants in client code); both dark-glow and light-flat themes render per the strict color spec; Arabic RTL mirrors correctly (incl. any progress bars); all strings ICU, none concatenated.	13 §3/§5; 05 (§ data-fetch/mutation rules, endpoint consumption sketch); 01 (i18n/RTL, Core Opinions); 04 §7 (endpoint conventions)
S-<date>-X3-apple-NN	apple	HealthKit bridge (HDSensors): observer + anchored queries per type, background delivery; read Weight/Body Fat %/Heart Rate/Skin Temp on-device, serialize to JSON, push to the X3 ingest endpoint; write-back burned active calories + server-confirmed completed hydration (250 ml → dietary water sample) with idempotency-tagged sample metadata. Water % + Skin Temp mapping flagged, not blocking direct-mapped types.	S-<date>-X3-backend-NN; Apple suite scaffold + iOS core-app sessions (workspace, HDAPIClient, TOGO auth); M1 hydration backend (for completed-hydration write-back)	Client-engine template + HealthKit: reads bridged as JSON and pushed to the X3 endpoint; write-back writes only backend-accepted entries (calories + hydration), idempotency-tagged so retries do not duplicate samples; denied-permission paths are non-fatal (silently-empty types, no guessed error states); thin-client/SSOT audit passes (no on-device interpretation, thresholds, or protocol constants — the 250/5000/30 never embedded as rule values); both themes + Arabic RTL for any body-metrics UI; ICU strings.	13 §3/§4/§5; 07 (§3 HDSensors layout, §3.1 sensor-vs-logic line, §5 HealthKit read/permission/write-back, §Open Questions); 01 (Core Opinions, RTL); 04 §7
S-<date>-X3-android-NN	android	Health Connect bridge (core/healthconnect): read Weight/Body Fat %/Heart Rate/Sleep on-device with point-of-use permission groups; push raw records to the X3 ingest endpoint via WorkManager + changes-token differential (deltas, not full history); write-back backend-accepted hydration (250 ml → Hydration record) and nutrition (mapping flagged) for ecosystem parity.	S-<date>-X3-backend-NN; Android suite scaffold + core-app sessions (core/network, TOGO auth token handling); M1 hydration backend (hydration write-back); nutrition write-back also needs M4 trigger-families backend (parity, flagged)	Client-engine template + Health Connect: read/push round-trip for Weight/Body Fat %/Heart Rate/Sleep; write-back fires only on backend-accepted logs — a 30s-cooldown- or 5000ml-cap-rejected hydration tap produces no Health Connect record; permission groups requested at point of use with non-fatal denied-permission fallbacks; thin-client/SSOT audit passes (no biometric interpretation, no protocol constants in client); both themes + Arabic RTL; ICU strings, none concatenated.	13 §3/§4/§5; 08 (§4 Health Connect read/write/endpoint sketch, §Open Questions); 01 (Core Opinions, RTL); 04 §7

Session count: 4 (backend, web, apple, android).

Notes & gotchas

• Legacy precedents worth reusing. The legacy build already had a health_samples table and a Zepp smart-scale flowing weight/body-fat/HR/sleep in through Apple Health — mine its shape and the baseline-from-earliest-reading progress idea (validate the greenfield module against any legacy *_test.go cases first, per doc 12). Keep the greenfield DB conventions (NOT NULL + default) and re-evaluate the legacy anti-patterns (text ids, absent-date-as-empty-text, triggers-as-CSV) rather than porting them.
• Thin-client / SSOT is the liability to avoid. The legacy iOS app carried a second protocol implementation (never called /api/today) — do not repeat it. X3 clients read the device store and render server state only; the baseline/progress math and any interpretation live exclusively in the backend module's core/. The Apple audit specifically greps for embedded rule numbers (250/5000/30/90/240/60/3).
• Categorical, not quantitative + no invented certainty. Biometrics are transported verbatim; there is no threshold logic, no "your heart rate is high" copy, and no diagnosis-shaped output on any surface. Any conclusion is backend behavioral-pattern analysis and always defers to "Consult your doctor."
• PENDING DESIGN — open items (do not silently resolve):
  • Cross-scope reconciliation of Apple vs Android read scopes: Apple lacks a Sleep read; Android lacks Body Water % and Skin Temp. The unified backend scope must accept partial per-platform coverage without erroring on an absent type.
  • Body Water % has no first-party HealthKit type — where it comes from on iOS (vendor-specific HealthKit writes? unsupported on Apple? backend-only via other clients) is unresolved.
  • Skin Temp mapping — appleSleepingWristTemperature, bodyTemperature, or both, and how the backend labels them on ingest.
  • Nutrition write-back mapping (Android) — Health Connect nutrition records are quantitative while Health Debug is categorical; what (if anything beyond name/timestamp) is written back is undecided (Health Debug holds no nutrient quantities).
  • Offline / queuing behavior for pushes (queue with original timestamps vs. reject vs. hybrid) is unresolved project-wide and interacts with server-enforced temporal rules.
  • Ingest sync cadence (background sync interval, changes-token differential cadence) is a backend-negotiated setting, unconfirmed.
  • Legacy weigh-in window 07:00–11:00 is a legacy precedent, not a spec constant — do not adopt without ratification.
• Ordering. X3 backend must precede all X3 clients. The Apple/Android sessions also depend on their suite scaffold + core-app sessions and on M1 hydration backend for the hydration write-back path (Android nutrition parity additionally leans on M4). Sequence X3 alongside the Apple/Android engine builds, not before them.

Handoff reminder

At session end, follow doc 13 §6: retain one session-handoff memory then memory/edit it to attach metadata (retain cannot set metadata). Use a unique source_ref: handoff/X3-sensors-biometrics/<surface>/<n> (never reuse — a duplicate supersedes the prior). Metadata: {project:"healthdebug", category:"session-handoff", era:"greenfield", status:"current", surface:"<surface>", module:"X3", title:"Handoff <session-id>", tags:[...], next:"<module+surface>"}. Fill the content with the exact SESSION HANDOFF structure (Module/Surface/Status, Summary, Files touched, Decisions, Deviations, Tests run, OPEN THREADS, NEXT SESSION). Then update the single build-ledger memory (source_ref: build-ledger, edited in place) so one recall shows the whole frontier and the recommended next session. Any new architectural decision or open question also gets its own classified memory and, if it changes the plan, an edit to the relevant plan doc.