Carry the bests, the badges and the environmental history through a restore

Four models leave the coverage-pending register with both ends and a
round-trip proof: PersonalRecord, UserAchievement, EnvironmentContext and
EnvironmentTravelLocation. Two new section modules hold reader and restore
beside each other, the arrangement the visits, vaccinations, reminders and
Coach sections already use.

The register understated two of them. The bests are "recomputable in
principle", which is true and does not help: nothing recomputes them, and a
recomputation over a restored history would find different rows, because
sample series and GPS routes never travel, a portable file omits deleted
readings, and a record set in a reading that has since been corrected cannot
be found twice. The badge's unlock date is worse. The evaluator prefers a
persisted date over a derived one, and several of the dates it can still
derive come from counters no backup carries, so a dropped row does not relock
the badge, it re-earns it today.

PersonalRecord.sourceMeasurementId is the reference that needed care, and it
is the dangerous kind. The schema declares no relation for it; migration 0054
created the column as a real foreign key against measurements. Writing it
blind is not a dangling pointer, it is a constraint violation that rolls the
whole restore back and hands the operator an empty account. Measured, with the
resolution removed: "Foreign key constraint violated on the constraint:
personal_records_source_measurement_id_fkey", HTTP 500, nothing restored. So
the restore runs after the measurements, resolves the pointer against the rows
it actually wrote, nulls what it cannot resolve and reports it under a new
personalRecordReference skip kind.

An unlocked badge names a definition in the code catalogue, which drifts
between the release that writes a file and the one that reads it. The id is
carried and written back verbatim rather than judged, the same answer the
vaccination restore gives an antigen slug it cannot resolve.

The readings and the location periods travel as a pair because carrying the
readings alone is worse than losing them. The environment resolver reads the
periods live, so with them gone the nightly seven-day lookback re-resolves
every trip day to the home location and upserts over the row: an account would
come back with a fortnight abroad and then have it quietly rewritten as a
fortnight at home, days after a restore that reported success. Day keys stay
strings end to end, and fetchedAt is restored verbatim so a two-year-old
provisional reading does not claim it was confirmed today.

The round trip seeds bests that share a metric type and an instant and differ
only in the sport slot, two badges earned years apart (one of them under an id
this build no longer defines), and a trip day beside a home day, then reads
each back column by column. Counting alone passes every one of the failures
worth fearing here: slots dropped so a 5 km best is presented as a 10 km best,
unlock dates stamped at restore time, a trip day re-attributed to the home
city, a location period whose bounds no longer cover the reading it explains.
Each of those was applied on purpose and each failed on its own assertion.

Two schema comments claimed no read path selects a column that this backup now
selects; both say what reads it instead of staying wrong.
This commit is contained in:
Marc-André Bombeck committed 2026-08-22 11:14:15 +02:00
1 parent 974a90f28f
commit f95fb95295
20 files changed
+1350 -21

No files matched your search

