fix(sync): enforce the plausibility domain on every provider write path

Every interactive path, every import, MCP and Telegram checked an incoming
measurement against VALUE_RANGES before storing it. The provider sync writers
did not, so a decode slip or a glitched sensor landed a row the application
itself calls impossible, and every mean, median and personal band derived from
it inherited the impossibility. Filtering the read side hid the row. It kept
landing.

The gate is one module reading the domain the app already declares, applied at
two kinds of seam. reconcileExternalMeasurement is the shared identity writer
for Polar, Oura, WHOOP, the Withings sleep leg, the Apple export importer and
the batch endpoint, so gating there means a provider added later inherits the
refusal rather than having to remember a check it never knew about; the new
rejected_range verdict carries no row, which is what makes the compiler force
every caller to handle it. The five writers that hold Prisma themselves gate at
their entry, before the existence probe decides insert versus overwrite, so an
impossible reading can no longer replace a good stored value.

An out-of-band value is dropped. Not clamped, because a clamp invents a reading
nobody took. Not stored behind a flag, because a quarantined row is still a row
and every consumer would have to learn the flag. Not fatal to the batch, because
one bad sample must not strand the run's other readings behind a held watermark.
Absence reads as absence.

A silent drop, though, is indistinguishable from a provider that sent nothing,
so every drop is tallied on the wide event under measurement.range_rejected with
the metric, the provider and the edge it broke. Counts only: the reading itself
is health data and never enters the log line, and the direction plus the
metric's own declared bound is what a diagnosis actually needs. The tally
accumulates rather than replacing, because a provider gates once per resource
leg and the reconciler once per row. One warning per provider lifts the event to
warn so a drop does not hide inside a green line.

A structural guard enumerates all twenty measurement writers with the reason
each is allowed to write, so a new one has to answer the question before it
ships. scripts/diagnose-implausible-measurements.ts reports the rows already
stored, aggregated per metric and source with no value beyond the bucket's own
extremes. It repairs nothing: whether a stored impossible row is a decode slip
or a band that is too narrow is not a call a script gets to make.
This commit is contained in:
Marc-André Bombeck committed 2026-08-07 22:19:43 +02:00
1 parent 8a1585a391
commit 2941d56238
21 files changed
+1733 -8

No files matched your search

