@critical-path/core 0.53.0 → 0.55.0

package/dist/engine/index.js

@@ -7,7 +7,7 @@ import { DomainEventBus } from '../domain/events.js';
 import { validateAttachmentUrl } from '../domain/entities.js';
 import { validateCustomFieldValues, validateCustomFieldDefinitions } from '../domain/custom-fields.js';
 import { detectDependencyCycle, CircularDependencyError, precedenceOf } from '../domain/graph.js';
-import { ValidationError, NotFoundError, ForbiddenError } from '../domain/errors.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';
@@ -16,6 +16,8 @@ import { CreateTaskSchema } from '../schemas/index.js';
 import { buildTimelineLadder, aggregateConcreteEvidenceForTask } from '../domain/ladder.js';
 import { calculateTaskMetrics, reconstructTaskProgressHistory } from '../domain/metrics.js';
 import { calculateWorkloadDistribution } from '../domain/workload.js';
+import { getTaskEstimateHours, getSummaryTaskIds } from '../domain/effort.js';
+import { inferTaskProgress } from '../domain/metrics.js';
 /** Every caller-settable task field, derived from the create schema so new fields are never dropped. */
 const CREATE_TASK_FIELDS = Object.keys(CreateTaskSchema.shape);
 export class CriticalPathEngine {
@@ -361,12 +363,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 +405,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 +436,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 +447,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 +514,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 +544,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 +573,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 +726,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 +739,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 +792,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 +819,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 +830,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 +937,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)
@@ -1947,6 +2022,10 @@ export class CriticalPathEngine {
         let estimatedHours = 0;
         let loggedHours = 0;
         let totalProgress = 0;
+        let progressCount = 0;
+        // Summary tasks are spanned by their subtasks (counted once, through the leaves); canceled
+        // tasks keep their logged hours but leave the estimate and progress.
+        const summaries = getSummaryTaskIds(allTasks);
         for (const task of tasks) {
             const statusDef = resolveStatusDefinition(task.status, project?.statusDefinitions || workflow?.statuses);
             if (statusDef.category === 'completed') {
@@ -1955,18 +2034,16 @@ export class CriticalPathEngine {
             else if (statusDef.category === 'in_progress') {
                 activeTasks++;
             }
-            if (task.estimatedHours)
-                estimatedHours += task.estimatedHours;
-            if (task.loggedHours)
-                loggedHours += task.loggedHours;
-            if (typeof task.progress === 'number') {
-                totalProgress += task.progress;
-            }
-            else {
-                totalProgress += statusDef.category === 'completed' ? 100 : 0;
-            }
+            if (summaries.has(task.id))
+                continue;
+            loggedHours += task.loggedHours ?? 0;
+            if (statusDef.category === 'canceled')
+                continue;
+            estimatedHours += getTaskEstimateHours(task) ?? 0;
+            totalProgress += inferTaskProgress(task, { customStatusDefinitions: project?.statusDefinitions || workflow?.statuses }).progressPercentage;
+            progressCount++;
         }
-        const progressPercentage = totalTasks > 0 ? Math.round(totalProgress / totalTasks) : 0;
+        const progressPercentage = progressCount > 0 ? Math.round(totalProgress / progressCount) : 0;
         return {
             deliverable,
             totalTasks,
@@ -2119,9 +2196,9 @@ export class CriticalPathEngine {
         const dependencies = await this.loadDependencies(tasks);
         const schedule = options.schedule || project?.schedule || this.config.defaultSchedule;
         const projectStartDate = options.projectStartDate || project?.startDate;
-        const { calendars, levelResources, levelingPriority, effort } = this.resolveCpmModes(options);
+        const { calendars, levelResources, levelingPriority, effort, defaultEstimateHours } = this.resolveCpmModes(options);
         if (calendars === 'project')
-            return calculateCPM(projectId, tasks, dependencies, { schedule, projectStartDate, effort });
+            return calculateCPM(projectId, tasks, dependencies, { schedule, projectStartDate, effort, defaultEstimateHours });
         const { users, teams } = await this.loadPeople(options, [project?.tenantId]);
         return calculateCPM(projectId, tasks, dependencies, {
             schedule,
@@ -2131,7 +2208,8 @@ export class CriticalPathEngine {
             teams,
             levelResources,
             levelingPriority,
-            effort
+            effort,
+            defaultEstimateHours
         });
     }
     /**
@@ -2143,7 +2221,7 @@ export class CriticalPathEngine {
      * Rejects runs above `portfolioTaskLimit` tasks (default 5000).
      */
     async calculatePortfolioCriticalPath(options = {}) {
-        const { calendars, levelResources, levelingPriority, effort } = this.resolveCpmModes(options);
+        const { calendars, levelResources, levelingPriority, effort, defaultEstimateHours } = this.resolveCpmModes(options);
         let projects;
         if (options.projectIds) {
             const ids = [...new Set(options.projectIds)];
@@ -2189,7 +2267,7 @@ export class CriticalPathEngine {
             projectStartDate: p.startDate || options.projectStartDate,
             schedule: p.schedule || options.schedule || this.config.defaultSchedule,
             ...(mode ? { background: mode } : {})
-        })), dependencies, { calendars, users, teams, levelResources, levelingPriority, effort, projectOrder: options.projectOrder });
+        })), dependencies, { calendars, users, teams, levelResources, levelingPriority, effort, defaultEstimateHours, projectOrder: options.projectOrder });
     }
     /** Validated calendar and levelling modes, with engine defaults applied. */
     resolveCpmModes(options) {
@@ -2209,7 +2287,11 @@ export class CriticalPathEngine {
         if (effort !== 'estimate' && effort !== 'remaining') {
             throw new ValidationError(`Unknown effort "${effort}"; use "estimate" or "remaining".`);
         }
-        return { calendars, levelResources, levelingPriority, effort };
+        const defaultEstimateHours = options.defaultEstimateHours ?? this.config.criticalPathDefaultEstimateHours;
+        if (defaultEstimateHours !== undefined && !(Number.isFinite(defaultEstimateHours) && defaultEstimateHours >= 0)) {
+            throw new ValidationError('defaultEstimateHours must be a number of hours, 0 or more.');
+        }
+        return { calendars, levelResources, levelingPriority, effort, defaultEstimateHours };
     }
     /** Every dependency touching `tasks`, once each. */
     async loadDependencies(tasks) {