@critical-path/core 0.21.0 → 0.23.0

package/src/domain/entities.ts

@@ -29,6 +29,7 @@ import { validateTransition, WorkflowValidationError } from '../utils/workflow.j
 import { resolveStatusDefinition } from '../utils/status.js';
 import { validateCustomFieldValues } from './custom-fields.js';
 import { generateProjectKey } from '../utils/key.js';
+import { ValidationError } from './errors.js';
 
 export abstract class BaseEntity {
   public readonly id: string;
@@ -294,8 +295,8 @@ export class TaskEntity extends BaseEntity {
   public logTime(
     entry: { hours: number; isBillable?: boolean; userId?: string; description?: string }
   ): TimeEntry {
-    if (entry.hours <= 0) {
-      throw new Error('Logged hours must be a positive number.');
+    if (!Number.isFinite(entry.hours) || entry.hours <= 0) {
+      throw new ValidationError('Logged hours must be a positive number.');
     }
 
     this.loggedHours = (this.loggedHours || 0) + entry.hours;

package/src/domain/errors.ts

@@ -0,0 +1,19 @@
+/**
+ * Thrown when input fails a domain rule. Route handlers map it to HTTP 400.
+ */
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+/**
+ * Thrown when a referenced entity does not exist. Route handlers map it to HTTP 404.
+ */
+export class NotFoundError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}

package/src/domain/events.ts

@@ -134,6 +134,11 @@ export interface ProjectUpdatedEvent extends DomainEvent<{ project: Project; pre
   readonly aggregateType: 'Project';
 }
 
+export interface ProjectDeletedEvent extends DomainEvent<{ projectId: string; name: string; deletedTaskIds: string[] }> {
+  readonly name: 'project.deleted';
+  readonly aggregateType: 'Project';
+}
+
 export interface WorkflowCreatedEvent extends DomainEvent<{ workflow: Workflow }> {
   readonly name: 'workflow.created';
   readonly aggregateType: 'Workflow';
@@ -207,6 +212,7 @@ export type CriticalPathDomainEvent =
   | TaskDependencyAddedEvent
   | ProjectCreatedEvent
   | ProjectUpdatedEvent
+  | ProjectDeletedEvent
   | WorkflowCreatedEvent
   | WorkflowUpdatedEvent
   | WorkflowDeletedEvent

package/src/domain/index.ts

@@ -1,6 +1,7 @@
 export * from './events.js';
 export * from './custom-fields.js';
 export * from './graph.js';
+export * from './errors.js';
 export * from './entities.js';
 export * from './cpm.js';
 export * from './ladder.js';

package/src/engine/actor.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { CriticalPathEngine } from '../index.js';
+
+describe('CriticalPathEngine.withActor', () => {
+  it('attributes mutations to the scoped actor and ignores identity claimed in payloads', async () => {
+    const engine = new CriticalPathEngine();
+    const alice = engine.withActor({ userId: 'alice', username: 'Alice' });
+
+    const project = await alice.createProject({ key: 'ACT', name: 'Actors', ownerId: 'mallory' });
+    const task = await alice.createTask({ projectId: project.id, title: 'Scoped' });
+    expect(task.reporterId).toBe('alice');
+
+    await alice.updateTask(task.id, { title: 'Renamed', actorId: 'ceo', actor: { userId: 'ceo' } });
+    const comment = await alice.addComment({ taskId: task.id, content: 'hi', authorId: 'ceo', authorType: 'agent' });
+    const reacted = await alice.addCommentReaction(comment.id, { emoji: '👍', userId: 'ceo' });
+    const entry = await alice.logTime({ taskId: task.id, hours: 1, userId: 'ceo' } as any);
+    const attachment = await alice.createAttachment({
+      taskId: task.id,
+      uploaderId: 'ceo',
+      filename: 'spec.md',
+      mimeType: 'text/markdown',
+      sizeBytes: 1,
+      url: 'https://example.com/spec.md'
+    });
+
+    expect(comment.authorId).toBe('alice');
+    expect(comment.authorType).toBe('user');
+    expect(reacted?.reactions?.[0].userId).toBe('alice');
+    expect(entry.userId).toBe('alice');
+    expect(attachment.uploaderId).toBe('alice');
+
+    const activities = await engine.store.getActivities({ projectId: project.id });
+    expect(activities.length).toBeGreaterThan(0);
+    expect(activities.every((a) => a.actorId === 'alice')).toBe(true);
+  });
+
+  it('does not change the base engine, and concurrent views stay isolated', async () => {
+    const engine = new CriticalPathEngine();
+    const project = await engine.createProject({ key: 'ISO', name: 'Isolation' });
+
+    const [a, b] = await Promise.all([
+      engine.withActor({ userId: 'a' }).createTask({ projectId: project.id, title: 'A' }),
+      engine.withActor({ userId: 'b' }).createTask({ projectId: project.id, title: 'B' })
+    ]);
+    expect(a.reporterId).toBe('a');
+    expect(b.reporterId).toBe('b');
+    expect(engine.actor).toBeUndefined();
+
+    // Views share state with the base engine
+    expect(await engine.getTask(a.id)).not.toBeNull();
+  });
+
+  it('still lets explicit updateTask options override the scoped actor', async () => {
+    const engine = new CriticalPathEngine();
+    const project = await engine.createProject({ key: 'OPT', name: 'Options' });
+    const task = await engine.createTask({ projectId: project.id, title: 'T' });
+
+    await engine.withActor({ userId: 'alice' }).updateTask(task.id, { title: 'T2' }, { actorId: 'automation' });
+    const activities = await engine.store.getActivities({ taskId: task.id });
+    expect(activities.some((a) => a.actorId === 'automation')).toBe(true);
+  });
+});

package/src/engine/index.ts

@@ -1,4 +1,5 @@
 import type {
+  Actor,
   CriticalPathConfig,
   Project,
   Task,
@@ -56,6 +57,7 @@ import {
   TaskDeletedEvent,
   ProjectCreatedEvent,
   ProjectUpdatedEvent,
+  ProjectDeletedEvent,
   WorkflowCreatedEvent,
   WorkflowUpdatedEvent,
   WorkflowDeletedEvent,
@@ -80,6 +82,7 @@ import {
 import { validateAttachmentUrl, AttachmentValidationError } from '../domain/entities.js';
 import { validateCustomFieldValues } from '../domain/custom-fields.js';
 import { detectDependencyCycle, CircularDependencyError } from '../domain/graph.js';
+import { ValidationError, NotFoundError } from '../domain/errors.js';
 import { calculateCPM, type CPMOptions } from '../domain/cpm.js';
 import { buildTimelineLadder, aggregateConcreteEvidenceForTask } from '../domain/ladder.js';
 import {
@@ -96,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;
@@ -118,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) {
@@ -180,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 }
     });
@@ -206,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 }
       });
@@ -233,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 }
       });
