@critical-path/core 0.52.0 → 0.54.0

package/dist/engine/index.js

@@ -6,8 +6,8 @@ import { extractMentions } from '../utils/mentions.js';
 import { DomainEventBus } from '../domain/events.js';
 import { validateAttachmentUrl } from '../domain/entities.js';
 import { validateCustomFieldValues, validateCustomFieldDefinitions } from '../domain/custom-fields.js';
-import { detectDependencyCycle, CircularDependencyError } from '../domain/graph.js';
-import { ValidationError, NotFoundError, ForbiddenError } from '../domain/errors.js';
+import { detectDependencyCycle, CircularDependencyError, precedenceOf } from '../domain/graph.js';
+import { ValidationError, NotFoundError, ForbiddenError, ConflictError } from '../domain/errors.js';
 import { WebhookDispatcher, assertWebhookUrl } from '../webhooks/dispatcher.js';
 import { buildStorageKey, normalizeUploadData } from '../storage/file-storage.js';
 import { generateWebhookSecret } from '../webhooks/signature.js';
@@ -361,12 +361,28 @@ export class CriticalPathEngine {
         });
         return created;
     }
+    /**
+     * Updates a workflow. Removing a status that tasks in a project using this workflow are still in
+     * is refused (`ConflictError`): move those tasks first, or switch the project with `statusMapping`.
+     */
     async updateWorkflow(id, updates) {
         const existing = await this.getWorkflow(id);
         if (!existing)
             return null;
         await this.requireWorkspaceAccess('workspace.manage');
         updates = this.withoutTenant(updates);
+        if (updates.statuses) {
+            const kept = new Set(updates.statuses.map((status) => status.key));
+            const removed = existing.statuses.map((status) => status.key).filter((key) => !kept.has(key));
+            if (removed.length) {
+                for (const project of await this.projectsUsingWorkflow(existing)) {
+                    const stranded = [...new Set((await this.store.getTasks(project.id)).map((t) => t.status))].filter((key) => removed.includes(key));
+                    if (stranded.length) {
+                        throw new ConflictError(`Tasks in project "${project.id}" are still in ${stranded.map((k) => `"${k}"`).join(', ')}, which this update removes. Move them to another status first.`);
+                    }
+                }
+            }
+        }
         const updated = await this.store.updateWorkflow(id, updates);
         if (updated) {
             const now = new Date().toISOString();
@@ -387,11 +403,16 @@ export class CriticalPathEngine {
         }
         return updated;
     }
+    /** Deletes a workflow. Refused (`ConflictError`) while any project uses it, even as its default. */
     async deleteWorkflow(id) {
         const existing = await this.getWorkflow(id);
         if (!existing)
             return false;
         await this.requireWorkspaceAccess('workspace.manage');
+        const users = await this.projectsUsingWorkflow(existing);
+        if (users.length) {
+            throw new ConflictError(`Workflow "${id}" is used by ${users.length} project(s) (${users.map((p) => p.id).join(', ')}). Switch them to another workflow first.`);
+        }
         const deleted = await this.store.deleteWorkflow(id);
         if (deleted) {
             const now = new Date().toISOString();
@@ -413,7 +434,10 @@ export class CriticalPathEngine {
         return deleted;
     }
     async resolveProjectWorkflow(projectId) {
-        const project = await this.store.getProject(projectId);
+        return this.workflowFor(await this.store.getProject(projectId));
+    }
+    /** The workflow a project (or a project as it would be after an update) uses. */
+    async workflowFor(project) {
         if (project?.workflow)
             return project.workflow;
         if (project?.workflowId) {
@@ -421,14 +445,33 @@ export class CriticalPathEngine {
             if (wf && (wf.tenantId ?? undefined) === (project.tenantId ?? undefined))
                 return wf;
         }
+        return (await this.defaultWorkflowFor(project?.tenantId)) ?? DEFAULT_SOFTWARE_WORKFLOW;
+    }
+    /** The tenant's stored default workflow: the one marked `isDefault`, else the first. */
+    async defaultWorkflowFor(tenantId) {
         // Only fall back to workflows from the project's own tenant.
-        const workflows = (await this.store.getWorkflows()).filter((w) => w.tenantId === project?.tenantId);
-        const defaultWf = workflows.find((w) => w.isDefault);
-        if (defaultWf)
-            return defaultWf;
-        if (workflows.length > 0)
-            return workflows[0];
-        return DEFAULT_SOFTWARE_WORKFLOW;
+        const workflows = (await this.store.getWorkflows()).filter((w) => w.tenantId === tenantId);
+        return workflows.find((w) => w.isDefault) ?? workflows[0];
+    }
+    /** The statuses tasks in a project may have: its own definitions, else its workflow's. */
+    async statusDefinitionsFor(project) {
+        return project?.statusDefinitions?.length ? project.statusDefinitions : (await this.workflowFor(project)).statuses;
+    }
+    /** Projects whose tasks follow `workflow`, explicitly or as their tenant's default. */
+    async projectsUsingWorkflow(workflow) {
+        const projects = await this.store.getProjects(workflow.tenantId ? { tenantId: workflow.tenantId } : undefined);
+        const using = [];
+        for (const project of projects) {
+            if ((project.tenantId ?? undefined) === (workflow.tenantId ?? undefined) && (await this.workflowFor(project)).id === workflow.id)
+                using.push(project);
+        }
+        return using;
+    }
+    /** Throws unless `status` is one of the project's statuses. */
+    assertKnownStatus(status, definitions) {
+        if (definitions.length && !definitions.some((d) => d.key === status)) {
+            throw new ValidationError(`Status "${status}" is not in this project's workflow (${definitions.map((d) => d.key).join(', ')}).`);
+        }
     }
     async getAllowedTaskTransitions(taskId) {
         const task = await this.getTask(taskId);
@@ -469,6 +512,13 @@ export class CriticalPathEngine {
         // Views always use the actor's tenant (possibly none); only trusted base-engine calls may set it.
         const input = { ...project, tenantId: this.actor ? this.actor.tenantId : project.tenantId };
         await this.assertUsableWorkflow(input.workflowId, input.tenantId);
+        // Pin the workflow the project starts with, so adding a new default workflow later does not
+        // silently change it.
+        if (!input.workflowId && !input.workflow) {
+            const workflow = await this.defaultWorkflowFor(input.tenantId);
+            if (workflow)
+                input.workflowId = workflow.id;
+        }
         // The creator administers the project they create.
         if (this.actor && this.actor.userId !== 'anonymous' && !input.members?.some((m) => m.userId === this.actor.userId)) {
             input.members = [...(input.members ?? []), { userId: this.actor.userId, role: 'admin' }];
@@ -492,7 +542,16 @@ export class CriticalPathEngine {
         });
         return created;
     }
-    async updateProject(id, updates) {
+    /**
+     * Updates a project. When the update changes which statuses the project has (`workflowId`,
+     * `workflow` or `statusDefinitions`), every task in a status the project no longer has must be
+     * moved: pass `statusMapping` (old status key -> new status key). Without a mapping for each such
+     * status the update is refused with a `ConflictError`, so no task is left in an unreachable status.
+     */
+    async updateProject(id, updates, options = {}) {
+        return this.inTransaction((engine) => engine.updateProjectNow(id, updates, options));
+    }
+    async updateProjectNow(id, updates, options) {
         const existing = await this.getProject(id);
         if (!existing)
             return null;
@@ -512,7 +571,24 @@ export class CriticalPathEngine {
         if (updates.workflowId && updates.workflowId !== existing.workflowId) {
             await this.assertUsableWorkflow(updates.workflowId, existing.tenantId);
         }
+        // Tasks whose status the project will no longer have, and where they go
+        const moves = [];
+        if ('workflowId' in updates || 'workflow' in updates || 'statusDefinitions' in updates) {
+            const next = new Set((await this.statusDefinitionsFor({ ...existing, ...updates })).map((d) => d.key));
+            const mapping = options.statusMapping ?? {};
+            const stranded = (await this.store.getTasks(id)).filter((task) => !next.has(task.status));
+            const unmapped = [...new Set(stranded.map((task) => task.status))].filter((key) => !next.has(mapping[key]));
+            if (unmapped.length) {
+                throw new ConflictError(`Tasks are in ${unmapped.map((k) => `"${k}"`).join(', ')}, which the project will no longer have. ` +
+                    `Pass statusMapping with a new status for each (available: ${[...next].join(', ')}).`);
+            }
+            moves.push(...stranded.map((task) => ({ taskId: task.id, status: mapping[task.status] })));
+        }
         const updated = await this.store.updateProject(id, updates);
+        // The old status is not in the new workflow, so there is no transition to check
+        for (const move of moves) {
+            await this.elevated().updateTask(move.taskId, { status: move.status }, { ...(this.actor ? { actor: this.actor } : {}), ignoreTransitions: true });
+        }
         if (updated) {
             const now = new Date().toISOString();
             const event = {
@@ -648,9 +724,11 @@ export class CriticalPathEngine {
         await this.assertValidParent(input.parentId, projectId);
         const defaultStatus = workflow?.defaultStatusKey || 'todo';
         const initialStatus = processedInput.status || taskInput.status || defaultStatus;
+        const statusDefinitions = await this.statusDefinitionsFor(project);
+        this.assertKnownStatus(initialStatus, statusDefinitions);
         const now = new Date().toISOString();
         // Derive initial lifecycle timestamps and semantic status
-        const statusDef = resolveStatusDefinition(initialStatus, project?.statusDefinitions || workflow?.statuses);
+        const statusDef = resolveStatusDefinition(initialStatus, statusDefinitions);
         const inProgress = statusDef.category === 'in_progress';
         const completed = statusDef.category === 'completed';
         const isBlocked = input.isBlocked ?? false;
@@ -659,15 +737,16 @@ export class CriticalPathEngine {
             projectId,
             title: processedInput.title || taskInput.title,
             status: initialStatus,
-            semanticStatus: input.semanticStatus ?? statusDef.category,
+            // Always derived from the status, so every module agrees on it
+            semanticStatus: statusDef.category,
             priority: processedInput.priority || taskInput.priority || 'medium',
             taskType: processedInput.taskType || taskInput.taskType || 'task',
             actualStartDate: input.actualStartDate ?? (inProgress ? now : undefined),
             actualEndDate: input.actualEndDate ?? (completed || statusDef.category === 'canceled' ? now : undefined),
             completedAt: input.completedAt ?? (completed ? now : undefined),
-            loggedHours: input.loggedHours ?? 0,
-            inProgressSince: input.inProgressSince ?? (inProgress ? now : undefined),
-            blockedSince: input.blockedSince ?? (isBlocked && inProgress ? now : undefined),
+            loggedHours: 0,
+            inProgressSince: inProgress ? now : undefined,
+            blockedSince: isBlocked && inProgress ? now : undefined,
             progress: input.progress ?? (completed ? 100 : 0),
             isBlocked,
             blockedReason: input.blockedReason ?? null,
@@ -711,8 +790,13 @@ export class CriticalPathEngine {
         // Plugins run first; their output is then validated like caller input. Identity and
         // ownership fields are never changed by hooks.
         const { id: _id, projectId: _projectId, createdAt: _createdAt, ...processedUpdates } = await this.plugins.runBeforeTaskUpdate(id, taskUpdates);
+        // Derived from the status below; never taken from callers or hooks
+        delete processedUpdates.semanticStatus;
         // Validate workflow transition invariant
         if (processedUpdates.status && processedUpdates.status !== existing.status) {
+            this.assertKnownStatus(processedUpdates.status, await this.statusDefinitionsFor(project));
+        }
+        if (processedUpdates.status && processedUpdates.status !== existing.status && !options?.ignoreTransitions) {
             const isValid = validateTransition(workflow || undefined, existing.status, processedUpdates.status);
             if (!isValid) {
                 throw new WorkflowValidationError(existing.status, processedUpdates.status, workflow?.id);
@@ -733,7 +817,7 @@ export class CriticalPathEngine {
         const effectiveCategory = newStatusDef?.category ?? existingStatusDef.category;
         // Auto-update execution/completion timestamps if status changes
         if (processedUpdates.status && processedUpdates.status !== existing.status && newStatusDef) {
-            processedUpdates.semanticStatus = processedUpdates.semanticStatus ?? newStatusDef.category;
+            processedUpdates.semanticStatus = newStatusDef.category;
             // 1. Leaving in_progress: finalize active session duration and blocked duration
             if (existingStatusDef.category === 'in_progress' && newStatusDef.category !== 'in_progress') {
                 const inProgressSince = existing.inProgressSince;
@@ -744,9 +828,6 @@ export class CriticalPathEngine {
                         const sessionSeconds = Math.max(0, (endMs - startMs) / 1000);
                         processedUpdates.actualDurationSeconds =
                             (processedUpdates.actualDurationSeconds ?? existing.actualDurationSeconds ?? 0) + sessionSeconds;
-                        if (processedUpdates.actualHours === undefined) {
-                            processedUpdates.actualHours = Math.round((processedUpdates.actualDurationSeconds / 3600) * 100) / 100;
-                        }
                         if (processedUpdates.actualDurationMinutes === undefined) {
                             processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualDurationSeconds / 60);
                         }
@@ -854,18 +935,10 @@ export class CriticalPathEngine {
         else if (processedUpdates.isBlocked === false && (existing.blockedSince || processedUpdates.blockedSince)) {
             processedUpdates.blockedSince = null;
         }
-        // Mutual sync for manual duration/effort edits
-        if (processedUpdates.actualDurationSeconds !== undefined && processedUpdates.actualHours === undefined) {
-            processedUpdates.actualHours = Math.round((processedUpdates.actualDurationSeconds / 3600) * 100) / 100;
-            if (processedUpdates.actualDurationMinutes === undefined) {
-                processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualDurationSeconds / 60);
-            }
-        }
-        else if (processedUpdates.actualHours !== undefined && processedUpdates.actualDurationSeconds === undefined) {
-            processedUpdates.actualDurationSeconds = Math.round(processedUpdates.actualHours * 3600);
-            if (processedUpdates.actualDurationMinutes === undefined) {
-                processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualHours * 60);
-            }
+        // Elapsed time (actualDuration*) and effort (actualHours, loggedHours) are separate quantities:
+        // keep the elapsed minutes in step with the seconds, and never derive effort from the clock.
+        if (processedUpdates.actualDurationSeconds !== undefined && processedUpdates.actualDurationMinutes === undefined) {
+            processedUpdates.actualDurationMinutes = Math.round(processedUpdates.actualDurationSeconds / 60);
         }
         const updated = await this.store.updateTask(id, processedUpdates);
         if (!updated)
@@ -976,9 +1049,12 @@ export class CriticalPathEngine {
         return updated;
     }
     /**
-     * After a task completes or is canceled, unblocks downstream tasks whose upstream tasks are all
-     * completed or canceled. Runs on an elevated view, so upstream tasks the caller cannot read still
-     * count, and resolves each task's status against its own project's definitions.
+     * After a task completes or is canceled, publishes `task.unblocked` for each downstream task whose
+     * upstream tasks are now all completed or canceled, so it is free to start. Dependency blocking is
+     * derived (see `getTaskLifecycleState`), so nothing is written to the task: a manual block
+     * (`isBlocked`, `blockedReason`) stays until someone clears it. Runs on an elevated view, so
+     * upstream tasks the caller cannot read still count, and resolves each task's status against its
+     * own project's definitions.
      */
     async checkAndUnblockDownstreamTasks(completedTask) {
         try {
@@ -995,39 +1071,28 @@ export class CriticalPathEngine {
                 }
                 return resolveStatusDefinition(task.status, statusDefsByProject.get(task.projectId)).category;
             };
+            const isFinished = async (task) => {
+                const category = await categoryOf(task);
+                return category === 'completed' || category === 'canceled';
+            };
             for (const downstream of graph.downstreamTasks) {
-                const category = await categoryOf(downstream);
-                if (category === 'completed' || category === 'canceled')
-                    continue;
-                // Nothing to unblock; don't publish task.unblocked for tasks that were never blocked.
-                if (!downstream.isBlocked && !downstream.blockedReason && !downstream.blockedSince)
+                if (await isFinished(downstream))
                     continue;
                 const downstreamGraph = await engine.getTaskDependencyGraph(downstream.id);
                 let allSatisfied = true;
                 for (const up of downstreamGraph.upstreamTasks) {
-                    const upCategory = await categoryOf(up);
-                    if (upCategory !== 'completed' && upCategory !== 'canceled') {
+                    if (!(await isFinished(up))) {
                         allSatisfied = false;
                         break;
                     }
                 }
                 if (!allSatisfied)
                     continue;
-                const updates = { isBlocked: false, blockedReason: null };
-                if (downstream.blockedSince) {
-                    const startMs = new Date(downstream.blockedSince).getTime();
-                    const endMs = Date.now();
-                    if (!isNaN(startMs) && endMs >= startMs) {
-                        updates.blockedDurationSeconds = (downstream.blockedDurationSeconds ?? 0) + (endMs - startMs) / 1000;
-                    }
-                    updates.blockedSince = null;
-                }
-                const updatedDownstream = (await this.store.updateTask(downstream.id, updates)) ?? downstream;
                 await this.publishEvent({
                     name: 'task.unblocked',
                     aggregateId: downstream.id,
                     aggregateType: 'Task',
-                    payload: { task: updatedDownstream, upstreamTaskId: completedTask.id }
+                    payload: { task: downstream, upstreamTaskId: completedTask.id }
                 });
                 await this.store.logActivity({
                     projectId: downstream.projectId,
@@ -1179,6 +1244,9 @@ export class CriticalPathEngine {
     // --- Task Dependencies & Graph ---
     /** Adds a dependency. Adding one that already exists (same tasks and type) returns the existing one. */
     async addDependency(dep) {
+        if (dep.type !== 'blocking' && dep.type !== 'relates_to') {
+            throw new ValidationError(`Dependency type must be 'blocking' or 'relates_to', got "${String(dep.type)}".`);
+        }
         const [task, upstream] = await Promise.all([this.getTask(dep.taskId), this.getTask(dep.dependsOnTaskId)]);
         if (!task)
             throw new NotFoundError(`Task "${dep.taskId}" not found.`);
@@ -1188,11 +1256,13 @@ export class CriticalPathEngine {
         const duplicate = (await this.store.getDependencies(dep.taskId)).find((d) => d.taskId === dep.taskId && d.dependsOnTaskId === dep.dependsOnTaskId && d.type === dep.type);
         if (duplicate)
             return duplicate;
-        // Enforce Directed Acyclic Graph (DAG) Invariant
-        const reachableDeps = await this.collectUpstreamDependencies(dep.dependsOnTaskId);
-        const cycleCheck = detectDependencyCycle(reachableDeps, dep);
-        if (cycleCheck.hasCycle) {
-            throw new CircularDependencyError(dep.taskId, dep.dependsOnTaskId, cycleCheck.cyclePath);
+        // Enforce the Directed Acyclic Graph (DAG) invariant. Informational links never form cycles.
+        if (dep.type === 'blocking') {
+            const reachableDeps = await this.collectUpstreamDependencies(dep.dependsOnTaskId);
+            const cycleCheck = detectDependencyCycle(reachableDeps, dep);
+            if (cycleCheck.hasCycle) {
+                throw new CircularDependencyError(dep.taskId, dep.dependsOnTaskId, cycleCheck.cyclePath);
+            }
         }
         const created = await this.store.addDependency(dep);
         const now = new Date().toISOString();
@@ -1222,12 +1292,14 @@ export class CriticalPathEngine {
             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))
+                    // getDependencies returns edges touching the task in both directions; follow the ones
+                    // where a visited task waits for another.
+                    const edge = precedenceOf(d);
+                    if (!edge || !visited.has(edge.after))
                         continue;
                     edges.set(d.id, d);
-                    if (!visited.has(d.dependsOnTaskId) && !next.includes(d.dependsOnTaskId)) {
-                        next.push(d.dependsOnTaskId);
+                    if (!visited.has(edge.before) && !next.includes(edge.before)) {
+                        next.push(edge.before);
                     }
                 }
             }
@@ -1242,12 +1314,14 @@ export class CriticalPathEngine {
         const dependencies = await this.store.getDependencies(taskId);
         const upstreamTaskIds = new Set();
         const downstreamTaskIds = new Set();
+        // Upstream and downstream follow scheduling edges only; `relates_to` links stay in `dependencies`.
         for (const dep of dependencies) {
-            if (dep.taskId === taskId) {
-                upstreamTaskIds.add(dep.dependsOnTaskId);
+            const edge = precedenceOf(dep);
+            if (edge?.after === taskId) {
+                upstreamTaskIds.add(edge.before);
             }
-            else if (dep.dependsOnTaskId === taskId) {
-                downstreamTaskIds.add(dep.taskId);
+            else if (edge?.before === taskId) {
+                downstreamTaskIds.add(edge.after);
             }
         }
         const upstreamTasks = (await Promise.all(Array.from(upstreamTaskIds).map((id) => this.getTask(id)))).filter((t) => t !== null);