feat: lay down the day view and timeline contract

Land every file the day view, the timeline and life events share before
any of them is built, so the server, the day view and the timeline can be
built side by side without editing the same file (#613).

Schema and migration 0387: LifeEvent with a short category list, calendar
start and end dates, a day/month/year precision, encrypted title and note,
a soft-delete tombstone and an index for the per-user live list. Every new
column is annotated for the column-reader sweep. Life events travel in both
backup purposes with their two ends in one file, are wiped with the
account, and are registered for key rotation.

src/lib/day/contract.ts carries the constants and wire types for
GET /api/day/{date}, /api/day/index, /api/timeline, /api/timeline/readiness
and the life-event routes, free of Zod so the navigation chrome can import
it; the schemas beside it feed the routes and the published contract. The
Coach and MCP tool name get_day is reserved there, and life events are
listed as the one section no model ever sees.

The opt-in timeline module, its navigation entry, the day-section and
timeline-lane surfaces, the day and timeline query keys (evicted by every
record data bundle), and stub routes that answer 501 behind their
admissions. The four cross-section reads declare the whole record for now;
the life-event list is a profile read, and life events join the profile
sharing domain and its consent copy in all seven locales. The day,
timeline and lifeEvents message namespaces carry their base copy as
release-pending keys.

The aggregate bundle cap moves to 4400: the branch already measured 4365
against 4335, and the new copy adds 10 KB.

src/app/api/__tests__/module-route-gate-inventory.test.ts

@@ -193,6 +193,11 @@ const MODULE_ROUTE_TREES_BY_KEY: Readonly<
   // data-layer-gated: every `/api/vaccinations/*` route is raw CRUD over the
   // person's own doses, so all six are EXEMPT below under the same reasoning.
   vaccinations: ["src/app/api/vaccinations"],
+  // v1.42 (#613) — the life timeline. The timeline reads and the readiness
+  // inventory gate on `timeline`; the life-event row store beside them is
+  // EXEMPT below under the data-layer reasoning. The day view is not this
+  // module's: it is core and lives under `/api/day`, which no key owns.
+  timeline: ["src/app/api/timeline", "src/app/api/life-events"],
 };
 
 /** Every declared tree, de-duplicated — the set this inventory walks. */
