one source of truth for Route/Activity shapes; enforce api contracts

Route and Activity existed three times: hand-written interfaces in
packages/types, Zod contracts in packages/api, and Drizzle columns in
packages/db — each with different fields and nullability. The
hand-written ones had drifted so far they had zero importers; the Zod
contracts were advisory because v1 handlers hand-rolled Response.json
shapes nothing validated.

- packages/types keeps only what both apps actually share (Waypoint,
  WaypointPoiTags) and documents where row types and wire contracts
  live; the dead Route/RouteMetadata/RouteVersion/Activity interfaces
  are gone
- packages/db exports canonical inferred row types (RouteRow,
  ActivityRow, RouteVersionRow, UserRow)
- packages/api contracts are reconciled with the real wire format
  (RouteVersionSchema gains the id and createdBy fields the endpoint
  has always returned) and gain Create*ResponseSchemas
- apiJson(schema, payload) in api-guard parses every v1 response
  through its contract: drift is now a thrown ZodError in tests/CI,
  unknown keys are stripped, and payloads are compile-checked as
  z.input of the schema

Enforcement immediately caught two real drifts: nullable DB
descriptions could ship null where the contract promises string (now
coalesced at the boundary), and GET /api/v1/activities/:id was missing
the routeName and photos fields its contract declares.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

packages/api/src/activities.ts

@@ -39,7 +39,11 @@ export const CreateActivityRequestSchema = z.object({
   distance: z.number().optional(),
 });
 
+/** Response to POST /api/v1/activities */
+export const CreateActivityResponseSchema = z.object({ id: z.uuid() });
+
 export type ActivitySummary = z.infer<typeof ActivitySummarySchema>;
+export type CreateActivityResponse = z.infer<typeof CreateActivityResponseSchema>;
 export type ActivityDetail = z.infer<typeof ActivityDetailSchema>;
 export type ActivityListResponse = z.infer<typeof ActivityListResponseSchema>;
 export type CreateActivityRequest = z.infer<typeof CreateActivityRequestSchema>;

packages/api/src/index.ts

@@ -33,10 +33,12 @@ export {
   RouteSummarySchema, RouteDetailSchema, RouteVersionSchema,
   RouteListResponseSchema,
   CreateRouteRequestSchema, UpdateRouteRequestSchema,
+  CreateRouteResponseSchema,
   ComputeRouteRequestSchema,
   type RouteSummary, type RouteDetail, type RouteVersion,
   type RouteListResponse,
   type CreateRouteRequest, type UpdateRouteRequest,
+  type CreateRouteResponse,
   type ComputeRouteRequest,
 } from "./routes.ts";
 
@@ -44,10 +46,10 @@ export {
 export {
   ActivitySummarySchema, ActivityDetailSchema,
   ActivityListResponseSchema,
-  CreateActivityRequestSchema,
+  CreateActivityRequestSchema, CreateActivityResponseSchema,
   type ActivitySummary, type ActivityDetail,
   type ActivityListResponse,
-  type CreateActivityRequest,
+  type CreateActivityRequest, type CreateActivityResponse,
 } from "./activities.ts";
 
 // Uploads

packages/api/src/routes.ts

@@ -17,7 +17,9 @@ export const RouteSummarySchema = z.object({
 
 /** Route version info */
 export const RouteVersionSchema = z.object({
+  id: z.uuid(),
   version: z.number(),
+  createdBy: z.string().nullable(),
   changeDescription: z.string().nullable(),
   createdAt: z.iso.datetime(),
 });
@@ -64,7 +66,11 @@ export const ComputeRouteRequestSchema = z.object({
   })).optional(),
 });
 
+/** Response to POST /api/v1/routes */
+export const CreateRouteResponseSchema = z.object({ id: z.uuid() });
+
 export type RouteSummary = z.infer<typeof RouteSummarySchema>;
+export type CreateRouteResponse = z.infer<typeof CreateRouteResponseSchema>;
 export type RouteVersion = z.infer<typeof RouteVersionSchema>;
 export type RouteDetail = z.infer<typeof RouteDetailSchema>;
 export type RouteListResponse = z.infer<typeof RouteListResponseSchema>;

packages/db/src/schema/journal.ts

@@ -463,3 +463,13 @@ export const consumedJwtJti = journalSchema.table("consumed_jwt_jti", {
   // Sweep runs `DELETE WHERE expires_at < now()` on a daily schedule.
   expiresAtIdx: index("consumed_jwt_jti_expires_at_idx").on(t.expiresAt),
 }));
+
+// ---------------------------------------------------------------------------
+// Canonical row types — derive from the schema, never re-declare by hand.
+// API wire shapes live in @trails-cool/api; these are the database truth.
+// ---------------------------------------------------------------------------
+
+export type RouteRow = typeof routes.$inferSelect;
+export type RouteVersionRow = typeof routeVersions.$inferSelect;
+export type ActivityRow = typeof activities.$inferSelect;
+export type UserRow = typeof users.$inferSelect;

packages/types/src/index.ts

@@ -1,7 +1,13 @@
 /**
- * Shared TypeScript types for trails.cool
+ * Shared TypeScript types for trails.cool — the Waypoint wire format
+ * used by both the Planner and Journal apps (Yjs document, GPX
+ * extensions, handoff payloads).
  *
- * These types are used by both the Planner and Journal apps.
+ * Not here on purpose: database row types are derived from the Drizzle
+ * schema (@trails-cool/db, e.g. RouteRow), and API response shapes are
+ * the Zod contracts in @trails-cool/api. Earlier hand-written Route /
+ * Activity interfaces in this file drifted from both and had zero
+ * importers when they were removed.
  */
 
 export interface WaypointPoiTags {
@@ -26,48 +32,3 @@ export interface Waypoint {
   osmId?: number;
   poiTags?: WaypointPoiTags;
 }
-
-export interface RouteMetadata {
-  created: Date;
-  updated: Date;
-  owner: string;
-  contributors: string[];
-  routingProfile: string;
-  dayBreaks: number[];
-  distance: number;
-  elevation: {
-    gain: number;
-    loss: number;
-  };
-  tags: string[];
-}
-
-export interface Route {
-  id: string;
-  name: string;
-  description: string;
-  gpx: string;
-  metadata: RouteMetadata;
-  plannerState?: Uint8Array;
-  versions: RouteVersion[];
-}
-
-export interface RouteVersion {
-  version: number;
-  gpx: string;
-  createdAt: Date;
-  createdBy: string;
-  changeDescription?: string;
-}
-
-export interface Activity {
-  id: string;
-  routeId?: string;
-  name: string;
-  description: string;
-  gpx: string;
-  startedAt: Date;
-  duration: number;
-  photos: string[];
-  participants: string[];
-}