Merge remote-tracking branch 'origin/main' into work/native-stepup-rebase

This commit is contained in:
Marc-André Bombeck committed 2026-07-23 09:04:43 +02:00
commit 8119cc6c82
642 files changed
+56250 -13112

No files matched your search

+174 -33
View File
@@ -1,7 +1,7 @@
openapi: 3.1.0
info:
title: HealthLog API
version: 1.30.33
version: 1.32.0
description: >-
Self-hosted personal-health-tracking PWA — public API surface for the iOS native client and external ingest.
@@ -3054,11 +3054,11 @@ paths:
- Measurements
summary: Sleep rhythm — sleep-debt + chronotype (v1.17.0)
description: "Returns the two server-authoritative sleep-timing signals the Sleep page + iOS render off the same
canonical night reconstruction the Sleep Score uses: cumulative `sleepDebt` over the rolling window (calm
`partial` state under the night threshold) and MCTQ `chronotype` (MSF/MSFsc band + social jetlag, `learning`
state until enough free-day nights exist). Free vs work nights default to weekend = free in the user's timezone
(no work calendar). A read-only view over existing per-stage SLEEP_DURATION rows — no schema, no new measurement
type."
canonical night reconstruction the Sleep Score uses: the outstanding `sleepDebt` balance over the rolling window
(calm `partial` state under the night threshold) and MCTQ `chronotype` (MSF/MSFsc band + social jetlag,
`learning` state until enough free-day nights exist). Free vs work nights default to weekend = free in the
user's timezone (no work calendar). A read-only view over existing per-stage SLEEP_DURATION rows — no schema, no
new measurement type."
responses:
"200":
description: Sleep-debt + chronotype DTO.
@@ -3126,10 +3126,12 @@ paths:
summary: Workout detail (v1.4.32)
description: Single-workout envelope. Owns the optional `WorkoutRoute` GeoJSON geometry + `canonicalId` pointer that
resolves to the cluster winner so deep-links into non-canonical twin rows can redirect cleanly. Additive
enrichment fields (`hrSeries`, `zones`, `splits`, `sportContext`, reserved `aiInsight`) are computed
server-side. `compact=1` (sent by the web client) drops the raw `samples.samples` HR blob and
`route.sampleTimestamps` array from the response; without it the payload is byte-identical to the v1.4.32
contract. Cross-user rows surface as 404 (existence channel sealed).
enrichment fields (`hrSeries`, `zones`, `splits`, `sportContext`) are computed server-side. `aiInsight` is a
pure read of a per-workout paragraph written by a background job when the workout landed; it is null for every
workout that predates the feature or was re-synced, and reading this endpoint never generates one. `compact=1`
(sent by the web client) drops the raw `samples.samples` HR blob and `route.sampleTimestamps` array from the
response; without it the payload is byte-identical to the v1.4.32 contract. Cross-user rows surface as 404
(existence channel sealed).
parameters:
- in: path
name: id
@@ -5671,6 +5673,9 @@ paths:
type: string
minLength: 1
maxLength: 500
workoutId:
type: string
maxLength: 64
required:
- message
responses:
@@ -10309,13 +10314,13 @@ paths:
post:
tags:
- Documents
summary: Summarise or transcribe a document (session-only)
description: 'On-demand, SESSION-ONLY description of a stored document. `?mode=summary` (default) returns a short
plain-language summary of WHAT the document is; `?mode=text` returns its raw transcribed text. The result is
transient — nothing is persisted except the AI-budget ledger + audit log; it never reaches coach memory,
snapshots, the structured stores, or the search index. The summary is descriptive only and never a diagnosis.
Same VISION (empty body) / TEXT (`application/json` `{ mode: "text", text }`, opt-in local OCR) dispatch as
extract. AI-consent / rate / budget gated. 422 with no provider.'
summary: Summarise or transcribe a document
description: 'On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language
summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot,
while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw
transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The
summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode:
"text", text }`, opt-in local OCR) dispatch as extract. AI-consent / rate / budget gated. 422 with no provider.'
parameters:
- name: id
in: path
@@ -10332,6 +10337,20 @@ paths:
- text
default: summary
description: "`summary` (plain-language description) or `text` (raw)."
- name: persist
in: query
required: false
schema:
type: boolean
default: false
description: "For summary mode only: persist into an empty stored-summary slot."
- name: replace
in: query
required: false
schema:
type: boolean
default: false
description: With `persist=true`, explicitly replace an existing stored summary.
requestBody:
required: false
content:
@@ -10361,7 +10380,7 @@ paths:
- text
responses:
"200":
description: The session-only summary (`{ summary }`) or extracted text (`{ text }`).
description: The summary and its persistence outcome, or transient extracted text.
content:
application/json:
schema:
@@ -12648,6 +12667,19 @@ components:
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
- type: "null"
manufacturer:
description: Marketing-authorisation holder / maker as printed on the carton. Free text, max 120 chars.
anyOf:
- type: string
maxLength: 120
- type: "null"
doseStrength:
description: Strength as printed on the container, e.g. "5 mg/0.5 ml". Free text, max 60 chars — deliberately not split
into a number + unit because pens state strength per dose, per ml, or per cartridge.
anyOf:
- type: string
maxLength: 60
- type: "null"
notes:
anyOf:
- type: string
@@ -12681,6 +12713,19 @@ components:
type: number
minimum: 0
maximum: 1000
manufacturer:
description: Marketing-authorisation holder / maker as printed on the carton. Free text, max 120 chars.
anyOf:
- type: string
maxLength: 120
- type: "null"
doseStrength:
description: Strength as printed on the container, e.g. "5 mg/0.5 ml". Free text, max 60 chars — deliberately not split
into a number + unit because pens state strength per dose, per ml, or per cartridge.
anyOf:
- type: string
maxLength: 60
- type: "null"
notes:
anyOf:
- type: string
@@ -17710,6 +17755,10 @@ components:
type: integer
minimum: 0
maximum: 9007199254740991
failed:
type: integer
minimum: 0
maximum: 9007199254740991
skipped:
type: array
items:
@@ -17734,6 +17783,7 @@ components:
- inserted
- updated
- duplicates
- failed
- skipped
- entries
additionalProperties: false
@@ -17751,9 +17801,10 @@ components:
- updated
- duplicate
- skipped
description: "`inserted`/`duplicate` — the row landed (advance the cursor). `updated` — a `stats:` aggregate (per-day
cumulative total or hourly heart-rate bucket) overwrote an existing row. `skipped` — not stored (e.g.
unmappable identifier, out-of-range value, or `malformed_hr_bucket_id`); see `reason`."
- failed
description: "`inserted`/`duplicate` — the row landed (advance the cursor). `updated` — a `stats:` aggregate overwrote
an existing row. `skipped` — validation no-op; see `reason`. `failed` — retryable database failure that must
not advance the entry cursor; the response is marked `Cache-Control: no-store`."
reason:
type: string
required:
@@ -18237,12 +18288,13 @@ components:
- partial
- ready
description: "`partial` until enough tracked nights exist (calm 'still learning'); `ready` once the rolling window can
assert a cumulative debt."
assert a balance."
debtMinutes:
type: integer
minimum: 0
maximum: 9007199254740991
description: Cumulative sleep debt over the window, in minutes, after caps.
description: Outstanding sleep-debt balance over the window, in minutes, after caps. A night below need adds its
shortfall; a night above need pays the balance down (floored at 0).
needMinutes:
type: integer
minimum: 0
@@ -18383,9 +18435,9 @@ components:
- chronotype
- averagePerNight
additionalProperties: false
description: "Server-authoritative sleep-rhythm read: cumulative sleep debt over the rolling window + MCTQ chronotype
(MSF/MSFsc band, social jetlag). Free vs work nights default to weekend = free in the user's timezone (no work
calendar). A view over existing per-stage SLEEP_DURATION rows — no schema, no new type."
description: "Server-authoritative sleep-rhythm read: the outstanding sleep-debt balance over the rolling window + MCTQ
chronotype (MSF/MSFsc band, social jetlag). Free vs work nights default to weekend = free in the user's timezone
(no work calendar). A view over existing per-stage SLEEP_DURATION rows — no schema, no new type."
ListWorkoutsResponse:
type: object
properties:
@@ -18648,7 +18700,9 @@ components:
- $ref: "#/components/schemas/WorkoutSportContext"
- type: "null"
aiInsight:
type: "null"
anyOf:
- $ref: "#/components/schemas/WorkoutActivityInsight"
- type: "null"
canonicalId:
type: string
required:
@@ -18847,6 +18901,19 @@ components:
- avgDistanceM
- avgAvgHr
additionalProperties: false
WorkoutActivityInsight:
type: object
properties:
paragraph:
type: string
generatedAt:
type: string
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
required:
- paragraph
- generatedAt
additionalProperties: false
BatchWorkoutsResponse:
type: object
properties:
@@ -19727,6 +19794,18 @@ components:
format: date-time
pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
- type: "null"
manufacturer:
anyOf:
- type: string
- type: "null"
description: Marketing-authorisation holder / maker as printed on the carton. NULL for a container registered before the
field existed, and for plain supply rows that never carried one.
doseStrength:
anyOf:
- type: string
- type: "null"
description: Strength as printed on the container, e.g. "5 mg/0.5 ml". Free text, not split into a number + unit — pens
state strength per dose, per ml, or per cartridge. NULL when unknown.
notes:
anyOf:
- type: string
@@ -19751,6 +19830,8 @@ components:
- expiresAt
- printedExpiry
- purchasedAt
- manufacturer
- doseStrength
- notes
- createdAt
- updatedAt
@@ -25250,6 +25331,28 @@ components:
anyOf:
- type: string
- type: "null"
dueCandidates:
type: array
items:
type: object
properties:
medicationId:
type: string
medicationName:
type: string
dueAt:
type: string
overdue:
type: boolean
availableFrom:
type: string
required:
- medicationId
- medicationName
- dueAt
- overdue
- availableFrom
additionalProperties: false
required:
- activeCount
- scheduledToday
@@ -25260,12 +25363,11 @@ components:
- nextDueMedicationName
- nextDueMedicationId
additionalProperties: false
description: "Today's medication block: active-medication count, today-window tally (scheduled / taken / skipped), and
the earliest next-due slot across active medications. `nextDueOverdue: true` marks an OPEN overdue slot
(anchor passed, still inside its catch-up band). `nextDueMedicationId` deep-links a consumer straight to the
overdue medication's card. Staleness contract: the snapshot is cache-served, so a `nextDueAt` in the past
with `nextDueOverdue: false` means the anchor passed after the snapshot was built — render the plain day
summary, never an overdue state."
description: "Today's medication block: active-medication count, today-window tally (scheduled / taken / skipped), every
active medication's current display-due candidate, and legacy scalar fields projected from candidate zero.
`overdue: true` marks an OPEN overdue slot (anchor passed, still inside its catch-up band); `availableFrom`
is the canonical cadence- and dose-window-derived attribution-band start. `dueCandidates` is optional so
older cached snapshots remain valid. Medication ids let consumers deep-link straight to the relevant card."
healthScore:
anyOf:
- type: object
@@ -30629,6 +30731,12 @@ components:
type: string
text:
type: string
persistence:
type: string
enum:
- stored
- withheld
- failed
additionalProperties: false
DocumentIndexEnvelope:
type: object
@@ -31663,6 +31771,37 @@ components:
items:
$ref: "#/components/schemas/DailyPriorityItem"
description: Bounded 0–3 rail items, never padded.
justIn:
anyOf:
- type: object
properties:
kind:
type: string
enum:
- sleep_night
- workout
- weight
- blood_pressure
- labs_panel
description: Closed arrival kind that landed.
at:
type: string
description: ISO-8601 instant of the newest sample. NEVER pre-formatted server-side — the client formats it in its own
locale and timezone.
required:
- kind
- at
additionalProperties: false
- type: "null"
description: The day's newest data arrival while it is still news (under three hours old), else null. Additive since
v1.31.0.
reactionLine:
anyOf:
- type: string
- type: "null"
description: One-sentence generated reaction to that arrival, standing for the rest of the local day. Null whenever no
line was generated (no provider, no consent, budget exhausted, or generation failed) — consumers fall back
to `briefingLead` / `line`. Additive since v1.31.0.
required:
- generatedAt
- phase
@@ -31672,6 +31811,8 @@ components:
- briefingLead
- line
- worthALook
- justIn
- reactionLine
additionalProperties: false
description: The one data spine of the daily-value system — composed from already-cached data, never a fresh AI call.
Consumed by the Today surface, the daily push, and a future iOS widget.
+59 -18
View File
@@ -112,29 +112,50 @@ mapped set (workout routes, ECG voltage traces) is counted in
### Cumulative HK type → daily aggregate
Cumulative quantity types — steps, active energy, walking/running
distance, flights climbed — get **collapsed into one row per
user-local day** to match the iOS daily-aggregation convention.
distance, flights climbed, time in daylight, and fall count — get
**collapsed into one estimated row per user-local day**. `export.xml`
contains source-specific records, not HealthKit's canonical daily
statistics, so the importer does not sum different devices or apps
into a source-blind total.
- Records are grouped by type, local day, and a SHA-256 hash of the
available source name, source version, and device attributes.
Values sum within each identified source-day; the largest
source-day subtotal is selected deterministically. If every source
attribute is absent, records remain separate rather than being
trusted as one source. Raw source and device labels are not
persisted.
- The row records `EXPORT_XML_SOURCE_MAX` provenance, its distinct
contributor count, and the selected non-identifying source hash.
- External ID format: `stats:<HKType>:<YYYY-MM-DD>` (e.g.
`stats:HKQuantityTypeIdentifierStepCount:2026-05-15`).
- The day boundary respects the user's timezone preference. The
worker defaults to `Europe/Berlin` when no preference is set
(`src/lib/jobs/apple-health-import-worker.ts:132-133`).
- A second import of the same archive re-folds the same days onto
the same external IDs — the values update in place rather than
duplicating.
(`src/lib/jobs/apple-health-import-worker.ts`).
- XML intervals are not reconstructed or split. A record crossing
midnight is assigned using its mapped timestamp and remains covered
by the explicit estimate contract.
- A second import re-folds the same days onto the same external IDs.
Equal-authority estimates update idempotently rather than duplicate.
The terminal job result exposes
`cumulativeEstimates: { days, rows }`; the web import card warns when
one or more cumulative days used this estimate path.
### Re-import idempotency
The two-axis idempotency story:
1. **File-level** — re-uploading the same `export.zip` (same SHA-256
of bytes) short-circuits to the previous job before the parser
even starts.
of bytes) short-circuits to the previous job only when that job
used the current parser revision. Existing jobs are revision 1;
new jobs use revision 2, so a pre-fix successful archive can be
deliberately processed again under the corrected aggregation.
2. **Record-level** — when an older `export.zip` is re-exported from
iOS (same history, slightly newer device timestamps), every
record's external ID stays stable. The upsert path matches on
`(userId, externalId)` and updates instead of inserting.
record's external ID stays stable. The serialized reconciliation
path matches the canonical identity and updates instead of
inserting.
Practically: a user who exports monthly and re-imports each archive
sees fresh data merged in without duplicates. The job result line
@@ -150,14 +171,34 @@ is identical to the user-facing flow.
The `ImportJob` row carries `triggeredByAdminId = admin.id` so the
status endpoint admits both the target user and the triggering
admin. Idempotency is scoped by target user — an admin re-uploading
the same archive for the same user resolves to the previous job.
admin. Idempotency is scoped by target user and parser revision — an
admin re-uploading the same archive for the same user resolves to the
previous current-revision job.
Typical use: migrating a friend's history into their HealthLog
account when they cannot run the import themselves, or backfilling
a household member's data after the admin received the `export.zip`
out of band.
## Aggregate authority and recovery
Native HealthKit daily statistics submitted by the iOS batch endpoint
are canonical and carry `HEALTHKIT_STATISTICS` provenance. XML
source-maximum estimates carry `EXPORT_XML_SOURCE_MAX`. Both use the
same serialized reconciler with this ordering:
`LEGACY_UNKNOWN < EXPORT_XML_SOURCE_MAX < HEALTHKIT_STATISTICS`
A later XML import cannot overwrite native statistics. Native
statistics repair an XML estimate or legacy row in either arrival
order, and every material reconciled update or resurrection increments
`syncVersion`. Existing Apple Health `stats:*` rows are migrated to
`LEGACY_UNKNOWN`; they are never guessed or heuristically promoted.
To recover an already-corrupted legacy total, the user must re-upload
the original archive under parser revision 2 or sync native HealthKit
statistics. Without either input, the correct per-source total cannot
be reconstructed from the stored aggregate.
## Source-priority interaction
HealthLog's source ladder is **APPLE_HEALTH ≻ WITHINGS ≻ MANUAL ≻
@@ -169,12 +210,12 @@ max). The defaults live in `src/lib/validations/source-priority.ts:205-220`.
Concrete consequences:
- If you already sync steps from a Withings ScanWatch and also import
Apple Health, the Apple-Health-aggregated stream wins for the day —
iOS HealthKit folds the watch sensor + iPhone motion data into a
single canonical stream, so it is the most complete cumulative
source. The Withings rows stay in the database as an audit trail
but drop out of the per-day aggregation.
- Native HealthKit cumulative statistics are the canonical Apple
Health stream for a day and outrank both XML estimates and Withings
cumulative rows. An XML upload chooses the largest source subtotal
only; it never claims to reproduce HealthKit's device de-duplication.
Lower-priority rows stay in the database as an audit trail but drop
out of the displayed per-day aggregation.
- If you weigh yourself on a Withings scale and also import Apple
Health (which received the same reading via the Health Mate iOS
app), the Withings row wins for display. Apple Health is
+3 -3
View File
@@ -84,9 +84,9 @@ pnpm dlx tsx scripts/restore-backup.ts \
/tmp/restored.json
```
The production standalone image strips `tsx`, so a bare
`pnpm tsx scripts/...` fails inside the container — always invoke
one-shot scripts via `pnpm dlx tsx`.
Run this command from a source checkout with the production backup variables
exported. The script imports the full application dependency graph, which the
minimal production image does not expose as an operator scripting environment.
The script downloads the object, decrypts it, and writes the JSON dump
to disk. Importing the JSON back into a HealthLog instance is left to
+14 -15
View File
@@ -46,24 +46,23 @@ metadata (`medication_schedules`):
Always. The default mode only reports and never mutates:
```bash
# inside the app container (or any checkout) — DATABASE_URL must point
# at the target database
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts
# inside the production app container — DATABASE_URL is inherited
healthlog-tsx scripts/repair-intake-anomalies.ts
# scoped to one account
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --user <userId>
healthlog-tsx scripts/repair-intake-anomalies.ts --user <userId>
# source-checkout equivalent
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts
```
The script is self-contained: its only import is `pg` and it reads
`DATABASE_URL` straight from the environment (no dotenv, no `@/` path
alias, no `src/` imports). That matters in the production container —
the standalone image ships no project `node_modules`, so the previous
revision died there with `Cannot find module 'dotenv/config'`. Inside
the image `pg` resolves via `NODE_PATH=/opt/pg-boss/node_modules`; in a
checkout it resolves from the project `node_modules`; the
`--package pg --package tsx` pins cover any environment with neither.
Use `pnpm dlx`, not bare `pnpm tsx` — the standalone image also strips
`tsx`.
alias, no `src/` imports). The production image provides the pinned
`healthlog-tsx` launcher and resolves `pg` from its standalone runtime tree
without retaining a package manager. In a source checkout, `pg` resolves from
the project `node_modules`; `pnpm dlx --package pg --package tsx ...` also
works in an environment where neither dependency is installed.
The dry-run prints every duplicate group (which row would be kept, which
would be tombstoned), a table of implausible rows (id, medication,
@@ -74,7 +73,7 @@ would write), and a table of stale-anchor pending rows.
## Applying the fix
```bash
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --fix
healthlog-tsx scripts/repair-intake-anomalies.ts --fix
```
`--fix` does five things:
@@ -92,7 +91,7 @@ pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --fix
in explicitly:
```bash
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --fix --tombstone-implausible
healthlog-tsx scripts/repair-intake-anomalies.ts --fix --tombstone-implausible
```
`--tombstone-implausible` is refused without `--fix`.
@@ -139,7 +138,7 @@ slot anchors:
The default run only **reports** the proposals. Apply them explicitly:
```bash
pnpm dlx --package pg --package tsx tsx scripts/repair-intake-anomalies.ts --backfill-eras
healthlog-tsx scripts/repair-intake-anomalies.ts --backfill-eras
```
Review the dry-run table first — the inference is a heuristic. A wrongly