@@ -413,6 +418,14 @@ const EXEMPT_ROUTES: ReadonlyArray<string> = [
   // while the nav entry, the picker and the report leaf hide.
   "src/app/api/vaccinations/[id]/booster/route.ts",
   "src/app/api/vaccinations/suggest/route.ts",
+  // ── DATA LAYER (timeline) ─────────────────────────────────────────
+  // v1.42 (#613) — the record's life events. Raw CRUD over the person's own
+  // rows: the module decides whether they SURFACE (the timeline, the day's
+  // life-event line, the capture entry), not whether the store accepts them.
+  // A restore must bring them back with the module off, and re-enabling must
+  // find every event where it was.
+  "src/app/api/life-events/route.ts",
+  "src/app/api/life-events/[id]/route.ts",
   // ── INFRA / CREDENTIALS (mcp) ─────────────────────────────────────
   // The remote MCP endpoint itself is `src/app/mcp/route.ts`, outside `/api`,
   // and it carries the gate: an account with the module off gets a 404 there

src/app/api/day/[date]/route.ts

@@ -0,0 +1,22 @@
+/**
+ * `GET /api/day/{date}` — one local day across the record (v1.42, #613): what
+ * ran through it, the readings in its window, what happened on it, and the
+ * few deterministic observations worth a second look. The shape is
+ * `DayResponse` in `src/lib/day/contract.ts`.
+ *
+ * Core, not a module: the day opens for every account. Sections of a
+ * switched-off module are left out; a section the caller's grant does not
+ * cover is named in `sections` and not read.
+ *
+ * Contract stub: answers 501 behind its admission. It declares the whole
+ * record for now, the posture every cross-section read in the tree has; a
+ * scoped grant is refused until the loader narrows each section to the
+ * grant's domains and the admission is reviewed for that.
+ */
+import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
+import { notImplemented } from "@/lib/http/not-implemented";
+
+export const GET = apiHandler(async () => {
+  await requireRecordAuth("read", "record");
+  return notImplemented();
+});

src/app/api/day/index/route.ts

@@ -0,0 +1,16 @@
+/**
+ * `GET /api/day/index?from=&to=` — which days in a window hold anything, and
+ * which of them carry a notable observation (v1.42, #613). Feeds the row of
+ * day dots under a chart and the day links in lists; at most
+ * `DAY_INDEX_MAX_SPAN_DAYS` days per call. The shape is `DayIndexResponse` in
+ * `src/lib/day/contract.ts`.
+ *
+ * Contract stub: answers 501 behind the same admission as the day itself.
+ */
+import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
+import { notImplemented } from "@/lib/http/not-implemented";
+
+export const GET = apiHandler(async () => {
+  await requireRecordAuth("read", "record");
+  return notImplemented();
+});

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

@@ -75,6 +75,7 @@ vi.mock("@/lib/db", () => ({
     extractedFact: { findMany: vi.fn().mockResolvedValue([]) },
     ecgRecording: { findMany: vi.fn().mockResolvedValue([]) },
     symptomDefinition: { findMany: vi.fn().mockResolvedValue([]) },
+    lifeEvent: { findMany: vi.fn().mockResolvedValue([]) },
     // v1.15.0 — cycle tables read by the full-backup helper.
     cycleProfile: { findUnique: vi.fn() },
     menstrualCycle: { findMany: vi.fn() },
@@ -171,6 +172,7 @@ beforeEach(() => {
   vi.mocked(prisma.coachReminder.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.ecgRecording.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.symptomDefinition.findMany).mockResolvedValue([] as never);
+  vi.mocked(prisma.lifeEvent.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.moodTagCategory.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.moodTagHidden.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.mentalHealthAssessment.findMany).mockResolvedValue(

src/app/api/export/__tests__/soft-delete-filter.test.ts

@@ -76,6 +76,7 @@ vi.mock("@/lib/db", () => ({
     extractedFact: { findMany: vi.fn() },
     ecgRecording: { findMany: vi.fn() },
     symptomDefinition: { findMany: vi.fn() },
+    lifeEvent: { findMany: vi.fn() },
     onboardingRecord: { findUnique: vi.fn().mockResolvedValue(null) },
     environmentTravelLocation: { findMany: vi.fn().mockResolvedValue([]) },
     environmentContext: { findMany: vi.fn().mockResolvedValue([]) },
@@ -213,6 +214,7 @@ beforeEach(() => {
   vi.mocked(prisma.extractedFact.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.ecgRecording.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.symptomDefinition.findMany).mockResolvedValue([] as never);
+  vi.mocked(prisma.lifeEvent.findMany).mockResolvedValue([] as never);
   vi.mocked(prisma.userAchievement.findMany).mockResolvedValue([] as never);
 });
 
@@ -275,6 +277,12 @@ describe("v1.4.41 W-DELETED-2 — soft-delete invisibility", () => {
         where: { userId: "user-1", deletedAt: null },
       }),
     );
+    // v1.42 — a deleted life event stays out of a portable file.
+    expect(prisma.lifeEvent.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: { userId: "user-1", deletedAt: null },
+      }),
+    );
     // Biomarker + Workout carry no soft-delete tombstone — userId-only scope.
     expect(prisma.biomarker.findMany).toHaveBeenCalledWith(
       expect.objectContaining({ where: { userId: "user-1" } }),

src/app/api/export/encrypted/__tests__/route.test.ts

@@ -67,6 +67,7 @@ vi.mock("@/lib/db", () => ({
     extractedFact: { findMany: vi.fn().mockResolvedValue([]) },
     ecgRecording: { findMany: vi.fn().mockResolvedValue([]) },
     symptomDefinition: { findMany: vi.fn().mockResolvedValue([]) },
+    lifeEvent: { findMany: vi.fn().mockResolvedValue([]) },
     cycleProfile: { findUnique: vi.fn().mockResolvedValue(null) },
     menstrualCycle: { findMany: vi.fn().mockResolvedValue([]) },
     cycleDayLog: { findMany: vi.fn().mockResolvedValue([]) },

src/app/api/life-events/[id]/route.ts

@@ -0,0 +1,21 @@
+/**
+ * `PATCH /api/life-events/{id}` edits one life event; `DELETE` soft-deletes
+ * it (v1.42, #613). Record-scoped like the list beside it.
+ *
+ * Contract stub: owner-only until implemented, then answers 501. The
+ * finished routes resolve the record through `requireRecordAuth` and join
+ * the sharing guard's delegable lists with their audit rows; a stub cannot
+ * carry those, so it does not claim the admission.
+ */
+import { apiHandler, requireAuth } from "@/lib/api-handler";
+import { notImplemented } from "@/lib/http/not-implemented";
+
+export const PATCH = apiHandler(async () => {
+  await requireAuth();
+  return notImplemented();
+});
+
+export const DELETE = apiHandler(async () => {
+  await requireAuth();
+  return notImplemented();
+});

src/app/api/life-events/route.ts

@@ -0,0 +1,26 @@
+/**
+ * `GET /api/life-events` lists the record's life events, oldest first;
+ * `POST` adds one (v1.42, #613). Title and note are encrypted at rest and
+ * never reach a model. Shapes and request schemas in `src/lib/day/`.
+ *
+ * Part of the `profile` sharing domain, beside allergies, visits and the
+ * immunization history. The row store answers whether or not the `timeline`
+ * module is on, the data-layer posture of the other record tables, so a
+ * restore keeps working and re-enabling finds the events intact.
+ *
+ * Contract stub: answers 501. The read declares its final admission; the
+ * create stays owner-only until it files its rows through the audit trail
+ * and joins the delegable write list.
+ */
+import { apiHandler, requireAuth, requireRecordAuth } from "@/lib/api-handler";
+import { notImplemented } from "@/lib/http/not-implemented";
+
+export const GET = apiHandler(async () => {
+  await requireRecordAuth("read", "profile");
+  return notImplemented();
+});
+
+export const POST = apiHandler(async () => {
+  await requireAuth();
+  return notImplemented();
+});

src/app/api/timeline/readiness/route.ts

@@ -0,0 +1,18 @@
+/**
+ * `GET /api/timeline/readiness` — what the timeline can already show, lane by
+ * lane, with one link per gap (v1.42, #613). Counts and keys, never a score.
+ * The shape is `TimelineReadinessResponse` in `src/lib/day/contract.ts`.
+ *
+ * Gated on the opt-in `timeline` module. Contract stub: answers 501 behind
+ * its admission and the gate.
+ */
+import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
+import { notImplemented } from "@/lib/http/not-implemented";
+import { requireModuleEnabled } from "@/lib/modules/gate";
+
+export const GET = apiHandler(async () => {
+  const { user } = await requireRecordAuth("read", "record");
+  const gate = await requireModuleEnabled(user.id, "timeline");
+  if (!gate.enabled) return gate.response;
+  return notImplemented();
+});

src/app/api/timeline/route.ts

@@ -0,0 +1,20 @@
+/**
+ * `GET /api/timeline?zoom=&from=&to=&values=` — the record laid out over the
+ * years (v1.42, #613): lanes of conditions, medications, visits, documents and
+ * life events, the standing items without a start, and monthly value series.
+ * The shape is `TimelineResponse` in `src/lib/day/contract.ts`.
+ *
+ * Gated on the opt-in `timeline` module. Contract stub: answers 501 behind
+ * its admission and the gate. Like the day, it declares the whole record
+ * until each lane is narrowed to the grant's domains.
+ */
+import { apiHandler, requireRecordAuth } from "@/lib/api-handler";
+import { notImplemented } from "@/lib/http/not-implemented";
+import { requireModuleEnabled } from "@/lib/modules/gate";
+
+export const GET = apiHandler(async () => {
+  const { user } = await requireRecordAuth("read", "record");
+  const gate = await requireModuleEnabled(user.id, "timeline");
+  if (!gate.enabled) return gate.response;
+  return notImplemented();
+});