feat(integrations): let the ledger hold every failing leg at once

`failing_leg` was one slot, so two legs of the same provider failing in
overlapping windows overwrote each other. The row remembered whichever failed
last, and that leg recovering then cleared an error the other one was still
causing — the ledger forgot a live failure and painted the card green over it.

The slot becomes a set. A failure adds its leg, a success removes its own, and
the error state, the per-kind buckets and the streak anchor clear only once the
set is empty. The array is ordered oldest failure first, so the last element is
the leg that wrote the message `last_error` holds; when that leg recovers while
others are still failing, the message is cleared rather than left describing a
leg that is now healthy.

An unattributed failure adds nothing and removes nothing. A single-leg provider
therefore behaves exactly as before, and a multi-leg provider no longer loses
what its other legs already reported.

The column never reached a client — it is absent from the status serialiser and
from the OpenAPI contract — so it is replaced rather than shimmed.
This commit is contained in:
Marc-André Bombeck committed 2026-07-27 14:35:33 +02:00
1 parent 3088753a92
commit 06935256b0
18 files changed
+433 -58

No files matched your search

+18 -1
View File
@@ -130,12 +130,27 @@ export const GET = apiHandler(async () => {
const row = await prisma.user.findUnique({
where: { id: user.id },
select: { healthKitConfigJson: true, healthKitLastSyncedAt: true },
select: {
healthKitConfigJson: true,
healthKitLastSyncedAt: true,
healthKitLastSyncTrigger: true,
healthKitLastBackgroundSyncAt: true,
},
});
const stored = parseStored(row?.healthKitConfigJson ?? null);
const entries = mergeWithDefaults(stored);
const lastSyncedAt = row?.healthKitLastSyncedAt?.toISOString() ?? null;
// What triggered the most recent accepted batch, and when data last arrived
// without the app being opened. `lastSyncedAt` alone cannot separate those
// two cases, which is the whole diagnostic: a card that only ever says "last
// sync 10 minutes ago" reads the same whether the phone is delivering by
// itself or whether every arrival was the user opening the app. Null in
// either field is honest absence — an older client that declares no trigger,
// or a pipe that has never delivered in the background.
const lastSyncTrigger = row?.healthKitLastSyncTrigger ?? null;
const lastBackgroundSyncAt =
row?.healthKitLastBackgroundSyncAt?.toISOString() ?? null;
// Apple Health is push-based: the iOS app delivers and nothing here polls, so
// liveness is a data question, not an attempt question. Without a threshold a
@@ -157,6 +172,8 @@ export const GET = apiHandler(async () => {
return apiSuccess({
entries,
lastSyncedAt,
lastSyncTrigger,
lastBackgroundSyncAt,
syncHealth,
metricFreshness: classifyMetricFreshness(samples, syncHealth.verdict),
});
+27 -7
View File
@@ -169,12 +169,14 @@ const batchEntrySchema = z.object({
});
// v1.32.8 (iOS #66) — optional per-REQUEST diagnostic tag naming what woke the
// client for this sync. Purely observational: it flows into the
// `measurement.batch.ingest` wide event and NOTHING else — never persisted,
// never part of the dedup key, never an input to attribution or how a sample is
// stored. Only the client knows its own wake reason, so it is client-asserted
// by necessity; being diagnostic-only, that carries no trust surface. Optional
// so every pre-#66 caller stays byte-for-byte unchanged.
// client for this sync. Purely diagnostic: it flows into the
// `measurement.batch.ingest` wide event and onto the account's HealthKit
// diagnostic columns, which the Apple Health card reads. It is never part of
// the dedup key and never an input to attribution or how a sample is stored —
// sending it or omitting it produces byte-identical row outcomes. Only the
// client knows its own wake reason, so it is client-asserted by necessity;
// being diagnostic-only, that carries no trust surface. Optional so every
// pre-#66 caller stays byte-for-byte unchanged.
const syncTriggerEnum = z.enum(["foreground", "background", "push"]);
const batchPayloadSchema = z.object({
@@ -644,10 +646,28 @@ async function postBatch(request: NextRequest): Promise<Response> {
// This batch route is the native HealthKit ingestion boundary. Stamp only
// after every attempted write has reached a durable, non-failed verdict;
// MANUAL-only and skipped-only batches are not HealthKit syncs.
//
// The trigger the client declared is stamped alongside, and a background- or
// push-triggered batch additionally dates `healthKitLastBackgroundSyncAt`.
// Without that second timestamp there is no way to tell a phone that delivers
// on its own from one that only ever delivers while the app is open — both
// look like a moving `healthKitLastSyncedAt`. A batch that declares no
// trigger writes null over the previous value rather than leaving a stale one
// standing: the field describes THIS sync, and an older build's silence is
// not evidence about it.
if (healthKitSyncSucceeded) {
const syncedAt = new Date();
const deliveredWithoutTheApp =
syncTrigger === "background" || syncTrigger === "push";
await prisma.user.update({
where: { id: user.id },
data: { healthKitLastSyncedAt: new Date() },
data: {
healthKitLastSyncedAt: syncedAt,
healthKitLastSyncTrigger: syncTrigger ?? null,
...(deliveredWithoutTheApp
? { healthKitLastBackgroundSyncAt: syncedAt }
: {}),
},
});
}
@@ -201,7 +201,13 @@ export function IntegrationStatusPill({
? "destructive"
: "outline"
}
aria-label={t("settings.integrationPill.ariaLabel")}
// No `aria-label` here. One used to sit on the badge and, being a
// generic string, it REPLACED the accessible name with itself — a screen
// reader announced the same words for "connected · 4 minutes ago" as for
// "error", which is the one distinction the pill exists to make. The
// visible label is the accessible name; the relative time stays
// `aria-hidden` because it is decoration on top of a state that already
// reads.
className={cn(
"max-w-full whitespace-nowrap",
state === "connected" && connectedChipClass,
@@ -18,7 +18,10 @@ import { HeartPulse, Upload } from "lucide-react";
import { SettingsCardHeader } from "@/components/settings/_card-header";
import { SettingsCard } from "@/components/settings/settings-card";
import { IntegrationStatusPill } from "@/components/settings/integration-status-pill";
import {
formatRelative,
IntegrationStatusPill,
} from "@/components/settings/integration-status-pill";
import { Button } from "@/components/ui/button";
import { apiGet } from "@/lib/api/api-fetch";
import { useTranslations } from "@/lib/i18n/context";
@@ -31,12 +34,84 @@ import { queryKeys } from "@/lib/query-keys";
import { MetricFreshnessDisclosure } from "./metric-freshness-disclosure";
import { IntegrationErrorMessage, pillStateForVerdict } from "./shared";
type SyncTrigger = "foreground" | "background" | "push";
interface HealthKitStatus {
lastSyncedAt: string | null;
/** What the client said woke it for the most recent accepted batch. */
lastSyncTrigger?: SyncTrigger | null;
/** When data last arrived without the app being opened. */
lastBackgroundSyncAt?: string | null;
syncHealth?: SyncHealth;
metricFreshness?: MetricFreshnessEntry[];
}
const TRIGGER_KEYS: Record<SyncTrigger, string> = {
foreground: "settings.appleHealth.delivery.trigger.foreground",
background: "settings.appleHealth.delivery.trigger.background",
push: "settings.appleHealth.delivery.trigger.push",
};
/**
* Whether the phone is delivering on its own, or only while someone is looking
* at it. `lastSyncedAt` cannot tell those apart — a card that reports nothing
* but "last sync 10 minutes ago" reads identically in both cases, which is why
* "is background delivery working?" was unanswerable from either side. The
* trigger of the most recent batch and the date of the last background arrival
* are the two facts that settle it, and each is shown only when it exists: a
* client that reports no trigger says so rather than being guessed at.
*/
function DeliveryDiagnostic({
status,
t,
}: {
status: HealthKitStatus;
t: (key: string, params?: Record<string, string | number>) => string;
}) {
const trigger = status.lastSyncTrigger ?? null;
const triggerLabel = t(
trigger
? TRIGGER_KEYS[trigger]
: "settings.appleHealth.delivery.trigger.unknown",
);
const backgroundAt = status.lastBackgroundSyncAt;
return (
<div className="space-y-2" data-testid="apple-health-delivery">
<h3 className="text-sm font-semibold">
{t("settings.appleHealth.delivery.title")}
</h3>
{status.lastSyncedAt ? (
<dl className="space-y-1 text-sm">
<div className="flex flex-wrap gap-x-2">
<dt className="text-muted-foreground">
{t("settings.appleHealth.delivery.lastTriggerLabel")}
</dt>
<dd data-testid="apple-health-last-trigger">{triggerLabel}</dd>
</div>
<div className="flex flex-wrap gap-x-2">
<dt className="text-muted-foreground">
{t("settings.appleHealth.delivery.lastBackgroundLabel")}
</dt>
<dd data-testid="apple-health-last-background">
{backgroundAt
? formatRelative(
Math.max(0, Date.now() - new Date(backgroundAt).getTime()),
t,
)
: t("settings.appleHealth.delivery.backgroundNever")}
</dd>
</div>
</dl>
) : (
<p className="text-muted-foreground text-sm">
{t("settings.appleHealth.delivery.noSyncYet")}
</p>
)}
</div>
);
}
export function AppleHealthCard({ enabled }: { enabled: boolean }) {
const { t } = useTranslations();
const {
@@ -96,6 +171,8 @@ export function AppleHealthCard({ enabled }: { enabled: boolean }) {
</p>
)}
{showPill && <DeliveryDiagnostic status={status} t={t} />}
<MetricFreshnessDisclosure
entries={status?.metricFreshness}
idPrefix="apple-health"
+2
View File
@@ -311,6 +311,8 @@ export const USER_RESET = {
stravaBackfillCompletedAt: null,
healthKitConfigJson: Prisma.DbNull,
healthKitLastSyncedAt: null,
healthKitLastSyncTrigger: null,
healthKitLastBackgroundSyncAt: null,
lastSyncedAt: null,
sourcePriorityJson: Prisma.DbNull,
+6
View File
@@ -61,6 +61,12 @@ export const INTEGRATION_WORKOUT_SOURCE: Partial<
> = {
strava: "STRAVA",
polar: "POLAR",
// These three write workouts too, and were missing from this table, so their
// cards could report every measurement type fresh while the workout leg had
// been silent for weeks — the freshness disclosure had no row to go quiet.
whoop: "WHOOP",
fitbit: "FITBIT",
"google-health": "GOOGLE_HEALTH",
};
/**
+91 -17
View File
@@ -229,6 +229,32 @@ const ERROR_STATES: ReadonlySet<string> = new Set<IntegrationState>([
"parked",
]);
/**
* Read the `failingLegs` JSON column into an ordered list of leg names.
*
* Anything that is not an array of strings — a legacy `null`, a hand-edited
* row, a shape from a future schema — reads as the empty set, which is the
* pre-existing "unattributed failure" semantics under which any success clears
* the row. Non-string members are dropped rather than coerced: a leg name is an
* identifier the caller passes, and inventing one from a number would let a
* success match a leg nobody ever recorded.
*/
function readFailingLegs(value: unknown): string[] {
if (!Array.isArray(value)) return [];
return value.filter((entry): entry is string => typeof entry === "string");
}
/**
* Append `leg` as the most recent failure, moving it to the end if it is
* already in the set. Ordering is load-bearing: the last element is the leg
* that wrote the message `lastError` currently holds, which is what lets a
* partial recovery tell "this message still describes a failing leg" from
* "this message belongs to a leg that has since recovered".
*/
function withLegRecorded(current: readonly string[], leg: string): string[] {
return [...current.filter((entry) => entry !== leg), leg];
}
export interface IntegrationStatusSnapshot {
integration: IntegrationKey;
state: IntegrationState;
@@ -373,15 +399,26 @@ export interface RecordSyncSuccessOptions {
* the state that the sleep leg had recorded at :15. The failing leg's strike
* ladder was reset several times an hour, so it could never reach the alert
* threshold or the park window, and the card painted a green "connected · 12
* minutes ago" over a data class that had stopped arriving. When the row holds
* an error owned by a DIFFERENT named leg, this success records its attempt and
* leaves the error standing.
* minutes ago" over a data class that had stopped arriving.
*
* This success removes its OWN leg from the failing set and clears the row only
* once that set is empty. The set matters because the previous single slot
* could remember one leg at a time: with sleep and activity both failing, the
* second failure overwrote the first, and the second leg recovering then wiped
* an error the first was still causing. The ledger forgot a live failure and
* went green over it — the exact case this set exists to hold.
*
* The partial path deliberately does NOT advance `lastSuccessAt`. That field is
* what the freshness arms and the card's "connected · X ago" read, and moving
* it forward while another leg is dead is exactly the sentence this change
* exists to stop the ledger from saying. `lastAttemptAt` does advance, so the
* row still reads as "being tried" rather than ageing into `stalled`.
*
* `lastError` is cleared on the partial path when the recovering leg is the one
* that wrote it. The message then describes a leg that is now healthy, and a
* row that keeps showing it is describing the wrong failure; the next attempt
* by a still-failing leg writes its own. No message is honest here — a guessed
* one would not be.
*/
export async function recordSyncSuccess(
userId: string,
@@ -394,18 +431,28 @@ export async function recordSyncSuccess(
if (leg !== null) {
const existing = await prisma.integrationStatus.findUnique({
where: { userId_integration: { userId, integration } },
select: { state: true, failingLeg: true },
select: { state: true, failingLegs: true },
});
const failingLegs = readFailingLegs(existing?.failingLegs);
const remaining = failingLegs.filter((entry) => entry !== leg);
const heldByAnotherLeg =
existing != null &&
existing.failingLeg != null &&
existing.failingLeg !== leg &&
remaining.length > 0 &&
ERROR_STATES.has(existing.state);
if (heldByAnotherLeg) {
// The recovering leg owned `lastError` iff it was the most recent
// failure, i.e. the last element. Dropping it leaves the row without a
// message for any leg that is still failing, which is the honest state
// until one of them fails again and writes its own.
const ownedLastError = failingLegs[failingLegs.length - 1] === leg;
await prisma.integrationStatus.update({
where: { userId_integration: { userId, integration } },
data: { lastAttemptAt: now },
data: {
lastAttemptAt: now,
failingLegs: remaining,
...(ownedLastError ? { lastError: null } : {}),
},
});
// Meta only — the enclosing wide event owns its own action name (the
// cron task), and overwriting it here would rename the job.
@@ -414,7 +461,7 @@ export async function recordSyncSuccess(
integration_partial_success: {
integration,
succeeded_leg: leg,
failing_leg: existing.failingLeg,
failing_legs: remaining,
},
},
});
@@ -435,6 +482,7 @@ export async function recordSyncSuccess(
lastSuccessAt: now,
lastAttemptAt: now,
consecutiveFailuresByKind: zeroBuckets(),
failingLegs: [],
},
update: {
state: "connected",
@@ -444,7 +492,7 @@ export async function recordSyncSuccess(
consecutiveFailuresByKind: zeroBuckets(),
persistentFailureStartedAt: null,
failingSinceAt: null,
failingLeg: null,
failingLegs: [],
alertedAt: null,
},
});
@@ -518,10 +566,20 @@ export async function recordSyncFailure(
consecutiveFailuresByKind: true,
persistentFailureStartedAt: true,
failingSinceAt: true,
failingLegs: true,
alertedAt: true,
},
});
// The failing set, with this leg appended as the most recent failure. An
// unattributed failure (no leg — a single-leg provider, or a recorder that
// does not know which leg it caught) adds nothing and removes nothing: it
// carries no attribution to record, and erasing what other legs already
// reported would let one of their successes clear an error it did not fix.
const existingLegs = readFailingLegs(existing?.failingLegs);
const failingLegs =
leg !== null ? withLegRecorded(existingLegs, leg) : existingLegs;
// Resolve the starting bucket envelope:
// - existing JSON value if present
// - zero envelope for a row that has never written a bucket payload
@@ -627,7 +685,7 @@ export async function recordSyncFailure(
consecutiveFailuresByKind: buckets,
persistentFailureStartedAt: isPersistent ? now : null,
failingSinceAt,
failingLeg: leg,
failingLegs,
},
update: {
state: newState,
@@ -636,7 +694,7 @@ export async function recordSyncFailure(
consecutiveFailuresByKind: buckets,
persistentFailureStartedAt,
failingSinceAt,
failingLeg: leg,
failingLegs,
},
});
@@ -663,6 +721,10 @@ export async function recordSyncFailure(
// "we concluded it was after a day of retrying".
escalatedFrom: escalatedFromTransient ? kind : null,
failingLeg: leg,
// Every leg the row currently holds an error for, not just this one —
// the audit trail is where an operator reconstructs an overlapping
// outage, and one leg per row was never enough to do it.
failingLegs,
failingSinceAt: failingSinceAt.toISOString(),
streakAgeMs,
errorCode: errorCode ?? null,
@@ -776,7 +838,7 @@ export async function resumeIntegrationFromPark(
consecutiveFailuresByKind: zeroBuckets(),
persistentFailureStartedAt: null,
failingSinceAt: null,
failingLeg: null,
failingLegs: [],
alertedAt: null,
},
});
@@ -833,11 +895,23 @@ export async function parkIntegrationAtReauth(opts: {
// audit log when the state or error changes.
const existing = await prisma.integrationStatus.findUnique({
where: { userId_integration: { userId, integration } },
select: { state: true, lastError: true, failingSinceAt: true },
select: {
state: true,
lastError: true,
failingSinceAt: true,
failingLegs: true,
},
});
const isFreshPark =
existing?.state !== "error_reauth" || existing.lastError !== encryptedError;
// Same set semantics as `recordSyncFailure`: a scope-skip park adds its leg
// to whatever the row already holds rather than replacing it, so a sibling
// leg's independent failure survives the park.
const existingLegs = readFailingLegs(existing?.failingLegs);
const failingLegs =
leg !== null ? withLegRecorded(existingLegs, leg) : existingLegs;
await prisma.integrationStatus.upsert({
where: { userId_integration: { userId, integration } },
create: {
@@ -851,7 +925,7 @@ export async function parkIntegrationAtReauth(opts: {
// 3-strike runway before paging.
consecutiveFailuresByKind: zeroBuckets(),
failingSinceAt: now,
failingLeg: leg,
failingLegs,
},
update: {
state: "error_reauth",
@@ -861,7 +935,7 @@ export async function parkIntegrationAtReauth(opts: {
// bucket values are preserved exactly. This is the whole point
// of the helper.
failingSinceAt: existing?.failingSinceAt ?? now,
failingLeg: leg,
failingLegs,
},
});
@@ -948,7 +1022,7 @@ export async function markDisconnected(
consecutiveFailuresByKind: zeroBuckets(),
persistentFailureStartedAt: null,
failingSinceAt: null,
failingLeg: null,
failingLegs: [],
alertedAt: null,
},
});
@@ -977,7 +1051,7 @@ export async function markReconnected(
consecutiveFailuresByKind: zeroBuckets(),
persistentFailureStartedAt: null,
failingSinceAt: null,
failingLeg: null,
failingLegs: [],
alertedAt: null,
},
});
+18
View File
@@ -15,6 +15,11 @@ const healthKitDirectionEnum = z
.enum(["bidirectional", "readOnly", "writeOnly", "disabled"])
.describe("Per-metric sync direction.");
// Mirror the batch route's `syncTriggerEnum` — what woke the client for a sync.
const healthKitSyncTriggerEnum = z
.enum(["foreground", "background", "push"])
.describe("What triggered a HealthKit batch.");
// Resolved entry (defaults merged): `kind` + `enabled` are always present.
const healthKitEntry = z
.object({
@@ -89,6 +94,19 @@ const healthKitConfigResponse = z
.describe(
"When HealthKit last synced for this user; null when never (and always null on the PATCH echo).",
),
lastSyncTrigger: healthKitSyncTriggerEnum
.nullable()
.optional()
.describe(
"What the client declared triggered the most recent accepted batch. Null when the client sent no trigger — an older build, or a batch that predates the field. Present on the GET read; omitted from the PATCH echo.",
),
lastBackgroundSyncAt: z.iso
.datetime({ offset: true })
.nullable()
.optional()
.describe(
"When a batch last arrived without the app being opened (a `background` or `push` trigger). Null when that has never happened. `lastSyncedAt` alone cannot separate a phone that delivers on its own from one that only delivers while the app is open; this field is what does. Present on the GET read; omitted from the PATCH echo.",
),
syncHealth: syncHealth
.optional()
.describe("Present on the GET read; omitted from the PATCH echo."),
+6 -5
View File
@@ -112,15 +112,16 @@ const batchPayloadSchema = z
.object({
entries: z.array(batchEntrySchema).min(1).max(500),
// v1.32.8 (iOS #66) — optional per-request diagnostic tag naming what woke
// the client for this sync. Observability only: it is recorded on the
// ingest wide event and NEVER persisted, deduped on, or used in
// attribution — sending it or omitting it produces byte-identical row
// outcomes. Omit on any client that does not track its wake reason.
// the client for this sync. Diagnostic only: it is recorded on the ingest
// wide event and on the account's HealthKit diagnostic fields, which
// `GET /api/integrations/healthkit` publishes. It is never deduped on or
// used in attribution — sending it or omitting it produces byte-identical
// row outcomes. Omit on any client that does not track its wake reason.
syncTrigger: z
.enum(["foreground", "background", "push"])
.optional()
.describe(
"Diagnostic-only. Names what triggered this sync (foreground app open, background refresh, or a push wake) so an operator can see, per batch, which trigger produced it. Recorded on the ingest wide event and nowhere else — it does not affect dedup, attribution, or how any sample is stored. Optional and backward-compatible: pre-#66 clients omit it.",
"Diagnostic-only. Names what triggered this sync (foreground app open, background refresh, or a push wake). Recorded on the ingest wide event and kept on the account as `lastSyncTrigger` — plus `lastBackgroundSyncAt` for a `background` or `push` trigger — both readable from `GET /api/integrations/healthkit`. It does not affect dedup, attribution, or how any sample is stored. Optional and backward-compatible: pre-#66 clients omit it.",
),
})
.meta({