feat: complete TASK-WP0-02 contract baseline

apps/api/package.json

@@ -9,6 +9,7 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
+    "@dada/shared-contracts": "workspace:*",
     "@fastify/swagger": "9.8.1",
     "@sinclair/typebox": "0.34.52",
     "better-sqlite3": "13.0.1",

apps/api/src/app.ts

@@ -1,17 +1,140 @@
+import { randomUUID } from "node:crypto";
+
+import {
+  BootstrapResponseSchema,
+  CorrelationIdSchema,
+  ErrorDetailsSchema,
+  ErrorEnvelopeSchema,
+  GenerationErrorCategorySchema,
+  ModelConfigSseEventSchema,
+  ModelRuntimeSseEventSchema,
+  SseEventSchema,
+  StableEngineeringErrorCodeSchema,
+  StateSseEventSchema,
+  isCorrelationId,
+  type BootstrapResponse,
+} from "@dada/shared-contracts";
 import swagger from "@fastify/swagger";
 import Fastify from "fastify";
 
-export function createApp() {
-  const app = Fastify({ logger: false });
+import { EventHub } from "./event-hub.js";
 
-  void app.register(swagger, {
+const defaultBootstrap: BootstrapResponse = {
+  app_version: "0.0.0",
+  dependencies: [],
+  model_summary: {
+    config_set_version: null,
+    configured_default_model_id: null,
+    recommended_model_id: null,
+    runtime_availability_version: null,
+  },
+  public_features: [],
+};
+
+export interface CreateAppOptions {
+  bootstrap?: () => BootstrapResponse | Promise<BootstrapResponse>;
+  eventHub?: EventHub;
+}
+
+function requestCorrelationId(headers: Record<string, string | string[] | undefined>) {
+  const header = headers["x-correlation-id"];
+  const candidate = Array.isArray(header) ? header[0] : header;
+  return isCorrelationId(candidate) ? candidate : randomUUID();
+}
+
+export async function createApp(options: CreateAppOptions = {}) {
+  const eventHub = options.eventHub ?? new EventHub();
+  const bootstrap = options.bootstrap ?? (() => defaultBootstrap);
+  const app = Fastify({
+    genReqId: (request) => requestCorrelationId(request.headers),
+    logger: false,
+  });
+
+  await app.register(swagger, {
     openapi: {
       info: {
         title: "Dada P0-A",
         version: "0.0.0",
       },
+      openapi: "3.1.0",
+    },
+    refResolver: {
+      buildLocalReference: (schema, _baseUri, _fragment, index) =>
+        typeof schema.$id === "string" ? schema.$id : `schema-${index}`,
     },
   });
 
+  for (const schema of [
+    CorrelationIdSchema,
+    GenerationErrorCategorySchema,
+    StableEngineeringErrorCodeSchema,
+    ErrorDetailsSchema,
+    ErrorEnvelopeSchema,
+    BootstrapResponseSchema,
+    StateSseEventSchema,
+    ModelConfigSseEventSchema,
+    ModelRuntimeSseEventSchema,
+    SseEventSchema,
+  ]) {
+    app.addSchema(schema);
+  }
+
+  app.addHook("onRequest", (request, reply, done) => {
+    reply.header("X-Correlation-Id", request.id);
+    done();
+  });
+
+  app.get(
+    "/api/v1/bootstrap",
+    {
+      schema: {
+        operationId: "getBootstrap",
+        response: {
+          200: BootstrapResponseSchema,
+        },
+        tags: ["Bootstrap"],
+      },
+    },
+    async () => bootstrap(),
+  );
+
+  app.get(
+    "/api/v1/events",
+    {
+      schema: {
+        operationId: "getEvents",
+        response: {
+          200: {
+            content: {
+              "text/event-stream": {
+                schema: SseEventSchema,
+              },
+            },
+            description: "Non-sensitive state change hints. REST remains authoritative.",
+          },
+        },
+        tags: ["State events"],
+      },
+    },
+    (request, reply) => {
+      reply.hijack();
+      reply.raw.setHeader("Cache-Control", "no-store");
+      reply.raw.setHeader("Connection", "keep-alive");
+      reply.raw.setHeader("Content-Type", "text/event-stream; charset=utf-8");
+      reply.raw.setHeader("X-Correlation-Id", request.id);
+      reply.raw.writeHead(200);
+      reply.raw.write(": connected\n\n");
+
+      const unsubscribe = eventHub.connect(
+        (event) => {
+          reply.raw.write(`id: ${event.event_id}\n`);
+          reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
+        },
+        () => reply.raw.end(),
+      );
+      request.raw.once("close", unsubscribe);
+    },
+  );
+
   return app;
 }

apps/api/src/event-hub.ts

@@ -0,0 +1,31 @@
+import { isSseEvent, type SseEvent } from "@dada/shared-contracts";
+
+interface Connection {
+  close: () => void;
+  send: (event: SseEvent) => void;
+}
+
+export class EventHub {
+  readonly #connections = new Set<Connection>();
+
+  get subscriberCount() {
+    return this.#connections.size;
+  }
+
+  connect(send: Connection["send"], close: Connection["close"]) {
+    const connection = { close, send };
+    this.#connections.add(connection);
+    return () => this.#connections.delete(connection);
+  }
+
+  publish(event: SseEvent) {
+    if (!isSseEvent(event)) throw new Error("SSE event does not match the frozen non-sensitive schema.");
+    for (const connection of this.#connections) connection.send(event);
+  }
+
+  disconnectAll() {
+    const connections = [...this.#connections];
+    this.#connections.clear();
+    for (const connection of connections) connection.close();
+  }
+}

apps/api/src/main.ts

@@ -1,6 +1,6 @@
 import { createApp } from "./app.js";
 
-const app = createApp();
+const app = await createApp();
 
 await app.listen({
   host: "127.0.0.1",