@@ -304,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 }
     });
@@ -331,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 }
       });
@@ -340,6 +362,46 @@ export class CriticalPathEngine {
     return updated;
   }
 
+  /**
+   * Deletes a project and its tasks. Each task goes through `deleteTask`, so plugin
+   * hooks run and `task.deleted` events fire before `project.deleted` is published.
+   */
+  async deleteProject(id: string): Promise<boolean> {
+    const existing = await this.store.getProject(id);
+    if (!existing) return false;
+
+    const tasks = await this.store.getTasks(id);
+    const deletedTaskIds: string[] = [];
+    for (const task of tasks) {
+      if (await this.deleteTask(task.id)) {
+        deletedTaskIds.push(task.id);
+      }
+    }
+
+    const deleted = await this.store.deleteProject(id);
+    if (deleted) {
+      const now = new Date().toISOString();
+      const event: ProjectDeletedEvent = {
+        id: `evt_${Math.random().toString(36).substring(2, 9)}`,
+        name: 'project.deleted',
+        aggregateId: id,
+        aggregateType: 'Project',
+        occurredAt: now,
+        payload: { projectId: id, name: existing.name, deletedTaskIds }
+      };
+      await this.events.publish(event);
+
+      await this.store.logActivity({
+        projectId: id,
+        actorId: this.actorIdOr('system'),
+        action: 'project.deleted',
+        details: { name: existing.name, deletedTaskCount: deletedTaskIds.length }
+      });
+      this.dispatchWebhook('project.deleted', { projectId: id, name: existing.name, deletedTaskIds });
+    }
+    return deleted;
+  }
+
   // --- Tasks ---
   async getTasks(projectId?: string): Promise<Task[]> {
     return this.store.getTasks(projectId);
@@ -350,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);
@@ -435,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 }
     });
@@ -462,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
@@ -861,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 }
           });
@@ -905,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 }
       });