@@ -0,0 +1,200 @@
/**
* Structural guard on the measurement ingest boundary.
*
* `VALUE_RANGES` is the band the application declares a metric can occupy.
* Every path a person can drive enforced it from the start; the provider sync
* writers never did, and nothing noticed, because each writer is correct on
* its own terms — it wrote what the remote sent. The gap was only visible from
* above, by listing every writer at once and asking which of them had ever
* been told about the band.
*
* So the list lives here. Every file that writes a `Measurement` row is
* enumerated with the reason it is allowed to, and the guard fails when the
* discovered set stops matching. A provider added tomorrow lands a file that
* is not in the map and has to answer the question before it can ship.
*
* This is a tripwire, not a proof. It cannot show a disposition is the right
* one — only that nobody added a writer without writing down which gate covers
* it. A reviewer who waves through a bogus `derived` label defeats it, and no
* test substitutes for that review.
*/
import { describe, it, expect } from "vitest";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { walkSourceFiles } from "./helpers/source-files";
const SRC = join(process.cwd(), "src");
/** The gate module every provider-fed writer has to reach. */
const GATE_MODULE = "@/lib/measurements/plausibility-gate";
/** The predicate every person-driven write path has always used. */
const VALIDATOR = "validateMeasurementRange";
/**
* How a writer satisfies the plausibility domain.
*
* - `gate` — provider-fed; must reach {@link GATE_MODULE} itself.
* - `validator` — person-driven; must call {@link VALIDATOR} itself.
* - `upstream` — validated in a named module before the row is built; the
* named module is checked, so the label cannot be a shrug.
* - `derived` — the value is arithmetic over rows already in the table, not a
* number from outside. Gating here would drop a consolidation of data that
* IS present, which is a different failure from admitting one that is not.
* - `literal` — the written value is a constant in the file, so no external
* number can reach the column.
* - `restore` — replays the record's own backup verbatim. Fidelity is the
* contract; a restore that silently dropped rows would be the worse bug,
* and the diagnostic script is how a stored impossible row gets found.
*/
type Disposition =
| { kind: "gate" }
| { kind: "validator" }
| { kind: "upstream"; validatedIn: string }
| { kind: "derived"; why: string }
| { kind: "literal"; why: string }
| { kind: "restore"; why: string };
const WRITERS: Record<string, Disposition> = {
// ── Provider sync writers, gated ──────────────────────────────────────
"lib/withings/sync.ts": { kind: "gate" },
"lib/withings/sync-activity.ts": { kind: "gate" },
"lib/fitbit/sync-core.ts": { kind: "gate" },
"lib/google-health/sync-core.ts": { kind: "gate" },
"lib/nightscout/sync.ts": { kind: "gate" },
// The shared identity seam. Polar, Oura, WHOOP, the Withings sleep leg,
// the Apple export importer and the batch endpoint all write through it,
// so the gate here is what makes a new provider fail closed.
"lib/measurements/reconcile-external-measurement.ts": { kind: "gate" },
// ── Person-driven write paths, validated ──────────────────────────────
"app/api/measurements/route.ts": {
kind: "upstream",
validatedIn: "lib/validations/measurement.ts",
},
"app/api/import/route.ts": { kind: "validator" },
"lib/mcp/writes.ts": { kind: "validator" },
"lib/measurements/create-from-telegram.ts": { kind: "validator" },
"lib/measurements/import-apple-health-export.ts": { kind: "validator" },
"app/api/import/csv/route.ts": {
kind: "upstream",
validatedIn: "lib/import/csv-measurements.ts",
},
// ── Fixed values ──────────────────────────────────────────────────────
"lib/withings/sync-ecg.ts": {
kind: "literal",
why: "an ECG row carries value 1 — the file's own constant, never a provider number",
},
"app/api/mental-health/assessments/route.ts": {
kind: "literal",
why: "the questionnaire score is summed from Zod-bounded item answers",
},
"lib/insights/score-row.ts": {
kind: "literal",
why: "the health score is computed in-app on a closed 0-100 scale",
},
// ── Derived from rows already stored ──────────────────────────────────
"lib/measurements/consolidate-daily-mean.ts": {
kind: "derived",
why: "writes the mean of the day's own stored rows",
},
"lib/measurements/consolidate-legacy-steps.ts": {
kind: "derived",
why: "folds stored per-sample step rows into the day's canonical row",
},
"lib/measurements/dense-intraday-retention.ts": {
kind: "derived",
why: "rebuilds hourly buckets from stored per-sample rows",
},
"lib/measurements/drain-per-sample-cumulative.ts": {
kind: "derived",
why: "reduces stored cumulative per-sample rows to one daily total",
},
// ── Restore ───────────────────────────────────────────────────────────
"app/api/admin/backups/[id]/restore/route.ts": {
kind: "restore",
why: "replays the record's own export; dropping rows would break the restore contract",
},
};
/**
* Any Prisma client handle followed by a measurement write. Whitespace- and
* handle-tolerant on purpose: the earlier generation of this repo's guards
* demanded a literal `prisma.x.findUnique(` and went green because it matched
* nothing, not because nothing was there. The transaction handles in use are
* `tx` and `pc`; a future one is caught by the `[A-Za-z_$][\w$]*` head.
*/
const MEASUREMENT_WRITE =
/[A-Za-z_$][\w$]*\s*\.\s*measurement\s*\.\s*(create|createMany|createManyAndReturn|upsert)\s*\(/;
function sourceFiles(): string[] {
return walkSourceFiles(SRC, { floor: 3000 })
.filter((p) => !p.startsWith("generated/"))
.filter((p) => !p.includes("__tests__"))
.filter((p) => !p.endsWith(".test.ts") && !p.endsWith(".test.tsx"))
.sort();
}
function read(rel: string): string {
return readFileSync(join(SRC, rel), "utf8");
}
function discoveredWriters(): string[] {
return sourceFiles().filter((rel) => MEASUREMENT_WRITE.test(read(rel)));
}
describe("every measurement writer declares how it meets the plausibility domain", () => {
it("finds the writers at all — an empty sweep is a broken guard, not a clean repo", () => {
// The map is the claim; this asserts the matcher can still see the
// population it describes. A regex that silently stops matching would
// otherwise turn every check below into a tautology.
expect(discoveredWriters().length).toBeGreaterThanOrEqual(15);
});
it("the discovered writer set matches the declared map exactly", () => {
expect(discoveredWriters()).toEqual(Object.keys(WRITERS).sort());
});
it("every provider-fed writer reaches the gate module", () => {
const gated = Object.entries(WRITERS)
.filter(([, d]) => d.kind === "gate")
.map(([rel]) => rel);
expect(gated.length).toBeGreaterThanOrEqual(6);
for (const rel of gated) {
expect(read(rel), `${rel} must import ${GATE_MODULE}`).toContain(
GATE_MODULE,
);
}
});
it("every person-driven writer calls the range validator", () => {
for (const [rel, disposition] of Object.entries(WRITERS)) {
if (disposition.kind === "validator") {
expect(read(rel), `${rel} must call ${VALIDATOR}`).toContain(VALIDATOR);
}
if (disposition.kind === "upstream") {
expect(
read(disposition.validatedIn),
`${disposition.validatedIn} must call ${VALIDATOR} on behalf of ${rel}`,
).toContain(VALIDATOR);
}
}
});
it("the exempt writers carry a written reason", () => {
for (const [rel, disposition] of Object.entries(WRITERS)) {
if (
disposition.kind === "derived" ||
disposition.kind === "literal" ||
disposition.kind === "restore"
) {
expect(disposition.why.length, `${rel} needs a reason`).toBeGreaterThan(
20,
);
}
}
});
});