module.personal-health

@lssm-tech/module.personal-health

Subject-bound, consent-controlled, non-clinical PersonalOS wellness ledger orchestration. The module composes provider-neutral contracts and deterministic runtime ports; hosts own durable databases, encrypted credential custody, provider transports, export artifact storage, audit persistence, and effects.

Public surfaces

• ./connections — consent-gated registration, explicit lifecycle transitions, and local-first revocation even when provider revocation fails.
• ./sync — bounded pagination, exact subject/connection/page binding, durable cursor/page checkpoints, idempotent page replay, strict normalization, quarantine, correction append, cross-provider overlap preservation, and restart after provider failure.
• ./history — one subject-bound history of measurements and corrections.
• ./rights — minimized export manifests, local deletion, projection removal, and per-provider deletion-propagation truth without a completion timestamp while any provider target is pending, failed, or unsupported.
• ./projections — ref-only PersonalOS goal linkage and expiring household summary/trend projections; raw measurements are never shared.
• ./household-revocation-service — exact authority-bound revocation with an atomic local invalidation/pending-receipt commit, replay-safe request collision denial, and separately validated consumer acknowledgement. Local access stays revoked while remote acknowledgement is pending or unavailable.
• ./insights — deterministic descriptive trend explanations derived only from two or more exact subject-, consent-, provenance-, metric-, and unit-bound ledger records. The service computes direction, confidence, freshness, and evidence references; callers cannot supply them. Unsupported metrics and clinical-looking records fail closed. User-requested urgent guidance is fixed EN/FR/ES non-monitoring copy.
• ./wellbeing-goal-service — a subject-confirmed wellbeing experiment over an exact PersonalOS goal, active provider connections, opaque provider-field references, accepted/corrected baseline and observation records, a bounded target and window, and mandatory human/consent/guardrail stop conditions. Exact goal ownership, granular goal/read consent, revisions, idempotency, digests, receipts, guardrails, state, and minimized audit commit through host ports. Consent revocation and verified guardrails pause collection and sharing locally even when consent or provider connectivity is unavailable.
• ./wellbeing-goal-summary and ./wellbeing-goal-query — an exact-subject, bounded host query that projects current plus recent experiments into the minimized PersonalOS workspace contract. Current experiments are never truncated; duplicate IDs, subject-version drift, count inflation, missing cursors, and raw/clinical/causal fields fail closed.

Connectivity boundary

HealthKit and Health Connect require host-provided native SDK ports and user authorization. Strava, Oura, Garmin, and Fitbit require host-provided transports, durable encrypted credential references, provider credentials, and operational controls. This package does not claim that any real provider is connected.

Safety boundary

The module does not diagnose, recommend treatment, monitor emergencies, infer protected traits, claim causality, or take consequential action. It never stores raw provider payloads or credential material and never substitutes 0, epoch, current time, a unit, a time zone, provenance, cursor, or healthy status for missing provider data.

The PGlite journeys persist normalized records for the production insight service, unified activity/sleep/biometric/nutrition history, restartable household revocation, and wellbeing experiment state. They verify encrypted rows and tokens, provider-failure restart, explicit cross-provider overlap evidence, quarantine, correction, raw-free export, deletion propagation, and deletion survival across restart. They also preserve local revocation and wellbeing guardrail pauses without restoring access or duplicating audit history. These are local simulated-provider journeys, not live-provider qualification.

The health-operations E2E additionally composes the observed strict Strava adapter with the subject-bound sync, encrypted checkpoint/ledger, rights, and connection services. It exercises a redacted provider failure, restart and paginated recovery, duplicate/quarantine handling, webhook HMAC denial, propagated deletion, local revocation, and content-free durable observations. It remains simulated local evidence and does not qualify a live provider, production alerting, a recovery drill, or a canary.

Verification

bun run lint:check
bun run typecheck
bun run test
bun run build