feat(encounters): the lab moment, the condition side, and closing a checkup

A lab panel files itself against the visit it came from, and never has to. The
OCR review and the manual form both offer the suggestion through the one shared
field, anchored on the draw date rather than on now, so backdating a reading
moves the offer with it. The commit writes one link PER RESULT ROW, which is
why the join is m:n: a marker re-run on a different day belongs to its own
visit. Best-effort by design — the readings are the write that matters and must
not be lost to a link that could not be made.

The condition side gets a Visits about this card with an action that pre-links
the episode. From the episode side only, and that is a decision: an episode
spans weeks and a visit is a point, so matching the other way would be wrong
often enough to teach a person to ignore every suggestion in the product.

A due checkup gains a second action beside erledigt. Filing the visit as done
satisfies the checkup through the same forward-only, idempotent primitive the
checkbox uses, so doing both is one satisfaction and no error. The two actions
answer different questions — one says it happened, the other says where.

An appointment now appears where a person looks, and NEITHER surface relaxes
the reminder-table exclusion that keeps it out of the preventive-care lists.
Both read the visit table: a quiet line under the dashboard checkup block for
anything inside two weeks, and one rail item for today or tomorrow. A diff in
either that touches origin is the wrong fix.

A visit write now also refreshes the reminder reads. Closing a checkup moves
its next-due date on three surfaces that would otherwise keep showing it due
until their own poll.

OpenAPI regenerated in the same commit.

src/app/api/encounters/route.ts

@@ -58,6 +58,7 @@ export const GET = apiHandler(async (request: NextRequest) => {
     to: params.get("to") ?? undefined,
     status: params.get("status") ?? undefined,
     practitionerId: params.get("practitionerId") ?? undefined,
+    episodeId: params.get("episodeId") ?? undefined,
     limit: params.get("limit") ?? undefined,
   });
   if (!parsed.success) {
@@ -75,6 +76,11 @@ export const GET = apiHandler(async (request: NextRequest) => {
     deletedAt: null,
     ...(query.status ? { status: query.status } : {}),
     ...(query.practitionerId ? { practitionerId: query.practitionerId } : {}),
+    // Filtered in SQL rather than in Node: the two arms are separately
+    // `take`-bounded, so narrowing after the read would page wrongly.
+    ...(query.episodeId
+      ? { conditionLinks: { some: { episodeId: query.episodeId } } }
+      : {}),
     ...(query.from || query.to
       ? {
           occurredAt: {

src/app/api/labs/ocr/commit/route.ts

@@ -39,6 +39,7 @@ import {
   linkOcrLabsToVaultDocument,
   type InsertedLabForLink,
 } from "@/lib/labs/vault-link";
+import { linkTargets } from "@/lib/links";
 import { annotate } from "@/lib/logging/context";
 import { classifyWrittenOutcome } from "@/lib/outcome/written-outcome";
 import {
@@ -217,6 +218,23 @@ async function commitOcrRows(request: NextRequest) {
     ).catch(() => {});
   }
 
+  // The visit the review step offered, if it offered one. ONE LINK PER RESULT
+  // ROW rather than one for the panel: a marker re-run on a different day
+  // belongs to its own visit, which is exactly why the join is m:n and not a
+  // scalar column on the result. Best-effort like the vault cross-link — the
+  // readings are the authoritative write and must not be lost to a link that
+  // could not be made. The link service narrows both ends to this record, so
+  // an id naming nothing writes nothing.
+  if (parsed.data.encounterId && linkable.length > 0) {
+    await linkTargets(prisma, {
+      userId: user.id,
+      sourceKind: "encounter",
+      sourceId: parsed.data.encounterId,
+      targetKind: "labResult",
+      targetIds: linkable.map((row) => row.labResultId),
+    }).catch(() => {});
+  }
+
   await auditLog("labs.ocr.commit", {
     userId: user.id,
     ipAddress: getClientIp(request),
@@ -225,7 +243,11 @@ async function commitOcrRows(request: NextRequest) {
 
   annotate({
     action: { name: "labs.ocr.committed" },
-    meta: { inserted: inserted.length, skipped: skipped.length },
+    meta: {
+      inserted: inserted.length,
+      skipped: skipped.length,
+      linkedVisit: parsed.data.encounterId ? 1 : 0,
+    },
   });
 
   // A lab panel just landed — resolve any "annual blood panel" reminders now

src/app/api/labs/route.ts

@@ -21,6 +21,7 @@ import {
   type ResolvedBiomarker,
   serialiseLabResult,
 } from "@/lib/labs/serialise";
+import { linkTargets } from "@/lib/links";
 import { encryptNoteToBytes } from "@/lib/labs/store";
 import { annotate } from "@/lib/logging/context";
 import {
@@ -190,6 +191,7 @@ async function postLabResult(request: NextRequest) {
     takenAt,
     note,
     source,
+    encounterId,
   } = parsed.data;
 
   // v1.18.9 — a qualitative reading carries `valueText` ("negativ" / …) instead
@@ -267,6 +269,21 @@ async function postLabResult(request: NextRequest) {
       noteEncrypted: note ? encryptNoteToBytes(note) : null,
     },
   });
+  // The by-the-way half: file the reading against the visit the form offered,
+  // if it offered one. Best-effort by design — the reading is the write that
+  // matters, and a link that could not be made (a visit deleted between the
+  // suggestion and the save) must not lose it. The link service narrows both
+  // ends to this record, so an id naming nothing simply writes nothing.
+  if (encounterId) {
+    await linkTargets(prisma, {
+      userId: user.id,
+      sourceKind: "encounter",
+      sourceId: encounterId,
+      targetKind: "labResult",
+      targetIds: [created.id],
+    }).catch(() => {});
+  }
+
   invalidateUserHealthScore(user.id);
   const dto = serialiseLabResult(created, biomarker);