feat(cycle): import Apple Health reproductive data into cycle, add cycle export

Promote the reproductive HealthKit category types out of the
Apple-Health-import privacy-hold list and route them into cycle day-logs
instead of measurements, and surface cycle data on the three export
surfaces.

Import promotion:
- A new HealthKit -> cycle mapping module is the single source of truth for
  how MenstrualFlow, IntermenstrualBleeding, CervicalMucusQuality,
  OvulationTestResult, SexualActivity, PregnancyTestResult,
  ProgesteroneTestResult, Contraceptive and the symptom category types fold
  into CycleDayLog fields / seeded symptom keys. The XML importer
  accumulates same-day reproductive samples and writes one canonical
  day-log per day with source APPLE_HEALTH and a synthetic per-day
  externalId for idempotent re-import. The fold is gated on cycle tracking
  being enabled, so a non-cycle export never provisions cycle rows. A
  contraceptive method nudges the profile goal toward avoiding pregnancy
  only when the goal is still on its default. Basal body temperature stays
  a measurement and mirrors onto the day-log. Pregnancy/Lactation status
  and the pregnancy-bleeding types stay deferred; the cycle awareness types
  remain server-derived.

Export:
- FHIR emits LMP (LOINC 8665-2), average cycle length (64700-8), period
  length (64698-4) and the current phase as opt-in reproductive-health
  observations grouped into their own document section.
- The doctor PDF gains an opt-in cycle section (recent cycles, average
  length and variability, current phase), privacy-default off like mood.
- The full-backup export, the weekly backup worker and the off-host DR
  snapshot include the cycle tables, and the admin restore re-creates them;
  the day-log note round-trips as ciphertext and is never decrypted onto a
  report surface.

Mapping table documented in docs/api/cycle-healthkit-mapping.md. Adds unit
+ integration coverage for the mapping, the import routing, the FHIR
observations and the backup round-trip. OpenAPI regenerated. Six-locale
strings added.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/app/api/admin/backups/[id]/restore/route.ts

@@ -49,6 +49,7 @@ import {
   MEDICATION_COMPLIANCE_BACKFILL_DAYS,
 } from "@/lib/rollups/medication-compliance-rollups";
 import { recomputeUserRollups } from "@/lib/rollups/measurement-rollups";
+import { restoreCycleData } from "@/lib/cycle/backup";
 
 export const dynamic = "force-dynamic";
 
@@ -63,6 +64,10 @@ interface RestoreResponse {
     notificationChannels: number;
     pushSubscriptions: number;
     telegramScheduledDeletions: number;
+    // v1.15.0 — cycle tables wiped before recreate.
+    cycles: number;
+    cycleDayLogs: number;
+    cycleProfile: number;
   };
 }
 
@@ -397,6 +402,11 @@ const handler = apiHandler(
           });
         }
 
+        // v1.15.0 — cycle tables (profile + observed spans + day-logs +
+        // symptom links). Delete-then-recreate, mirroring the contract
+        // above. `notesEncrypted` is restored as ciphertext verbatim.
+        const cycleCleared = await restoreCycleData(tx, ownerId, payload);
+
         return {
           measurements: measurements.count,
           medications: meds.count,
@@ -405,6 +415,9 @@ const handler = apiHandler(
           notificationChannels: channels.count,
           pushSubscriptions: subs.count,
           telegramScheduledDeletions: tgDel.count,
+          cycles: cycleCleared.cycles,
+          cycleDayLogs: cycleCleared.cycleDayLogs,
+          cycleProfile: cycleCleared.cycleProfile,
         };
       });
     } catch (err) {
@@ -513,6 +526,8 @@ const handler = apiHandler(
           medications: summary.medications,
           intakeEvents: summary.intakeEvents,
           moodEntries: summary.moodEntries,
+          cycles: summary.cycles,
+          cycleDayLogs: summary.cycleDayLogs,
         },
       },
     });

src/app/api/admin/backups/upload/route.ts

@@ -216,6 +216,8 @@ export const POST = apiHandler(async (request: NextRequest) => {
         medications: summary.medications,
         intakeEvents: summary.intakeEvents,
         moodEntries: summary.moodEntries,
+        cycles: summary.cycles,
+        cycleDayLogs: summary.cycleDayLogs,
       },
     },
   });

src/app/api/auth/me/doctor-report-prefs/__tests__/route.test.ts