+130
View File
@@ -36,6 +36,7 @@ import {
EncounterStatus,
ExtractedFactStatus,
ExtractedFactType,
EnvironmentLocationSource,
FamilyRelationship,
FlowLevel,
GlucoseContext,
@@ -61,6 +62,7 @@ import {
MedicationSideEffectCategory,
MedicationSideEffectEntry,
OvulationTest,
PersonalRecordDirection,
ReminderOrigin,
RhythmClassification,
SecondarySymptom,
@@ -1105,6 +1107,106 @@ const measurementReminderEventBackupSchema = z
})
.passthrough();
/**
* One personal best.
*
* `direction` is required rather than defaulted: it says whether higher or
* lower wins, the read path orders by it, and a best time defaulted to MAX
* would present the account's worst time as its record. `sourceMeasurementId`
* is the provenance pointer the restore resolves, and a real foreign key in the
* database, whatever `prisma/schema.prisma` says, so the restore nulls what it
* cannot resolve rather than letting Postgres refuse the whole file.
*/
const personalRecordBackupSchema = z
.object({
metricType: z.enum(MeasurementType),
metricSlot: z.string().nullable().optional(),
direction: z.enum(PersonalRecordDirection),
value: z.number(),
unit: z.string().min(1),
achievedAt: isoDateTime,
sourceMeasurementId: z.string().nullable().optional(),
source: z.enum(MeasurementSource).optional(),
externalId: z.string().nullable().optional(),
createdAt: isoDateTime.optional(),
})
.passthrough();
/**
* One unlocked badge.
*
* `achievementId` is a free string on purpose: it names a definition in the
* code catalogue, which drifts between the release that wrote the file and the
* one that reads it, and a row is evidence that a person earned something on a
* day rather than a claim about what this build ships.
*
* `unlockedAt` is REQUIRED, unlike almost every other stamp in this file. It
* is the field that cannot be recovered from anywhere else, and a file that
* does not state it must fail rather than restore every badge to today.
*/
const userAchievementBackupSchema = z
.object({
achievementId: z.string().min(1),
unlockedAt: isoDateTime,
createdAt: isoDateTime.optional(),
})
.passthrough();
/** `YYYY-MM-DD`, the day key both environment tables are addressed by. */
const environmentDayKey = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
message: "Expected a YYYY-MM-DD day key",
});
/**
* One day's environmental reading.
*
* `source` is required: it is the only record that the day resolved somewhere
* other than the home city, and a defaulted value would re-attribute a trip to
* home. Every weather column is optional, because the feed is allowed to be partial
* and a file written before a column existed says nothing about it.
*/
const environmentContextBackupSchema = z
.object({
date: environmentDayKey,
lat: z.number(),
lon: z.number(),
locationLabel: z.string(),
source: z.enum(EnvironmentLocationSource),
tempMin: z.number().nullable().optional(),
tempMax: z.number().nullable().optional(),
tempMean: z.number().nullable().optional(),
apparentMean: z.number().nullable().optional(),
sunshineSec: z.number().int().nullable().optional(),
daylightSec: z.number().int().nullable().optional(),
precipSum: z.number().nullable().optional(),
pressureMean: z.number().nullable().optional(),
pressureDelta: z.number().nullable().optional(),
humidityMean: z.number().nullable().optional(),
cloudMean: z.number().nullable().optional(),
weatherCode: z.number().int().nullable().optional(),
fetchedAt: isoDateTime.optional(),
createdAt: isoDateTime.optional(),
updatedAt: isoDateTime.optional(),
})
.passthrough();
/**
* One declared stretch spent away from home. Both bounds are day keys rather
* than instants: the resolver compares them lexicographically against other
* day keys, and routing one through a `Date` is how a day key loses a day.
*/
const environmentTravelLocationBackupSchema = z
.object({
startDate: environmentDayKey,
endDate: environmentDayKey,
lat: z.number(),
lon: z.number(),
label: z.string(),
createdAt: isoDateTime.optional(),
updatedAt: isoDateTime.optional(),
})
.passthrough();
/**
* One Coach turn.
*
@@ -1512,6 +1614,19 @@ export const backupPayloadSchema = z
measurementReminderEvents: z
.array(measurementReminderEventBackupSchema)
.default([]),
// The bests and the badges. Defaulted for the same reason as the sections
// above: a file written before they travelled carries no key, and an
// account that has earned neither writes [].
personalRecords: z.array(personalRecordBackupSchema).default([]),
userAchievements: z.array(userAchievementBackupSchema).default([]),
// The per-day readings and the location periods that explain them. Two
// keys rather than one because they are two tables, but they are written
// and restored as a pair: readings whose periods are missing get rewritten
// to the home location by the next refresh.
environmentContexts: z.array(environmentContextBackupSchema).default([]),
environmentTravelLocations: z
.array(environmentTravelLocationBackupSchema)
.default([]),
manifest: backupManifestSchema.nullable().default(null),
// v1.37.19 (A6-9) — field paths a PORTABLE export could not decrypt
// (fail-soft nulls). Disclosed in the file so a nulled field is
@@ -1614,6 +1729,14 @@ export interface BackupSummary {
mentalHealthAssessments: number;
/** Consent records. Disaster-recovery payloads only. */
consentReceipts: number;
/** Personal bests across every metric and sport slot. */
personalRecords: number;
/** Badges the account has unlocked, each with the day it was earned. */
userAchievements: number;
/** Local days with an environmental reading. */
environmentContexts: number;
/** Declared stretches spent away from home. */
environmentTravelLocations: number;
}
export function summarizeBackup(payload: BackupPayload): BackupSummary {
@@ -1685,6 +1808,13 @@ export function summarizeBackup(payload: BackupPayload): BackupSummary {
coachReminders: payload.coachReminders.length,
mentalHealthAssessments: payload.mentalHealthAssessments.length,
consentReceipts: payload.consentReceipts.length,
// Counted from the release that carries them, so the admin's "what did I
// just restore" answer never under-counts a file with bests, badges or an
// environmental history the way it once did for visits.
personalRecords: payload.personalRecords.length,
userAchievements: payload.userAchievements.length,
environmentContexts: payload.environmentContexts.length,
environmentTravelLocations: payload.environmentTravelLocations.length,
};
}