@@ -916,14 +986,9 @@ export class CriticalPathEngine {
 
   // --- Task Dependencies & Graph ---
   async addDependency(dep: Omit<TaskDependency, 'id'>): Promise<TaskDependency> {
-    const existingDependencies = await this.store.getDependencies(dep.taskId);
-    const allProjectDeps = [
-      ...existingDependencies,
-      ...(await this.store.getDependencies(dep.dependsOnTaskId))
-    ];
-
     // Enforce Directed Acyclic Graph (DAG) Invariant
-    const cycleCheck = detectDependencyCycle(allProjectDeps, dep);
+    const reachableDeps = await this.collectUpstreamDependencies(dep.dependsOnTaskId);
+    const cycleCheck = detectDependencyCycle(reachableDeps, dep);
     if (cycleCheck.hasCycle) {
       throw new CircularDependencyError(dep.taskId, dep.dependsOnTaskId, cycleCheck.cyclePath);
     }
@@ -944,6 +1009,37 @@ export class CriticalPathEngine {
     return created;
   }
 
+  /**
+   * Collects every dependency edge reachable upstream from `startTaskId`. A new edge
+   * `taskId -> dependsOnTaskId` creates a cycle exactly when `taskId` is reachable from
+   * `dependsOnTaskId`, so this is the full set of edges the cycle check needs.
+   */
+  private async collectUpstreamDependencies(startTaskId: string): Promise<TaskDependency[]> {
+    const edges = new Map<string, TaskDependency>();
+    const visited = new Set<string>();
+    let frontier = [startTaskId];
+
+    while (frontier.length > 0) {
+      const next: string[] = [];
+      const results = await Promise.all(frontier.map((id) => this.store.getDependencies(id)));
+      frontier.forEach((id) => visited.add(id));
+
+      for (const deps of results) {
+        for (const d of deps) {
+          // getDependencies returns edges in both directions; follow only outgoing ones.
+          if (!visited.has(d.taskId)) continue;
+          edges.set(d.id, d);
+          if (!visited.has(d.dependsOnTaskId) && !next.includes(d.dependsOnTaskId)) {
+            next.push(d.dependsOnTaskId);
+          }
+        }
+      }
+      frontier = next;
+    }
+
+    return Array.from(edges.values());
+  }
+
   async getTaskDependencyGraph(taskId: string): Promise<TaskDependencyGraph> {
     const dependencies = await this.store.getDependencies(taskId);
     const upstreamTaskIds = new Set<string>();
@@ -996,8 +1092,8 @@ export class CriticalPathEngine {
 
   // --- Time Tracking ---
   async logTime(entry: Omit<TimeEntry, 'id' | 'loggedAt' | 'userId'> & { userId?: string; loggedAt?: string }): Promise<TimeEntry> {
-    if (entry.hours <= 0) {
-      throw new Error('Logged hours must be a positive number.');
+    if (!Number.isFinite(entry.hours) || entry.hours <= 0) {
+      throw new ValidationError('Logged hours must be a positive number.');
     }
 
     const task = await this.store.getTask(entry.taskId);
@@ -1014,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
     };
 
@@ -1044,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();
@@ -1110,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;
 
@@ -1155,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;
 
@@ -1199,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();
@@ -1288,7 +1392,7 @@ export class CriticalPathEngine {
   async readAttachmentText(id: string): Promise<string> {
     const attachment = await this.getAttachment(id);
     if (!attachment) {
-      throw new Error(`Attachment with id "${id}" not found.`);
+      throw new NotFoundError(`Attachment with id "${id}" not found.`);
     }
 
     if (attachment.storageKey && this.fileStorage && typeof this.fileStorage.download === 'function') {
@@ -1430,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 }
     });
@@ -1483,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 }
       });
@@ -1511,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 }
       });
