@critical-path/core 0.22.0 → 0.24.0

package/src/engine/index.ts

@@ -1,4 +1,5 @@
 import type {
+  Actor,
   CriticalPathConfig,
   Project,
   Task,
@@ -98,6 +99,8 @@ export class CriticalPathEngine {
   public readonly plugins: PluginRegistry;
   public readonly events: DomainEventBus;
   public readonly ready: Promise<void> = Promise.resolve();
+  /** The identity mutations are attributed to. Set only on views returned by `withActor`. */
+  public readonly actor?: Actor;
 
   constructor(config: CriticalPathConfig = {}) {
     this.config = config;
@@ -120,6 +123,23 @@ export class CriticalPathEngine {
     }
   }
 
+  /**
+   * Returns a view of this engine that attributes every mutation to `actor`: activity log
+   * entries, comment authors, reactions, time entries, attachment uploaders and task reporters.
+   * Identity fields supplied in payloads are ignored on the view, so callers cannot claim to be
+   * someone else. The view shares the store, plugins and event bus, and does not modify this engine,
+   * so it is safe to create one per request.
+   */
+  withActor(actor: Actor): CriticalPathEngine {
+    const scoped = Object.create(this) as CriticalPathEngine;
+    Object.defineProperty(scoped, 'actor', { value: Object.freeze({ ...actor }), enumerable: true });
+    return scoped;
+  }
+
+  private actorIdOr(fallback: string): string {
+    return this.actor?.userId ?? fallback;
+  }
+
   private async seedInitialData(data: NonNullable<CriticalPathConfig['initialData']>): Promise<void> {
     if (data.workflows) {
       for (const wf of data.workflows) {
@@ -182,7 +202,7 @@ export class CriticalPathEngine {
     await this.events.publish(event);
 
     await this.store.logActivity({
-      actorId: 'system',
+      actorId: this.actorIdOr('system'),
       action: 'workflow.created',
       details: { name: created.name }
     });
@@ -208,7 +228,7 @@ export class CriticalPathEngine {
       await this.events.publish(event);
 
       await this.store.logActivity({
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'workflow.updated',
         details: { name: updated.name }
       });
@@ -235,7 +255,7 @@ export class CriticalPathEngine {
       await this.events.publish(event);
 
       await this.store.logActivity({
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'workflow.deleted',
         details: { name: existing.name }
       });
@@ -306,7 +326,7 @@ export class CriticalPathEngine {
 
     await this.store.logActivity({
       projectId: created.id,
-      actorId: project.ownerId || 'system',
+      actorId: this.actorIdOr(project.ownerId || 'system'),
       action: 'project.created',
       details: { name: created.name, key: created.key }
     });
@@ -333,7 +353,7 @@ export class CriticalPathEngine {
 
       await this.store.logActivity({
         projectId: updated.id,
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'project.updated',
         details: { name: updated.name }
       });
@@ -373,7 +393,7 @@ export class CriticalPathEngine {
 
       await this.store.logActivity({
         projectId: id,
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'project.deleted',
         details: { name: existing.name, deletedTaskCount: deletedTaskIds.length }
       });
@@ -392,6 +412,9 @@ export class CriticalPathEngine {
   }
 
   async createTask(taskInput: CreateTaskInput): Promise<Task> {
+    if (this.actor && !taskInput.reporterId) {
+      taskInput = { ...taskInput, reporterId: this.actor.userId };
+    }
     const processedInput = await this.plugins.runBeforeTaskCreate(taskInput);
     const projectId = processedInput.projectId || taskInput.projectId;
     const project = await this.store.getProject(projectId);
@@ -477,7 +500,7 @@ export class CriticalPathEngine {
     await this.store.logActivity({
       projectId: created.projectId,
       taskId: created.id,
-      actorId: created.reporterId || 'system',
+      actorId: this.actorIdOr(created.reporterId || 'system'),
       action: 'task.created',
       details: { title: created.title, status: created.status }
     });
@@ -504,25 +527,30 @@ export class CriticalPathEngine {
     const existing = await this.store.getTask(id);
     if (!existing) return null;
 
+    // On a withActor view, the scoped actor replaces any identity claimed in the payload.
+    // Explicit options from trusted server-side code still take precedence.
+    options = options ?? (this.actor ? { actor: this.actor } : undefined);
+    const claimed = this.actor ? undefined : updates;
+
     const actorId =
       options?.actorId ||
-      updates.actorId ||
+      claimed?.actorId ||
       options?.actor?.userId ||
-      updates.actor?.userId ||
+      claimed?.actor?.userId ||
       'system';
     const actorName =
       options?.actorName ||
-      updates.actorName ||
+      claimed?.actorName ||
       options?.actor?.username ||
-      updates.actor?.username ||
+      claimed?.actor?.username ||
       (actorId === 'system' ? 'System' : undefined);
     const actorType =
       options?.actorType ||
-      updates.actorType ||
+      claimed?.actorType ||
       options?.actor?.actorType ||
-      updates.actor?.actorType ||
+      claimed?.actor?.actorType ||
       (actorId === 'system' ? 'system' : 'user');
-    const actorObj = options?.actor || updates.actor || {
+    const actorObj = options?.actor || claimed?.actor || {
       userId: actorId,
       username: actorName,
       actorType
@@ -903,7 +931,7 @@ export class CriticalPathEngine {
           await this.store.logActivity({
             projectId: downstream.projectId,
             taskId: downstream.id,
-            actorId: 'system',
+            actorId: this.actorIdOr('system'),
             action: 'task.unblocked',
             details: { unblockedByTaskId: completedTask.id }
           });
@@ -947,7 +975,7 @@ export class CriticalPathEngine {
       await this.store.logActivity({
         projectId: existing.projectId,
         taskId: id,
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'task.deleted',
         details: { title: existing.title }
       });
@@ -1082,7 +1110,7 @@ export class CriticalPathEngine {
 
     const fullEntry: Omit<TimeEntry, 'id' | 'loggedAt'> & { loggedAt?: string } = {
       ...entry,
-      userId: entry.userId || task?.assigneeId || 'system',
+      userId: this.actor?.userId || entry.userId || task?.assigneeId || 'system',
       loggedAt: entry.loggedAt
     };
 
@@ -1112,6 +1140,9 @@ export class CriticalPathEngine {
   }
 
   async addComment(comment: Omit<Comment, 'id' | 'createdAt' | 'updatedAt'>): Promise<Comment> {
+    if (this.actor) {
+      comment = { ...comment, authorId: this.actor.userId, authorType: this.actor.actorType ?? 'user' };
+    }
     const mentions = comment.mentions ?? extractMentions(comment.content);
     const created = await this.store.addComment({ ...comment, mentions });
     const now = new Date().toISOString();
@@ -1178,6 +1209,7 @@ export class CriticalPathEngine {
   }
 
   async addCommentReaction(commentId: string, reaction: { emoji: string; userId: string }): Promise<Comment | null> {
+    if (this.actor) reaction = { ...reaction, userId: this.actor.userId };
     const existing = await this.store.getComment(commentId);
     if (!existing) return null;
 
@@ -1223,6 +1255,7 @@ export class CriticalPathEngine {
   }
 
   async removeCommentReaction(commentId: string, reaction: { emoji: string; userId: string }): Promise<Comment | null> {
+    if (this.actor) reaction = { ...reaction, userId: this.actor.userId };
     const existing = await this.store.getComment(commentId);
     if (!existing) return null;
 
@@ -1267,6 +1300,9 @@ export class CriticalPathEngine {
   }
 
   async createAttachment(attachment: Omit<Attachment, 'id' | 'createdAt' | 'updatedAt'>): Promise<Attachment> {
+    if (this.actor) {
+      attachment = { ...attachment, uploaderId: this.actor.userId, uploaderType: this.actor.actorType ?? 'user' };
+    }
     validateAttachmentUrl(attachment.url);
     const created = await this.store.createAttachment(attachment);
     const now = new Date().toISOString();
@@ -1498,7 +1534,7 @@ export class CriticalPathEngine {
 
     await this.store.logActivity({
       projectId: created.projectId,
-      actorId: 'system',
+      actorId: this.actorIdOr('system'),
       action: 'deliverable.created',
       details: { title: created.title, format: created.format }
     });
@@ -1551,7 +1587,7 @@ export class CriticalPathEngine {
 
       await this.store.logActivity({
         projectId: updated.projectId,
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'deliverable.updated',
         details: { title: updated.title, status: updated.status }
       });
@@ -1579,7 +1615,7 @@ export class CriticalPathEngine {
 
       await this.store.logActivity({
         projectId: existing.projectId,
-        actorId: 'system',
+        actorId: this.actorIdOr('system'),
         action: 'deliverable.deleted',
         details: { title: existing.title }
       });

package/src/schemas/index.ts

@@ -0,0 +1,337 @@
+/**
+ * Request payload schemas for Critical Path resources.
+ *
+ * Exposed from `@critical-path/core/schemas` (not the package root) so browser bundles of core do
+ * not pull in zod. Create schemas omit server-assigned fields (`id`, `createdAt`, `updatedAt`, task
+ * `key`); update schemas additionally make every field optional and omit the owning `projectId`.
+ * Unknown keys are stripped rather than rejected, so older clients that send whole objects keep
+ * working while protected fields are never written.
+ */
+import { z } from 'zod';
+import { ValidationError, type ValidationIssue } from '../domain/errors.js';
+
+/**
+ * Parses `data` with `schema`, returning the cleaned value (unknown keys stripped, defaults
+ * applied) or throwing a `ValidationError` whose `issues` list every problem.
+ */
+export function parsePayload<S extends z.ZodTypeAny>(schema: S, data: unknown): z.output<S> {
+  const result = schema.safeParse(data ?? {});
+  if (result.success) return result.data;
+  const issues: ValidationIssue[] = result.error.issues.map((issue) => ({
+    path: issue.path.join('.'),
+    message: issue.message
+  }));
+  const summary = issues.map((i) => (i.path ? `${i.path}: ${i.message}` : i.message)).join('; ');
+  throw new ValidationError(`Invalid request body: ${summary}`, issues);
+}
+
+const isoString = z.string();
+const nonEmpty = z.string().min(1);
+
+export const SemanticStatusSchema = z.enum(['not_started', 'in_progress', 'completed', 'canceled']);
+export const AuthorTypeSchema = z.enum(['user', 'agent', 'system']);
+
+export const StatusDefinitionSchema = z.object({
+  key: nonEmpty,
+  label: z.string(),
+  category: SemanticStatusSchema
+});
+
+export const WorkScheduleSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  timezone: z.string().optional(),
+  defaultHoursPerDay: z.number().nonnegative().optional(),
+  days: z.array(
+    z.object({
+      dayOfWeek: z.number().int().min(0).max(6),
+      isWorkingDay: z.boolean(),
+      hours: z.array(z.object({ start: z.string(), end: z.string() })).optional()
+    })
+  ),
+  holidays: z
+    .array(z.object({ date: z.string(), name: z.string().optional(), halfDay: z.boolean().optional() }))
+    .optional()
+});
+
+export const CustomFieldDefinitionSchema = z.object({
+  id: z.string(),
+  key: nonEmpty,
+  label: z.string(),
+  type: z.enum(['text', 'number', 'date', 'boolean', 'single_select', 'multi_select', 'user']),
+  options: z.array(z.string()).optional(),
+  required: z.boolean().optional(),
+  defaultValue: z.unknown().optional()
+});
+
+export const TaskTypeDefinitionSchema = z.object({
+  key: nonEmpty,
+  label: z.string(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  defaultStatusKey: z.string().optional(),
+  workflowId: z.string().optional()
+});
+
+const customFields = z.record(z.unknown());
+const metadata = z.record(z.unknown());
+
+// --- Workflows ---
+
+export const CreateWorkflowSchema = z.object({
+  name: nonEmpty,
+  description: z.string().optional(),
+  statuses: z.array(StatusDefinitionSchema),
+  transitions: z
+    .array(
+      z.object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        fromStatusKey: z.string(),
+        toStatusKey: z.string()
+      })
+    )
+    .default([]),
+  taskTypes: z.array(TaskTypeDefinitionSchema).optional(),
+  defaultStatusKey: z.string().optional(),
+  isDefault: z.boolean().optional()
+});
+export const UpdateWorkflowSchema = CreateWorkflowSchema.partial();
+
+// --- Projects ---
+
+export const CreateProjectSchema = z.object({
+  key: z.string().optional(),
+  name: nonEmpty,
+  description: z.string().optional(),
+  ownerId: z.string().optional(),
+  members: z.array(z.string()).optional(),
+  teamIds: z.array(z.string()).optional(),
+  workflowId: z.string().optional(),
+  taskTypes: z.array(TaskTypeDefinitionSchema).optional(),
+  statusDefinitions: z.array(StatusDefinitionSchema).optional(),
+  priorityDefinitions: z
+    .array(z.object({ key: z.string(), label: z.string(), level: z.number().optional() }))
+    .optional(),
+  customFieldDefinitions: z.array(CustomFieldDefinitionSchema).optional(),
+  schedule: WorkScheduleSchema.optional(),
+  startDate: isoString.optional(),
+  targetEndDate: isoString.optional()
+});
+export const UpdateProjectSchema = CreateProjectSchema.partial();
+
+// --- Tasks ---
+
+const taskFields = {
+  title: nonEmpty,
+  description: z.string().optional(),
+  status: z.string().optional(),
+  semanticStatus: SemanticStatusSchema.optional(),
+  priority: z.string().optional(),
+  taskType: z.string().optional(),
+  assigneeId: z.string().optional(),
+  assignees: z
+    .array(
+      z.object({
+        id: z.string(),
+        name: z.string().optional(),
+        role: z.string().optional(),
+        type: z.enum(['user', 'agent', 'team']).optional(),
+        avatarUrl: z.string().optional()
+      })
+    )
+    .optional(),
+  reporterId: z.string().optional(),
+  reviewerId: z.string().optional(),
+  iterationId: z.string().optional(),
+  teamId: z.string().optional(),
+  containerId: z.string().optional(),
+  deliverableId: z.string().optional(),
+  plannedStartDate: isoString.optional(),
+  actualStartDate: isoString.optional(),
+  actualEndDate: isoString.optional(),
+  completedAt: isoString.optional(),
+  dueDate: isoString.optional(),
+  estimatedHours: z.number().nonnegative().optional(),
+  loggedHours: z.number().nonnegative().optional(),
+  actualHours: z.number().nonnegative().optional(),
+  billableHours: z.number().nonnegative().optional(),
+  estimatedDurationMinutes: z.number().nonnegative().optional(),
+  actualDurationMinutes: z.number().nonnegative().optional(),
+  billableDurationMinutes: z.number().nonnegative().optional(),
+  actualDurationSeconds: z.number().nonnegative().optional(),
+  inProgressSince: isoString.nullable().optional(),
+  blockedDurationSeconds: z.number().nonnegative().optional(),
+  blockedSince: isoString.nullable().optional(),
+  progress: z.number().min(0).max(100).optional(),
+  isBlocked: z.boolean().optional(),
+  blockedReason: z.string().nullable().optional(),
+  tags: z.array(z.string()).optional(),
+  todos: z
+    .array(
+      z.object({
+        id: z.string(),
+        title: z.string(),
+        completed: z.boolean(),
+        createdAt: isoString.optional(),
+        completedAt: isoString.optional()
+      })
+    )
+    .optional(),
+  customFields: customFields.optional(),
+  parentId: z.string().optional()
+};
+
+export const CreateTaskSchema = z.object({ projectId: nonEmpty, ...taskFields });
+
+/** Actor fields accepted on task updates; ignored when the server resolves the caller. */
+const actorClaimFields = {
+  actorId: z.string().optional(),
+  actorName: z.string().optional(),
+  actorType: z.string().optional(),
+  actor: z
+    .object({ userId: z.string(), username: z.string().optional(), actorType: z.string().optional() })
+    .optional()
+};
+
+export const UpdateTaskSchema = z.object(taskFields).partial().extend(actorClaimFields);
+
+// --- Dependencies ---
+
+export const CreateDependencySchema = z.object({
+  dependsOnTaskId: nonEmpty,
+  type: z.enum(['blocking', 'blocked_by', 'relates_to']).default('blocking')
+});
+
+// --- Deliverables ---
+
+const deliverableFields = {
+  title: nonEmpty,
+  description: z.string().optional(),
+  status: z.string().optional(),
+  format: z.string().optional(),
+  specs: z.record(z.unknown()).optional(),
+  leadId: z.string().optional(),
+  reviewerId: z.string().optional(),
+  dueDate: isoString.optional(),
+  deliveredAt: isoString.optional(),
+  outputUrls: z.array(z.string()).optional(),
+  customFields: customFields.optional()
+};
+export const CreateDeliverableSchema = z.object({ projectId: nonEmpty, ...deliverableFields });
+export const UpdateDeliverableSchema = z.object(deliverableFields).partial();
+
+// --- Teams ---
+
+export const CreateTeamSchema = z.object({
+  name: nonEmpty,
+  description: z.string().optional(),
+  leaderId: z.string().optional(),
+  memberIds: z.array(z.string()).default([]),
+  weeklyCapacityHours: z.number().nonnegative().optional(),
+  schedule: WorkScheduleSchema.optional()
+});
+export const UpdateTeamSchema = CreateTeamSchema.partial();
+
+// --- Containers ---
+
+const containerFields = {
+  name: nonEmpty,
+  description: z.string().optional(),
+  parentId: z.string().optional(),
+  type: z.string().optional(),
+  color: z.string().optional()
+};
+export const CreateContainerSchema = z.object({ projectId: nonEmpty, ...containerFields });
+export const UpdateContainerSchema = z.object(containerFields).partial();
+
+// --- Iterations ---
+
+const iterationFields = {
+  name: nonEmpty,
+  goal: z.string().optional(),
+  type: z.string().optional(),
+  startDate: isoString.optional(),
+  endDate: isoString.optional(),
+  status: z.enum(['planning', 'active', 'completed']).default('planning')
+};
+export const CreateIterationSchema = z.object({ projectId: nonEmpty, ...iterationFields });
+export const UpdateIterationSchema = z
+  .object({ ...iterationFields, status: z.enum(['planning', 'active', 'completed']) })
+  .partial();
+
+// --- Comments & Reactions ---
+
+export const CreateCommentSchema = z.object({
+  taskId: nonEmpty,
+  /** Required unless the server resolves the caller, in which case it is replaced. */
+  authorId: z.string().optional(),
+  authorType: AuthorTypeSchema.optional(),
+  parentId: z.string().optional(),
+  content: nonEmpty,
+  mentions: z.array(z.string()).optional(),
+  metadata: metadata.optional()
+});
+export const UpdateCommentSchema = z
+  .object({ content: nonEmpty, mentions: z.array(z.string()), metadata })
+  .partial();
+
+export const CommentReactionSchema = z.object({
+  emoji: nonEmpty,
+  /** Required unless the server resolves the caller, in which case it is replaced. */
+  userId: z.string().optional()
+});
+
+// --- Attachments ---
+
+const attachmentLinks = {
+  taskId: z.string().optional(),
+  projectId: z.string().optional(),
+  commentId: z.string().optional(),
+  /** Required unless the server resolves the caller, in which case it is replaced. */
+  uploaderId: z.string().optional(),
+  uploaderType: AuthorTypeSchema.optional(),
+  artifactType: z.enum(['plan', 'spec', 'deliverable', 'review', 'general']).optional(),
+  metadata: metadata.optional()
+};
+
+export const CreateAttachmentSchema = z.object({
+  ...attachmentLinks,
+  filename: nonEmpty,
+  // Linked (rather than uploaded) files often have no known type or size.
+  mimeType: nonEmpty.default('application/octet-stream'),
+  sizeBytes: z.number().int().nonnegative().default(0),
+  url: nonEmpty,
+  storageKey: z.string().optional()
+});
+
+export const UploadAttachmentSchema = z.object({
+  ...attachmentLinks,
+  filename: nonEmpty,
+  data: z.string(),
+  mimeType: z.string().optional(),
+  pathPrefix: z.string().optional(),
+  encoding: z.enum(['base64', 'utf-8', 'binary']).optional()
+});
+
+export const PresignAttachmentSchema = z.object({
+  storageKey: nonEmpty,
+  expiresInSeconds: z.number().int().positive().optional(),
+  contentType: z.string().optional()
+});
+
+// --- Time Tracking ---
+
+export const LogTimeSchema = z.object({
+  taskId: nonEmpty,
+  hours: z.number().positive(),
+  isBillable: z.boolean().optional(),
+  description: z.string().optional(),
+  userId: z.string().optional(),
+  loggedAt: isoString.optional()
+});
+
+export type CreateTaskPayload = z.infer<typeof CreateTaskSchema>;
+export type UpdateTaskPayload = z.infer<typeof UpdateTaskSchema>;
+export type CreateProjectPayload = z.infer<typeof CreateProjectSchema>;
+export type UpdateProjectPayload = z.infer<typeof UpdateProjectSchema>;

package/src/schemas/schemas.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import type { z } from 'zod';
+import type {
+  CreateTaskInput,
+  Task,
+  CreateProjectInput,
+  Project,
+  Workflow,
+  CreateDeliverableInput,
+  Deliverable,
+  Team,
+  TaskContainer,
+  Iteration,
+  Comment,
+  CreateAttachmentInput,
+  TimeEntry
+} from '../types/index.js';
+import {
+  CreateTaskSchema,
+  UpdateTaskSchema,
+  CreateProjectSchema,
+  UpdateProjectSchema,
+  CreateWorkflowSchema,
+  CreateDeliverableSchema,
+  UpdateDeliverableSchema,
+  CreateTeamSchema,
+  CreateContainerSchema,
+  UpdateContainerSchema,
+  CreateIterationSchema,
+  CreateCommentSchema,
+  UpdateCommentSchema,
+  CreateAttachmentSchema,
+  LogTimeSchema
+} from './index.js';
+
+/**
+ * Compile-time check that a schema covers exactly the writable keys of a domain type. If a field
+ * is added to a type in `types/index.ts` but not to its schema, the build fails here instead of
+ * the field being silently stripped from API requests.
+ */
+type SameKeys<Schema, Expected> = [Exclude<keyof Schema, keyof Expected>, Exclude<keyof Expected, keyof Schema>] extends [
+  never,
+  never
+]
+  ? true
+  : { extraInSchema: Exclude<keyof Schema, keyof Expected>; missingFromSchema: Exclude<keyof Expected, keyof Schema> };
+
+type Infer<S extends z.ZodTypeAny> = z.infer<S>;
+type ServerAssigned = 'id' | 'createdAt' | 'updatedAt';
+type ActorClaims = 'actorId' | 'actorName' | 'actorType' | 'actor';
+
+const keyChecks: true[] = [
+  true as SameKeys<Infer<typeof CreateTaskSchema>, Omit<CreateTaskInput, 'key'>>,
+  true as SameKeys<Omit<Infer<typeof UpdateTaskSchema>, ActorClaims>, Omit<Task, ServerAssigned | 'key' | 'projectId'>>,
+  // `workflow` is a denormalised copy resolved from `workflowId`, so it is not writable.
+  true as SameKeys<Infer<typeof CreateProjectSchema>, Omit<CreateProjectInput, 'workflow'>>,
+  true as SameKeys<Infer<typeof UpdateProjectSchema>, Omit<Project, ServerAssigned | 'workflow'>>,
+  true as SameKeys<Infer<typeof CreateWorkflowSchema>, Omit<Workflow, ServerAssigned>>,
+  true as SameKeys<Infer<typeof CreateDeliverableSchema>, CreateDeliverableInput>,
+  true as SameKeys<Infer<typeof UpdateDeliverableSchema>, Omit<Deliverable, ServerAssigned | 'projectId'>>,
+  true as SameKeys<Infer<typeof CreateTeamSchema>, Omit<Team, ServerAssigned>>,
+  true as SameKeys<Infer<typeof CreateContainerSchema>, Omit<TaskContainer, ServerAssigned>>,
+  true as SameKeys<Infer<typeof UpdateContainerSchema>, Omit<TaskContainer, ServerAssigned | 'projectId'>>,
+  true as SameKeys<Infer<typeof CreateIterationSchema>, Omit<Iteration, 'id' | 'createdAt'>>,
+  // Reactions are managed through the reactions endpoints.
+  true as SameKeys<Infer<typeof CreateCommentSchema>, Omit<Comment, ServerAssigned | 'reactions'>>,
+  true as SameKeys<Infer<typeof UpdateCommentSchema>, Pick<Comment, 'content' | 'mentions' | 'metadata'>>,
+  true as SameKeys<Infer<typeof CreateAttachmentSchema>, CreateAttachmentInput>,
+  true as SameKeys<Infer<typeof LogTimeSchema>, Omit<TimeEntry, 'id'>>
+];
+
+describe('request schemas', () => {
+  it('cover the writable fields of each domain type', () => {
+    expect(keyChecks.every(Boolean)).toBe(true);
+  });
+
+  it('strip server-assigned and unknown fields', () => {
+    const parsed = UpdateTaskSchema.parse({
+      title: 'ok',
+      id: 'hijack',
+      projectId: 'other',
+      createdAt: '1999-01-01',
+      key: 'X-1',
+      junk: true
+    });
+    expect(parsed).toEqual({ title: 'ok' });
+  });
+
+  it('reject wrong types and out-of-range values', () => {
+    expect(UpdateTaskSchema.safeParse({ status: 123 }).success).toBe(false);
+    expect(UpdateTaskSchema.safeParse({ progress: 140 }).success).toBe(false);
+    expect(CreateTaskSchema.safeParse({ projectId: 'p1' }).success).toBe(false);
+    expect(LogTimeSchema.safeParse({ taskId: 't1', hours: 0 }).success).toBe(false);
+  });
+
+  it('apply defaults for optional collections and enums', () => {
+    expect(CreateTeamSchema.parse({ name: 'Core' }).memberIds).toEqual([]);
+    expect(CreateIterationSchema.parse({ projectId: 'p1', name: 'S1' }).status).toBe('planning');
+    expect(CreateWorkflowSchema.parse({ name: 'W', statuses: [] }).transitions).toEqual([]);
+  });
+
+  it('keep lifecycle fields writable for imports and backfills', () => {
+    const parsed = CreateTaskSchema.parse({
+      projectId: 'p1',
+      title: 'Imported',
+      completedAt: '2026-01-02T00:00:00.000Z',
+      actualStartDate: '2026-01-01T00:00:00.000Z'
+    });
+    expect(parsed.completedAt).toBe('2026-01-02T00:00:00.000Z');
+  });
+});

package/src/types/index.ts

@@ -300,6 +300,13 @@ export interface Iteration {
 
 export type AuthorType = 'user' | 'agent' | 'system';
 
+/** The identity a mutation is attributed to (see `CriticalPathEngine.withActor`). */
+export interface Actor {
+  userId: string;
+  username?: string;
+  actorType?: AuthorType;
+}
+
 export interface CommentReaction {
   emoji: string;
   userId: string;