@critical-path/server 0.15.0 → 0.17.0

package/src/index.test.ts

@@ -111,7 +111,7 @@ describe('@critical-path/server Router Tests', () => {
     const postCmtReq = new Request(`http://localhost:3000/api/critical-path/tasks/${task.id}/comments`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ content: 'Root comment', authorId: 'u1', authorType: 'user' })
+      body: JSON.stringify({ content: 'Root comment' })
     });
     const postCmtRes = await router.handleRequest(postCmtReq);
     expect(postCmtRes.status).toBe(201);
@@ -146,8 +146,7 @@ describe('@critical-path/server Router Tests', () => {
         mimeType: 'text/markdown',
         sizeBytes: 100,
         taskId: task.id,
-        projectId: proj.id,
-        uploaderId: 'u1'
+        projectId: proj.id
       })
     });
     const postAttRes = await router.handleRequest(postAttReq);
@@ -183,8 +182,7 @@ describe('@critical-path/server Router Tests', () => {
       body: JSON.stringify({
         filename: 'huge.pdf',
         url: `data:application/pdf;base64,${'B'.repeat(3000)}`,
-        taskId: task.id,
-        uploaderId: 'u1'
+        taskId: task.id
       })
     });
     const invalidAttRes = await router.handleRequest(invalidAttReq);
@@ -203,29 +201,29 @@ describe('@critical-path/server Router Tests', () => {
     const addReactReq = new Request(`http://localhost:3000/api/critical-path/comments/${comment.id}/reactions`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ emoji: '❤️', userId: 'u2' })
+      body: JSON.stringify({ emoji: '❤️' })
     });
     const addReactRes = await router.handleRequest(addReactReq);
     expect(addReactRes.status).toBe(200);
     const addReactData = await addReactRes.json();
     expect(addReactData.comment.reactions).toHaveLength(1);
     expect(addReactData.comment.reactions[0].emoji).toBe('❤️');
+    expect(addReactData.comment.reactions[0].userId).toBe('anonymous');
 
-    // 2. Add reaction validation error (missing emoji or userId)
+    // 2. Add reaction validation error (missing emoji, or identity claimed in the body)
     const badReactReq = new Request(`http://localhost:3000/api/critical-path/comments/${comment.id}/reactions`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ emoji: '❤️' })
+      body: JSON.stringify({ emoji: '❤️', userId: 'u2' })
     });
     const badReactRes = await router.handleRequest(badReactReq);
     expect(badReactRes.status).toBe(400);
 
     // 3. Remove reaction via DELETE
-    const delReactReq = new Request(`http://localhost:3000/api/critical-path/comments/${comment.id}/reactions`, {
-      method: 'DELETE',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ emoji: '❤️', userId: 'u2' })
-    });
+    const delReactReq = new Request(
+      `http://localhost:3000/api/critical-path/comments/${comment.id}/reactions?emoji=${encodeURIComponent('❤️')}`,
+      { method: 'DELETE' }
+    );
     const delReactRes = await router.handleRequest(delReactReq);
     expect(delReactRes.status).toBe(200);
     const delReactData = await delReactRes.json();
@@ -483,11 +481,16 @@ describe('@critical-path/server Router Tests', () => {
       }
     });
 
-    it('answers CORS preflight requests', async () => {
-      const router = new CriticalPathRouter();
-      const res = await router.handleRequest(new Request(`${base}/tasks`, { method: 'OPTIONS' }));
-      expect(res.status).toBe(204);
-      expect(res.headers.get('Access-Control-Allow-Methods')).toContain('PATCH');
+    it('answers CORS preflight requests, sending CORS headers only when configured', async () => {
+      const preflight = () => new Request(`${base}/tasks`, { method: 'OPTIONS', headers: { Origin: 'https://x.test' } });
+
+      const closed = await new CriticalPathRouter().handleRequest(preflight());
+      expect(closed.status).toBe(204);
+      expect(closed.headers.get('Access-Control-Allow-Origin')).toBeNull();
+
+      const open = await new CriticalPathRouter(undefined, { cors: { origins: '*' } }).handleRequest(preflight());
+      expect(open.headers.get('Access-Control-Allow-Origin')).toBe('*');
+      expect(open.headers.get('Access-Control-Allow-Methods')).toContain('PATCH');
     });
   });
 