@@ -90,6 +90,7 @@ describe("PUT /api/auth/me/doctor-report-prefs", () => {
       mood: true,
       compliance: true,
       sleep: false,
+      cycle: false,
     };
     const res = await (PUT as (r: Request) => Promise<Response>)(mkPut(body));
     expect(res.status).toBe(200);
@@ -112,6 +113,7 @@ describe("PUT /api/auth/me/doctor-report-prefs", () => {
       mood: true,
       compliance: false,
       sleep: false,
+      cycle: false,
     };
     vi.mocked(prisma.user.findUnique).mockResolvedValue({
       doctorReportPrefsJson: current,

src/app/api/export/__tests__/per-type-routes.test.ts

@@ -16,6 +16,10 @@ vi.mock("@/lib/db", () => ({
     medication: { findMany: vi.fn() },
     medicationIntakeEvent: { findMany: vi.fn() },
     moodEntry: { findMany: vi.fn() },
+    // v1.15.0 — cycle tables read by the full-backup helper.
+    cycleProfile: { findUnique: vi.fn() },
+    menstrualCycle: { findMany: vi.fn() },
+    cycleDayLog: { findMany: vi.fn() },
     user: { findUnique: vi.fn() },
     auditLog: { create: vi.fn() },
   },
@@ -318,6 +322,9 @@ describe("GET /api/export/full-backup", () => {
       [] as never,
     );
     vi.mocked(prisma.moodEntry.findMany).mockResolvedValue([] as never);
+    vi.mocked(prisma.cycleProfile.findUnique).mockResolvedValue(null as never);
+    vi.mocked(prisma.menstrualCycle.findMany).mockResolvedValue([] as never);
+    vi.mocked(prisma.cycleDayLog.findMany).mockResolvedValue([] as never);
 
     const { GET } = await import("../full-backup/route");
     const res = await GET(mkReq("http://localhost/api/export/full-backup"));

src/app/api/export/full-backup/route.ts

@@ -22,6 +22,7 @@ import { auditLog } from "@/lib/auth/audit";
 import { apiError, getClientIp } from "@/lib/api-response";
 import { checkRateLimit } from "@/lib/rate-limit";
 import { BACKUP_SCHEMA_VERSION } from "@/lib/validations/backup";
+import { buildCycleBackupSection } from "@/lib/cycle/backup";
 import { NextRequest, NextResponse } from "next/server";
 
 export const GET = apiHandler(async (request: NextRequest) => {
@@ -33,7 +34,7 @@ export const GET = apiHandler(async (request: NextRequest) => {
     return apiError("Maximum 10 exports per hour", 429);
   }
 
-  const [measurements, medications, intakeEvents, moodEntries] =
+  const [measurements, medications, intakeEvents, moodEntries, cycle] =
     await Promise.all([
       prisma.measurement.findMany({
         // v1.4.41 W-DELETED-2 — soft-deleted rows are excluded from the
@@ -74,6 +75,9 @@ export const GET = apiHandler(async (request: NextRequest) => {
         where: { userId: user.id, deletedAt: null },
         orderBy: { moodLoggedAt: "desc" },
       }),
+      // v1.15.0 — cycle tables (profile + observed spans + day-logs). The
+      // shared helper carries `notesEncrypted` verbatim (never decrypted).
+      buildCycleBackupSection(prisma, user.id),
     ]);
 
   // Shape mirrors the pg-boss `data-backup` worker exactly so the same
@@ -118,6 +122,10 @@ export const GET = apiHandler(async (request: NextRequest) => {
       source: e.source,
       loggedAt: e.moodLoggedAt.toISOString(),
     })),
+    // v1.15.0 — cycle slice (profile + observed spans + day-logs).
+    cycleProfile: cycle.cycleProfile,
+    cycles: cycle.cycles,
+    cycleDayLogs: cycle.cycleDayLogs,
   };
 
   await auditLog("user.export.full-backup", {
@@ -129,6 +137,8 @@ export const GET = apiHandler(async (request: NextRequest) => {
         medications: medications.length,
         intakeEvents: intakeEvents.length,
         moodEntries: moodEntries.length,
+        cycles: cycle.cycles.length,
+        cycleDayLogs: cycle.cycleDayLogs.length,
       },
     },
   });
@@ -139,6 +149,8 @@ export const GET = apiHandler(async (request: NextRequest) => {
       export_medications_count: medications.length,
       export_intake_count: intakeEvents.length,
       export_mood_count: moodEntries.length,
+      export_cycle_count: cycle.cycles.length,
+      export_cycle_day_log_count: cycle.cycleDayLogs.length,
     },
   });