@@ -1661,7 +1765,7 @@ export class CriticalPathEngine {
   ): Promise<TimelineLadder> {
     const project = await this.store.getProject(projectId);
     if (!project) {
-      throw new Error(`Project with ID "${projectId}" not found.`);
+      throw new NotFoundError(`Project with ID "${projectId}" not found.`);
     }
 
     let tasks = await this.store.getTasks(projectId);

package/src/index.test.ts

@@ -3,6 +3,30 @@ import { CriticalPathEngine, deriveTaskLifecycleState, DEFAULT_VFX_WORKFLOW } fr
 import type { CriticalPathPlugin } from './types/index.js';
 
 describe('CriticalPathEngine Core Tests', () => {
+  it('deletes a project with its tasks and publishes deletion events', async () => {
+    const engine = new CriticalPathEngine();
+    const proj = await engine.createProject({ key: 'DEL', name: 'Doomed Project' });
+    const keep = await engine.createProject({ key: 'KEEP', name: 'Survivor' });
+    const t1 = await engine.createTask({ projectId: proj.id, title: 'One' });
+    const t2 = await engine.createTask({ projectId: proj.id, title: 'Two' });
+    const other = await engine.createTask({ projectId: keep.id, title: 'Other' });
+
+    const published: string[] = [];
+    engine.events.subscribe('*', (event) => {
+      published.push(event.name);
+    });
+
+    expect(await engine.deleteProject(proj.id)).toBe(true);
+    expect(await engine.getProject(proj.id)).toBeNull();
+    expect(await engine.getTask(t1.id)).toBeNull();
+    expect(await engine.getTask(t2.id)).toBeNull();
+    expect(await engine.getTask(other.id)).not.toBeNull();
+    expect(published.filter((n) => n === 'task.deleted')).toHaveLength(2);
+    expect(published.at(-1)).toBe('project.deleted');
+
+    expect(await engine.deleteProject(proj.id)).toBe(false);
+  });
+
   it('creates projects and tasks with activity logs', async () => {
     const engine = new CriticalPathEngine();
 

package/src/store/sqlite.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect, beforeEach } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { SQLiteStore } from './sqlite.js';
 
 describe('SQLiteStore', () => {
@@ -194,3 +197,22 @@ describe('SQLiteStore', () => {
     expect(remaining).toHaveLength(0);
   });
 });
+
+describe('SQLiteStore outside the vitest runtime', () => {
+  const distEntry = fileURLToPath(new URL('../../dist/index.js', import.meta.url));
+
+  // vitest injects `require` into ESM modules, which once hid an `eval("require(...)")` failure
+  // that broke `new SQLiteStore({ filename })` in plain Node. Run the built package in a real Node process.
+  it.skipIf(!existsSync(distEntry))('constructs from a filename in a plain Node ESM process', () => {
+    const script = `
+      const { SQLiteStore } = await import(${JSON.stringify(pathToFileURL(distEntry).href)});
+      const store = new SQLiteStore({ filename: ':memory:' });
+      const project = await store.createProject({ key: 'SMOKE', name: 'Smoke' });
+      process.stdout.write(project.key);
+    `;
+    const output = execFileSync(process.execPath, ['--input-type=module', '--no-warnings', '-e', script], {
+      encoding: 'utf8'
+    });
+    expect(output).toBe('SMOKE');
+  });
+});

package/src/store/sqlite.ts

@@ -41,7 +41,13 @@ export class SQLiteStore implements StorageAdapter {
         throw new Error('SQLiteStore is only available in Node.js environments.');
       }
       try {
-        const nodeSqlite = eval("require('node:sqlite')");
+        // `require` is undefined in ESM, and a static import would break browser bundles of core.
+        const nodeSqlite = (globalThis as any).process?.getBuiltinModule?.('node:sqlite') as
+          | typeof import('node:sqlite')
+          | undefined;
+        if (!nodeSqlite) {
+          throw new Error('process.getBuiltinModule is unavailable (requires Node.js 22.3+)');
+        }
         this.db = new nodeSqlite.DatabaseSync(config.filename || ':memory:');
       } catch (err: any) {
         throw new Error(`Failed to load node:sqlite module: ${err.message}`);

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;
@@ -409,6 +416,7 @@ export interface Webhook {
 export type WebhookEvent =
   | 'project.created'
   | 'project.updated'
+  | 'project.deleted'
   | 'task.created'
   | 'task.updated'
   | 'task.deleted'

package/src/utils/fractional-index.test.ts

@@ -120,6 +120,43 @@ describe('fractional-index', () => {
         current = next;
       }
     });
+
+    it('handles repeated insertions directly after the same lower bound', () => {
+      const lower = 'a0';
+      let upper = 'a1';
+
+      // Repeatedly drop a card just below the first card
+      for (let i = 0; i < 50; i++) {
+        const next = generateKeyBetween(lower, upper);
+        expect(lower < next).toBe(true);
+        expect(next < upper).toBe(true);
+        upper = next;
+      }
+    });
+
+    it('keeps keys strictly ordered under random insertions', () => {
+      const keys = ['a0', 'a1'];
+      let seed = 42;
+      const random = () => {
+        seed = (seed * 1103515245 + 12345) % 2147483648;
+        return seed / 2147483648;
+      };
+
+      for (let i = 0; i < 500; i++) {
+        const idx = Math.floor(random() * (keys.length + 1));
+        const next = generateKeyBetween(keys[idx - 1] ?? null, keys[idx] ?? null);
+        keys.splice(idx, 0, next);
+      }
+
+      for (let i = 1; i < keys.length; i++) {
+        expect(keys[i - 1] < keys[i]).toBe(true);
+      }
+    });
+
+    it('throws when the lower bound does not sort before the upper bound', () => {
+      expect(() => generateKeyBetween('a1', 'a0')).toThrow(RangeError);
+      expect(() => generateKeyBetween('a0', 'a0')).toThrow(RangeError);
+    });
   });
 
   describe('generateNKeysBetween', () => {