@@ -500,7 +503,7 @@ describe('@critical-path/server Router Tests', () => {
     expect((await GET(req())).status).toBe(200);
   });
 
-  it('updates projects via PATCH without allowing id or timestamp overrides', async () => {
+  it('updates projects via PATCH and rejects id or timestamp overrides', async () => {
     const router = new CriticalPathRouter();
     const proj = await router.engine.createProject({ key: 'UPD', name: 'Before' });
     const patch = (id: string, body: unknown) =>
@@ -512,7 +515,10 @@ describe('@critical-path/server Router Tests', () => {
         })
       );
 
-    const res = await patch(proj.id, { name: 'After', id: 'hijacked', createdAt: '1999-01-01T00:00:00.000Z' });
+    expect((await patch(proj.id, { name: 'After', id: 'hijacked' })).status).toBe(400);
+    expect((await patch(proj.id, { name: 'After', createdAt: '1999-01-01T00:00:00.000Z' })).status).toBe(400);
+
+    const res = await patch(proj.id, { name: 'After' });
     expect(res.status).toBe(200);
     const { project } = await res.json();
     expect(project.id).toBe(proj.id);
@@ -632,7 +638,7 @@ describe('@critical-path/server Router Tests', () => {
       expect((await call(router, '/projects', { method: 'OPTIONS' })).status).toBe(204);
     });
 
-    it('attributes mutations to the context user and ignores identity in bodies', async () => {
+    it('attributes mutations to the context user', async () => {
       const router = new CriticalPathRouter(undefined, { getContext: tokenContext });
       const project = await router.engine.createProject({ key: 'CTX', name: 'Context' });
       const task = await router.engine.createTask({ projectId: project.id, title: 'T' });
@@ -640,14 +646,14 @@ describe('@critical-path/server Router Tests', () => {
       const patched = await call(router, `/tasks/${task.id}`, {
         method: 'PATCH',
         token: 'alice',
-        body: JSON.stringify({ title: 'Renamed', actorId: 'ceo', actorName: 'CEO' })
+        body: JSON.stringify({ title: 'Renamed' })
       });
       expect(patched.status).toBe(200);
 
       const commented = await call(router, `/tasks/${task.id}/comments`, {
         method: 'POST',
         token: 'alice',
-        body: JSON.stringify({ content: 'hi', authorId: 'ceo' })
+        body: JSON.stringify({ content: 'hi' })
       });
       const { comment } = await commented.json();
       expect(comment.authorId).toBe('alice');
@@ -727,7 +733,7 @@ describe('@critical-path/server Router Tests', () => {
         new Request(`http://localhost/api/critical-path/tasks/${task.id}/comments`, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify({ content: 'from svelte', authorId: 'spoofed' })
+          body: JSON.stringify({ content: 'from svelte' })
         });
 
       expect((await POST({ request: commentReq(), locals: {} })).status).toBe(401);
@@ -752,5 +758,91 @@ describe('@critical-path/server Router Tests', () => {
       expect((await handle(new Request('http://localhost/other/projects'))).status).toBe(404);
     });
   });
+
+  describe('request body validation', () => {
+    const send = (router: CriticalPathRouter, method: string, path: string, body: unknown, token?: string) =>
+      router.handleRequest(
+        new Request(`http://localhost:3000/api/critical-path${path}`, {
+          method,
+          headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+          body: JSON.stringify(body)
+        })
+      );
+
+    it('rejects attempts to move tasks or rewrite server-assigned fields', async () => {
+      const router = new CriticalPathRouter();
+      const home = await router.engine.createProject({ key: 'HOME', name: 'Home' });
+      const other = await router.engine.createProject({ key: 'OTH', name: 'Other' });
+      const task = await router.engine.createTask({ projectId: home.id, title: 'Stay' });
+
+      const res = await send(router, 'PATCH', `/tasks/${task.id}`, {
+        title: 'Renamed',
+        projectId: other.id,
+        id: 'hijacked',
+        createdAt: '1999-01-01T00:00:00.000Z',
+        injected: '<script>'
+      });
+      expect(res.status).toBe(400);
+      const { issues } = await res.json();
+      expect(issues[0].message).toMatch(/Unrecognized key/);
+      expect(issues[0].message).toMatch(/projectId/);
+
+      const stored = await router.engine.getTask(task.id);
+      expect(stored?.title).toBe('Stay');
+      expect(stored?.projectId).toBe(home.id);
+    });
+
+    it('returns 400 with field-level issues for invalid bodies', async () => {
+      const router = new CriticalPathRouter();
+      const project = await router.engine.createProject({ key: 'VAL', name: 'Validation' });
+
+      const res = await send(router, 'POST', '/tasks', { projectId: project.id, title: '', progress: 'half' });
+      expect(res.status).toBe(400);
+      const data = await res.json();
+      expect(data.issues.map((i: { path: string }) => i.path).sort()).toEqual(['progress', 'title']);
+
+      expect((await send(router, 'POST', '/projects', [])).status).toBe(400);
+      expect((await send(router, 'POST', '/iterations', { projectId: project.id, name: 'S1', status: 'later' })).status).toBe(400);
+    });
+
+    it('takes authorship from the caller (or anonymous), never the body, and path ids win', async () => {
+      const router = new CriticalPathRouter(undefined, {
+        getContext: (request) => {
+          const token = request.headers.get('Authorization')?.replace('Bearer ', '');
+          return token ? { userId: token } : null;
+        }
+      });
+      const project = await router.engine.createProject({ key: 'AUT', name: 'Authors' });
+      const task = await router.engine.createTask({ projectId: project.id, title: 'T' });
+      const decoy = await router.engine.createTask({ projectId: project.id, title: 'Decoy' });
+
+      const anonymous = await send(router, 'POST', `/tasks/${task.id}/comments`, { content: 'hi' });
+      expect(anonymous.status).toBe(201);
+      expect((await anonymous.json()).comment.authorId).toBe('anonymous');
+
+      const spoofed = await send(router, 'POST', `/tasks/${task.id}/comments`, { content: 'hi', authorId: 'ceo' }, 'alice');
+      expect(spoofed.status).toBe(400);
+
+      const authed = await send(router, 'POST', `/tasks/${task.id}/comments`, { content: 'hi', taskId: decoy.id }, 'alice');
+      expect(authed.status).toBe(201);
+      const { comment } = await authed.json();
+      expect(comment.authorId).toBe('alice');
+      expect(comment.taskId).toBe(task.id);
+    });
+
+    it('attributes unauthenticated writes to the anonymous actor and rejects actor claims', async () => {
+      const router = new CriticalPathRouter();
+      const project = await router.engine.createProject({ key: 'ANO', name: 'Anonymous' });
+      const task = await router.engine.createTask({ projectId: project.id, title: 'T' });
+
+      const claimed = await send(router, 'PATCH', `/tasks/${task.id}`, { isBlocked: true, actorId: 'agent-7' });
+      expect(claimed.status).toBe(400);
+
+      const res = await send(router, 'PATCH', `/tasks/${task.id}`, { isBlocked: true });
+      expect(res.status).toBe(200);
+      const activities = await router.engine.store.getActivities({ taskId: task.id });
+      expect(activities.some((a) => a.actorId === 'anonymous')).toBe(true);
+    });
+  });
 });
 

package/src/index.ts

@@ -2,3 +2,4 @@ export * from './router.js';
 export * from './adapters/next.js';
 export * from './adapters/sveltekit.js';
 export * from './adapters/universal.js';
+export * from './openapi.js';

package/src/openapi.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { CriticalPathRouter } from './router.js';
+import { ROUTES, buildOpenApiDocument } from './openapi.js';
+
+const base = 'http://localhost:3000/api/critical-path';
+
+describe('OpenAPI document', () => {
+  it('documents every route the router serves, with matching response envelopes', async () => {
+    const router = new CriticalPathRouter();
+    const engine = router.engine;
+    const project = await engine.createProject({ key: 'OAS', name: 'OpenAPI' });
+    const task = await engine.createTask({ projectId: project.id, title: 'Task' });
+    const workflow = await engine.createWorkflow({ name: 'WF', statuses: [], transitions: [] });
+    const team = await engine.createTeam({ name: 'Team', memberIds: [] });
+    const container = await engine.createContainer({ projectId: project.id, name: 'Epic' });
+    const deliverable = await engine.createDeliverable({ projectId: project.id, title: 'Cut' });
+    const iteration = await engine.createIteration({ projectId: project.id, name: 'S1', status: 'planning' });
+    const comment = await engine.addComment({ taskId: task.id, content: 'hi', authorId: 'u1' });
+    const attachment = await engine.createAttachment({
+      taskId: task.id,
+      uploaderId: 'u1',
+      filename: 'a.md',
+      mimeType: 'text/markdown',
+      sizeBytes: 1,
+      url: 'https://example.com/a.md'
+    });
+
+    const ids: Record<string, string> = {
+      projectId: project.id,
+      taskId: task.id,
+      workflowId: workflow.id,
+      teamId: team.id,
+      containerId: container.id,
+      deliverableId: deliverable.id,
+      iterationId: iteration.id,
+      commentId: comment.id,
+      attachmentId: attachment.id
+    };
+    const query: Record<string, string> = { projectId: project.id, taskId: task.id, emoji: '👍', userId: 'u1' };
+
+    // Deletes run last so earlier routes still have data; the project goes last of all.
+    const ordered = [...ROUTES].sort((a, b) => {
+      const rank = (r: (typeof ROUTES)[number]) => (r.method === 'delete' ? (r.path === '/projects/{projectId}' ? 2 : 1) : 0);
+      return rank(a) - rank(b);
+    });
+
+    for (const route of ordered) {
+      const path = route.path.replace(/\{(\w+)\}/g, (_, name) => ids[name]);
+      const params = new URLSearchParams();
+      for (const q of route.query ?? []) {
+        const name = q.replace(/!$/, '');
+        if (query[name]) params.set(name, query[name]);
+      }
+      const res = await router.handleRequest(
+        new Request(`${base}${path}${params.size ? `?${params}` : ''}`, {
+          method: route.method.toUpperCase(),
+          headers: { 'Content-Type': 'application/json' },
+          ...(route.method === 'post' || route.method === 'patch' ? { body: '{}' } : {})
+        })
+      );
+      const body = await res.json();
+      const label = `${route.method.toUpperCase()} ${route.path}`;
+      expect(String(body.error ?? ''), label).not.toMatch(/^Route not found/);
+      if (res.status < 300 && route.responseKey) {
+        expect(body, label).toHaveProperty(route.responseKey);
+      }
+    }
+  });
+
+  it('serves the document at /openapi.json with request bodies from the validation schemas', async () => {
+    const router = new CriticalPathRouter();
+    const res = await router.handleRequest(new Request(`${base}/openapi.json`));
+    expect(res.status).toBe(200);
+    const doc = await res.json();
+
+    expect(doc.openapi).toBe('3.1.0');
+    expect(doc.servers[0].url).toBe('http://localhost:3000/api/critical-path');
+    const createTask = doc.paths['/tasks'].post.requestBody.content['application/json'].schema;
+    expect(createTask.required).toEqual(expect.arrayContaining(['projectId', 'title']));
+    expect(createTask.properties).not.toHaveProperty('id');
+    expect(doc.paths['/tasks/{taskId}/dependencies'].post.responses).toHaveProperty('409');
+  });
+
+  it('respects requireAuth', async () => {
+    const router = new CriticalPathRouter(undefined, { requireAuth: true });
+    const res = await router.handleRequest(new Request(`${base}/openapi.json`));
+    expect(res.status).toBe(401);
+  });
+
+  it('can be built without a router for static publishing', () => {
+    const doc = buildOpenApiDocument({ serverUrl: 'https://api.example.com/pm', version: '2.0.0' }) as any;
+    expect(doc.info.version).toBe('2.0.0');
+    expect(Object.keys(doc.paths).length).toBeGreaterThan(30);
+  });
+});

package/src/openapi.ts

@@ -0,0 +1,178 @@
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import * as schemas from '@critical-path/core/schemas';
+
+type Method = 'get' | 'post' | 'patch' | 'delete';
+
+interface RouteDoc {
+  method: Method;
+  path: string;
+  summary: string;
+  tag: string;
+  /** Query parameters; names ending in `!` are required. */
+  query?: string[];
+  body?: { safeParse(data: unknown): unknown };
+  /** Key of the JSON response envelope, e.g. `task` for `{ "task": { ... } }`. */
+  responseKey?: string;
+  status?: number;
+}
+
+/** Every route served by `CriticalPathRouter`. Kept in sync by the route drift test. */
+export const ROUTES: RouteDoc[] = [
+  { method: 'get', path: '/workflows', summary: 'List workflows', tag: 'Workflows', responseKey: 'workflows' },
+  { method: 'post', path: '/workflows', summary: 'Create a workflow', tag: 'Workflows', body: schemas.CreateWorkflowSchema, responseKey: 'workflow', status: 201 },
+  { method: 'get', path: '/workflows/{workflowId}', summary: 'Get a workflow', tag: 'Workflows', responseKey: 'workflow' },
+  { method: 'patch', path: '/workflows/{workflowId}', summary: 'Update a workflow', tag: 'Workflows', body: schemas.UpdateWorkflowSchema, responseKey: 'workflow' },
+  { method: 'delete', path: '/workflows/{workflowId}', summary: 'Delete a workflow', tag: 'Workflows' },
+
+  { method: 'get', path: '/projects', summary: 'List projects', tag: 'Projects', responseKey: 'projects' },
+  { method: 'post', path: '/projects', summary: 'Create a project', tag: 'Projects', body: schemas.CreateProjectSchema, responseKey: 'project', status: 201 },
+  { method: 'get', path: '/projects/{projectId}', summary: 'Get a project', tag: 'Projects', responseKey: 'project' },
+  { method: 'patch', path: '/projects/{projectId}', summary: 'Update a project', tag: 'Projects', body: schemas.UpdateProjectSchema, responseKey: 'project' },
+  { method: 'delete', path: '/projects/{projectId}', summary: 'Delete a project and its tasks', tag: 'Projects' },
+  { method: 'get', path: '/projects/{projectId}/critical-path', summary: 'Critical path (CPM) analysis', tag: 'Analysis', responseKey: 'analysis' },
+  { method: 'get', path: '/projects/{projectId}/ladder', summary: 'Timeline ladder of abstraction', tag: 'Analysis', query: ['level', 'containerId', 'iterationId'], responseKey: 'ladder' },
+  { method: 'get', path: '/projects/{projectId}/workload', summary: 'Project workload distribution', tag: 'Analysis', query: ['startDate', 'endDate', 'interval', 'groupBy', 'metric', 'defaultWeeklyCapacityHours'], responseKey: 'workload' },
+
+  { method: 'get', path: '/tasks', summary: 'List tasks', tag: 'Tasks', query: ['projectId'], responseKey: 'tasks' },
+  { method: 'post', path: '/tasks', summary: 'Create a task', tag: 'Tasks', body: schemas.CreateTaskSchema, responseKey: 'task', status: 201 },
+  { method: 'get', path: '/tasks/{taskId}', summary: 'Get a task', tag: 'Tasks', responseKey: 'task' },
+  { method: 'patch', path: '/tasks/{taskId}', summary: 'Update a task (enforces workflow transitions)', tag: 'Tasks', body: schemas.UpdateTaskSchema, responseKey: 'task' },
+  { method: 'delete', path: '/tasks/{taskId}', summary: 'Delete a task', tag: 'Tasks' },
+  { method: 'get', path: '/tasks/{taskId}/comments', summary: 'List task comments', tag: 'Comments', responseKey: 'comments' },
+  { method: 'post', path: '/tasks/{taskId}/comments', summary: 'Comment on a task', tag: 'Comments', body: schemas.CreateCommentSchema.omit({ taskId: true }), responseKey: 'comment', status: 201 },
+  { method: 'get', path: '/tasks/{taskId}/attachments', summary: 'List task attachments', tag: 'Attachments', responseKey: 'attachments' },
+  { method: 'post', path: '/tasks/{taskId}/attachments', summary: 'Attach a file link to a task', tag: 'Attachments', body: schemas.CreateAttachmentSchema.omit({ taskId: true }), responseKey: 'attachment', status: 201 },
+  { method: 'get', path: '/tasks/{taskId}/dependencies', summary: 'Task dependency graph', tag: 'Dependencies', responseKey: 'graph' },
+  { method: 'post', path: '/tasks/{taskId}/dependencies', summary: 'Add a dependency (409 on cycles)', tag: 'Dependencies', body: schemas.CreateDependencySchema, responseKey: 'dependency', status: 201 },
+  { method: 'get', path: '/tasks/{taskId}/lifecycle', summary: 'Derived lifecycle state', tag: 'Tasks', responseKey: 'state' },
+  { method: 'get', path: '/tasks/{taskId}/transitions', summary: 'Allowed status transitions', tag: 'Tasks' },
+  { method: 'get', path: '/tasks/{taskId}/ladder', summary: 'Single-task ladder view', tag: 'Analysis', responseKey: 'taskLadder' },
+  { method: 'get', path: '/tasks/{taskId}/metrics', summary: 'Task metrics and EVM', tag: 'Analysis', responseKey: 'metrics' },
+  { method: 'get', path: '/tasks/{taskId}/progress-history', summary: 'Reconstructed progress history', tag: 'Analysis', responseKey: 'progressHistory' },
+
+  { method: 'get', path: '/teams', summary: 'List teams', tag: 'Teams', responseKey: 'teams' },
+  { method: 'post', path: '/teams', summary: 'Create a team', tag: 'Teams', body: schemas.CreateTeamSchema, responseKey: 'team', status: 201 },
+  { method: 'get', path: '/teams/{teamId}', summary: 'Get a team', tag: 'Teams', responseKey: 'team' },
+  { method: 'patch', path: '/teams/{teamId}', summary: 'Update a team', tag: 'Teams', body: schemas.UpdateTeamSchema, responseKey: 'team' },
+  { method: 'delete', path: '/teams/{teamId}', summary: 'Delete a team', tag: 'Teams' },
+
+  { method: 'get', path: '/containers', summary: 'List containers', tag: 'Containers', query: ['projectId!'], responseKey: 'containers' },
+  { method: 'post', path: '/containers', summary: 'Create a container', tag: 'Containers', body: schemas.CreateContainerSchema, responseKey: 'container', status: 201 },
+  { method: 'get', path: '/containers/{containerId}', summary: 'Get a container', tag: 'Containers', responseKey: 'container' },
+  { method: 'patch', path: '/containers/{containerId}', summary: 'Update a container', tag: 'Containers', body: schemas.UpdateContainerSchema, responseKey: 'container' },
+  { method: 'delete', path: '/containers/{containerId}', summary: 'Delete a container', tag: 'Containers' },
+
+  { method: 'get', path: '/deliverables', summary: 'List deliverables', tag: 'Deliverables', query: ['projectId!'], responseKey: 'deliverables' },
+  { method: 'post', path: '/deliverables', summary: 'Create a deliverable', tag: 'Deliverables', body: schemas.CreateDeliverableSchema, responseKey: 'deliverable', status: 201 },
+  { method: 'get', path: '/deliverables/{deliverableId}', summary: 'Get a deliverable', tag: 'Deliverables', responseKey: 'deliverable' },
+  { method: 'get', path: '/deliverables/{deliverableId}/summary', summary: 'Deliverable rollup summary', tag: 'Deliverables', responseKey: 'summary' },
+  { method: 'patch', path: '/deliverables/{deliverableId}', summary: 'Update a deliverable', tag: 'Deliverables', body: schemas.UpdateDeliverableSchema, responseKey: 'deliverable' },
+  { method: 'delete', path: '/deliverables/{deliverableId}', summary: 'Delete a deliverable', tag: 'Deliverables' },
+
+  { method: 'get', path: '/iterations', summary: 'List iterations', tag: 'Iterations', query: ['projectId!'], responseKey: 'iterations' },
+  { method: 'post', path: '/iterations', summary: 'Create an iteration', tag: 'Iterations', body: schemas.CreateIterationSchema, responseKey: 'iteration', status: 201 },
+  { method: 'get', path: '/iterations/{iterationId}', summary: 'Get an iteration', tag: 'Iterations', responseKey: 'iteration' },
+  { method: 'patch', path: '/iterations/{iterationId}', summary: 'Update an iteration', tag: 'Iterations', body: schemas.UpdateIterationSchema, responseKey: 'iteration' },
+  { method: 'delete', path: '/iterations/{iterationId}', summary: 'Delete an iteration', tag: 'Iterations' },
+
+  { method: 'get', path: '/activities', summary: 'Activity (audit) stream', tag: 'Activity', query: ['projectId', 'taskId'], responseKey: 'activities' },
+
+  { method: 'get', path: '/comments', summary: 'List comments for a task', tag: 'Comments', query: ['taskId!'], responseKey: 'comments' },
+  { method: 'post', path: '/comments', summary: 'Create a comment', tag: 'Comments', body: schemas.CreateCommentSchema, responseKey: 'comment', status: 201 },
+  { method: 'get', path: '/comments/{commentId}', summary: 'Get a comment', tag: 'Comments', responseKey: 'comment' },
+  { method: 'patch', path: '/comments/{commentId}', summary: 'Update a comment', tag: 'Comments', body: schemas.UpdateCommentSchema, responseKey: 'comment' },
+  { method: 'delete', path: '/comments/{commentId}', summary: 'Delete a comment', tag: 'Comments' },
+  { method: 'post', path: '/comments/{commentId}/reactions', summary: 'Add a reaction', tag: 'Comments', body: schemas.CommentReactionSchema, responseKey: 'comment' },
+  { method: 'delete', path: '/comments/{commentId}/reactions', summary: 'Remove a reaction', tag: 'Comments', query: ['emoji!'], responseKey: 'comment' },
+
+  { method: 'get', path: '/attachments', summary: 'List attachments', tag: 'Attachments', query: ['taskId', 'projectId', 'commentId'], responseKey: 'attachments' },
+  { method: 'post', path: '/attachments', summary: 'Register an attachment', tag: 'Attachments', body: schemas.CreateAttachmentSchema, responseKey: 'attachment', status: 201 },
+  { method: 'post', path: '/attachments/upload', summary: 'Upload a file through the configured FileStorageAdapter', tag: 'Attachments', body: schemas.UploadAttachmentSchema, responseKey: 'attachment', status: 201 },
+  { method: 'post', path: '/attachments/presign', summary: 'Request a presigned upload URL', tag: 'Attachments', body: schemas.PresignAttachmentSchema, responseKey: 'presigned' },
+  { method: 'get', path: '/attachments/{attachmentId}', summary: 'Get an attachment', tag: 'Attachments', responseKey: 'attachment' },
+  { method: 'delete', path: '/attachments/{attachmentId}', summary: 'Delete an attachment', tag: 'Attachments' },
+
+  { method: 'get', path: '/time-entries', summary: 'List time entries for a task', tag: 'Time Tracking', query: ['taskId!'], responseKey: 'timeEntries' },
+  { method: 'post', path: '/time-entries', summary: 'Log time against a task', tag: 'Time Tracking', body: schemas.LogTimeSchema, responseKey: 'timeEntry', status: 201 },
+
+  { method: 'get', path: '/workload', summary: 'Workload distribution across projects', tag: 'Analysis', query: ['projectId', 'startDate', 'endDate', 'interval', 'groupBy', 'metric', 'defaultWeeklyCapacityHours'], responseKey: 'workload' },
+  { method: 'post', path: '/status', summary: 'Publish an agent status update', tag: 'Agents' }
+];
+
+const errorResponse = {
+  description: 'Error',
+  content: {
+    'application/json': {
+      schema: {
+        type: 'object',
+        properties: {
+          error: { type: 'string' },
+          issues: { type: 'array', items: { type: 'object', properties: { path: { type: 'string' }, message: { type: 'string' } } } }
+        },
+        required: ['error']
+      }
+    }
+  }
+};
+
+function toJsonSchema(schema: unknown): Record<string, unknown> {
+  const { $schema: _ignored, ...json } = zodToJsonSchema(schema as any, { $refStrategy: 'none' }) as Record<string, unknown>;
+  return json;
+}
+
+export interface OpenApiOptions {
+  /** Public URL the API is served from, e.g. `https://app.example.com/api/critical-path`. */
+  serverUrl?: string;
+  title?: string;
+  version?: string;
+}
+
+/**
+ * Builds an OpenAPI 3.1 document for the router. Request bodies are generated from the same zod
+ * schemas the router validates with, so the contract cannot drift from enforcement.
+ */
+export function buildOpenApiDocument(options: OpenApiOptions = {}): Record<string, unknown> {
+  const paths: Record<string, Record<string, unknown>> = {};
+
+  for (const route of ROUTES) {
+    const pathParams = [...route.path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+    const parameters = [
+      ...pathParams.map((name) => ({ name, in: 'path', required: true, schema: { type: 'string' } })),
+      ...(route.query ?? []).map((q) => ({
+        name: q.replace(/!$/, ''),
+        in: 'query',
+        required: q.endsWith('!'),
+        schema: { type: 'string' }
+      }))
+    ];
+    const status = String(route.status ?? 200);
+    const successSchema = route.responseKey
+      ? { type: 'object', properties: { [route.responseKey]: {} }, required: [route.responseKey] }
+      : { type: 'object' };
+
+    paths[route.path] ??= {};
+    paths[route.path][route.method] = {
+      summary: route.summary,
+      tags: [route.tag],
+      ...(parameters.length ? { parameters } : {}),
+      ...(route.body
+        ? { requestBody: { required: true, content: { 'application/json': { schema: toJsonSchema(route.body) } } } }
+        : {}),
+      responses: {
+        [status]: { description: 'Success', content: { 'application/json': { schema: successSchema } } },
+        '400': errorResponse,
+        '401': errorResponse,
+        '404': errorResponse,
+        ...(route.path.endsWith('/dependencies') && route.method === 'post' ? { '409': errorResponse } : {}),
+        '500': errorResponse
+      }
+    };
+  }
+
+  return {
+    openapi: '3.1.0',
+    info: { title: options.title ?? 'Critical Path API', version: options.version ?? '1.0.0' },
+    ...(options.serverUrl ? { servers: [{ url: options.serverUrl }] } : {}),
+    paths
+  };
+}