@critical-path/core 0.43.1 → 0.45.0

package/README.md

@@ -355,7 +355,7 @@ const leveled = await engine.calculateCriticalPath('proj_123', { calendars: 'ass
 console.log(leveled.unleveledProjectEndDate, '->', leveled.projectEndDate);
 ```
 
-With `calendars: 'assignee'` (or `criticalPathCalendars: 'assignee'` on the engine), each task uses its assignee's schedule, then its team's, then the project calendar. Passes run on dates, slack is measured in each task's calendar, and each calendar is evaluated in its own `timezone` (IANA name; default UTC), including daylight-saving changes. `levelResources: true` additionally delays tasks so nobody works on two at once (priority rule `levelingPriority`, default least slack), reporting `levelingDelayHours` and `waitingOn` per task. Tasks with `allocation` below 1 take that share of their assignee (a 16h task at 0.5 spans 32 working hours); levelling fits them within 100% per person, and `overallocations` lists who is booked above 100% and when.
+With `calendars: 'assignee'` (or `criticalPathCalendars: 'assignee'` on the engine), each task uses its assignee's schedule, then its team's, then the project calendar. Passes run on dates, slack is measured in each task's calendar, and each calendar is evaluated in its own `timezone` (IANA name; default UTC), including daylight-saving changes. `levelResources: true` additionally delays tasks so nobody works on two at once (priority rule `levelingPriority`, default least slack), reporting `levelingDelayHours` and `waitingOn` per task. Tasks with `allocation` below 1 take that share of their assignee (a 16h task at 0.5 spans 32 working hours); levelling fits them within 100% per person, and `overallocations` lists who is booked above 100% and when. Teams act as pools of `headcount` people (default: member count) shared by team-only tasks and members' own tasks. Finished tasks take no time. `calculatePortfolioCriticalPath({ projectIds })` levels several projects together, sharing people and teams across them.
 
 ### 9. Fractional Lexical Indexing (Kanban Reordering)
 

package/dist/domain/cpm.d.ts

@@ -1,9 +1,16 @@
-import type { Task, TaskDependency, CriticalPathAnalysis, WorkSchedule, User, Team } from '../types/index.js';
+import type { Task, TaskDependency, CriticalPathAnalysis, WorkSchedule, User, Team, PortfolioCriticalPathAnalysis } from '../types/index.js';
 export declare function getTaskDurationHours(task: Task): number;
 /** The task's `allocation`, clamped to (0, 1]; 1 when unset or invalid. */
 export declare function getTaskAllocation(task: Task): number;
 /** Working hours a task spans: its effort divided by its allocation. */
 export declare function getTaskElapsedHours(task: Task): number;
+/** True for completed or canceled tasks (by `semanticStatus`, else the default `done`/`canceled` statuses). */
+export declare function isTaskFinished(task: Task): boolean;
+/**
+ * Working hours critical path analysis schedules for a task: 0 when it is finished (it needs no
+ * more time and occupies nobody), otherwise its elapsed hours.
+ */
+export declare function getTaskScheduledHours(task: Task): number;
 export interface CPMOptions {
     projectStartDate?: string | Date;
     /** The project calendar. Default: `DEFAULT_WORK_SCHEDULE`. */
@@ -39,6 +46,26 @@ export declare function resolveTaskSchedule(task: Task, context: {
     teams?: Team[];
     schedule?: WorkSchedule;
 }): WorkSchedule;
+export interface PortfolioProjectInput {
+    projectId: string;
+    tasks: Task[];
+    /** The project's start. Default: today (UTC midnight). */
+    projectStartDate?: string | Date;
+    /** The project calendar. Default: `DEFAULT_WORK_SCHEDULE`. */
+    schedule?: WorkSchedule;
+}
+export interface PortfolioCPMOptions extends Omit<CPMOptions, 'projectStartDate' | 'schedule'> {
+    /** Project ids in priority order; when levelling, their tasks get people first. Unlisted projects come last. */
+    projectOrder?: string[];
+}
+/**
+ * Critical path analysis over several projects at once. Always date-based. Each task starts no
+ * earlier than its own project's start and is due by its project's end. Dependencies between tasks
+ * in different projects are honoured. With `levelResources` (requires `calendars: 'assignee'`),
+ * assignees and team pools are shared across all projects, so nobody is booked above capacity in
+ * total. Returns one analysis per project, the latest end, and the combined over-allocation report.
+ */
+export declare function calculatePortfolioCPM(projects: PortfolioProjectInput[], dependencies: TaskDependency[], options?: PortfolioCPMOptions): PortfolioCriticalPathAnalysis;
 /**
  * Calculates the Critical Path Method (CPM) schedule for a set of tasks and their dependencies.
  * - Forward Pass: computes earlyStart and earlyFinish (in working hours and calendar dates)

package/dist/domain/cpm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cpm.d.ts","sourceRoot":"","sources":["../../src/domain/cpm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,cAAc,EAEd,oBAAoB,EACpB,YAAY,EACZ,IAAI,EACJ,IAAI,EAEL,MAAM,mBAAmB,CAAC;AAW3B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYvD;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAGpD;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEtD;AAED,MAAM,WAAW,UAAU;IACzB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IACnC,iFAAiF;IACjF,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1E,4FAA4F;AAC5F,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;CAAE,GACnE,YAAY,CAOd;AAybD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,EAAE,EACb,YAAY,EAAE,cAAc,EAAE,EAC9B,OAAO,GAAE,UAAe,GACvB,oBAAoB,CA4JtB"}
+{"version":3,"file":"cpm.d.ts","sourceRoot":"","sources":["../../src/domain/cpm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EACJ,cAAc,EAEd,oBAAoB,EACpB,YAAY,EACZ,IAAI,EACJ,IAAI,EAEJ,6BAA6B,EAC9B,MAAM,mBAAmB,CAAC;AAW3B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAYvD;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAGpD;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAEtD;AAED,+GAA+G;AAC/G,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAGlD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAExD;AAED,MAAM,WAAW,UAAU;IACzB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;IACnC,iFAAiF;IACjF,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC;AAE1E,4FAA4F;AAC5F,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE;IAAE,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,YAAY,CAAA;CAAE,GACnE,YAAY,CAOd;AAmjBD,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,WAAW,mBAAoB,SAAQ,IAAI,CAAC,UAAU,EAAE,kBAAkB,GAAG,UAAU,CAAC;IAC5F,gHAAgH;IAChH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,qBAAqB,EAAE,EACjC,YAAY,EAAE,cAAc,EAAE,EAC9B,OAAO,GAAE,mBAAwB,GAChC,6BAA6B,CAqB/B;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,IAAI,EAAE,EACb,YAAY,EAAE,cAAc,EAAE,EAC9B,OAAO,GAAE,UAAe,GACvB,oBAAoB,CA4JtB"}

package/dist/domain/cpm.js

@@ -21,6 +21,19 @@ export function getTaskAllocation(task) {
 export function getTaskElapsedHours(task) {
     return getTaskDurationHours(task) / getTaskAllocation(task);
 }
+/** True for completed or canceled tasks (by `semanticStatus`, else the default `done`/`canceled` statuses). */
+export function isTaskFinished(task) {
+    if (task.semanticStatus)
+        return task.semanticStatus === 'completed' || task.semanticStatus === 'canceled';
+    return task.status === 'done' || task.status === 'canceled';
+}
+/**
+ * Working hours critical path analysis schedules for a task: 0 when it is finished (it needs no
+ * more time and occupies nobody), otherwise its elapsed hours.
+ */
+export function getTaskScheduledHours(task) {
+    return isTaskFinished(task) ? 0 : getTaskElapsedHours(task);
+}
 /** The calendar a task runs on in assignee mode: assignee, then task team, then project. */
 export function resolveTaskSchedule(task, context) {
     return ((task.assigneeId && context.users?.find((u) => u.id === task.assigneeId)?.schedule) ||
@@ -105,39 +118,80 @@ function buildGraph(tasks, dependencies) {
  * the project start. With `levelResources`, see `levelSchedule`.
  */
 function calculateCalendarCPM(projectId, calculatedAt, graph, options) {
-    const { taskMap, taskIds, prerequisites, successors, topoOrder } = graph;
-    const projectSchedule = options.schedule || DEFAULT_WORK_SCHEDULE;
+    const segment = {
+        projectId,
+        start: startOrToday(options.projectStartDate),
+        schedule: options.schedule || DEFAULT_WORK_SCHEDULE,
+        taskIds: graph.taskIds
+    };
+    const result = scheduleOnDates(graph, [segment], options, calculatedAt);
+    return result.projects[0];
+}
+function startOrToday(input) {
+    if (input)
+        return parseDate(input);
     const today = new Date();
-    const projectStart = options.projectStartDate
-        ? parseDate(options.projectStartDate)
-        : new Date(Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()));
-    const calendarOf = new Map(taskIds.map((id) => [id, resolveTaskSchedule(taskMap.get(id), options)]));
-    const durationOf = new Map(taskIds.map((id) => [id, getTaskElapsedHours(taskMap.get(id))]));
-    const ctx = { taskMap, calendarOf, durationOf, projectStart };
+    return new Date(Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()));
+}
+/**
+ * Date-based passes over one or more projects at once. Each task starts no earlier than its
+ * project's start and is due by its project's end; dependencies, assignees and team pools may span
+ * projects. Returns one analysis per project plus the combined over-allocation report.
+ */
+function scheduleOnDates(graph, segments, options, calculatedAt) {
+    const { taskMap, taskIds, prerequisites, successors, topoOrder } = graph;
+    const segmentOf = new Map(segments.flatMap((seg) => seg.taskIds.map((id) => [id, seg])));
+    const calendarOf = new Map(taskIds.map((id) => {
+        const seg = segmentOf.get(id);
+        const task = taskMap.get(id);
+        return [id, options.calendars === 'assignee' ? resolveTaskSchedule(task, { ...options, schedule: seg.schedule }) : seg.schedule];
+    }));
+    const durationOf = new Map(taskIds.map((id) => [id, getTaskScheduledHours(taskMap.get(id))]));
+    const ctx = { taskMap, calendarOf, durationOf, startOf: (id) => segmentOf.get(id).start };
+    const endOfProjects = (dates) => {
+        const ends = new Map(segments.map((seg) => [seg.projectId, latest(seg.taskIds.map((id) => dates.finish.get(id)), seg.start)]));
+        return (id) => ends.get(segmentOf.get(id).projectId);
+    };
+    const resourcesOf = resourceModel(options.teams);
     const early = forwardPass(topoOrder, prerequisites, ctx);
-    const late = backwardPass([...topoOrder].reverse(), (id) => successors.get(id), latest(early.finish, projectStart), ctx);
+    const late = backwardPass([...topoOrder].reverse(), (id) => successors.get(id), endOfProjects(early), ctx);
+    const analyse = (seg, e, l, extra) => buildAnalysis(seg, calculatedAt, e, l, ctx, extra);
     if (!options.levelResources) {
-        const analysis = buildAnalysis(projectId, calculatedAt, taskIds, early, late, projectSchedule, ctx);
-        return { ...analysis, overallocations: findOverallocations(taskMap, early) };
+        const overallocations = findOverallocations(taskMap, early, resourcesOf);
+        return {
+            projects: segments.map((seg) => ({ ...analyse(seg, early, late), overallocations: involving(overallocations, seg) })),
+            overallocations
+        };
     }
     const unleveledSlack = new Map(taskIds.map((id) => [id, slackHours(early.finish.get(id), late.finish.get(id), calendarOf.get(id))]));
-    const leveled = levelSchedule(graph, ctx, unleveledSlack, options.levelingPriority ?? 'slack');
-    const leveledLate = backwardPass(leveled.backwardOrder, (id) => [...successors.get(id), ...(leveled.resourceSuccessors.get(id) ?? [])], latest(leveled.early.finish, projectStart), ctx);
-    const analysis = buildAnalysis(projectId, calculatedAt, taskIds, leveled.early, leveledLate, projectSchedule, ctx, (id) => {
-        const delay = round2(getWorkingHoursBetween(early.start.get(id), leveled.early.start.get(id), calendarOf.get(id)));
-        const waitingOn = leveled.waitingOn.get(id);
-        return { levelingDelayHours: delay, ...(waitingOn ? { waitingOn } : {}) };
-    });
+    const projectRank = new Map((options.projectOrder ?? []).map((pid, i) => [pid, i]));
+    const rankOf = (id) => projectRank.get(segmentOf.get(id).projectId) ?? projectRank.size;
+    const leveled = levelSchedule(graph, ctx, unleveledSlack, options.levelingPriority ?? 'slack', resourcesOf, rankOf);
+    const leveledLate = backwardPass(leveled.backwardOrder, (id) => [...successors.get(id), ...(leveled.resourceSuccessors.get(id) ?? [])], endOfProjects(leveled.early), ctx);
+    const overallocations = findOverallocations(taskMap, leveled.early, resourcesOf);
+    const unleveledEnd = endOfProjects(early);
     return {
-        ...analysis,
-        leveled: true,
-        unleveledProjectEndDate: latest(early.finish, projectStart).toISOString(),
-        overallocations: findOverallocations(taskMap, leveled.early)
+        projects: segments.map((seg) => ({
+            ...analyse(seg, leveled.early, leveledLate, (id) => {
+                const delay = round2(getWorkingHoursBetween(early.start.get(id), leveled.early.start.get(id), calendarOf.get(id)));
+                const waitingOn = leveled.waitingOn.get(id);
+                return { levelingDelayHours: delay, ...(waitingOn ? { waitingOn } : {}) };
+            }),
+            leveled: true,
+            unleveledProjectEndDate: (seg.taskIds.length ? unleveledEnd(seg.taskIds[0]) : seg.start).toISOString(),
+            overallocations: involving(overallocations, seg)
+        })),
+        overallocations
     };
 }
+/** Over-allocation entries that include at least one of the project's tasks. */
+function involving(overallocations, seg) {
+    const ids = new Set(seg.taskIds);
+    return overallocations.filter((o) => o.taskIds.some((id) => ids.has(id)));
+}
 function latest(dates, floor) {
     let max = floor;
-    for (const d of dates.values())
+    for (const d of dates)
         if (d > max)
             max = d;
     return max;
@@ -152,7 +206,7 @@ function forwardPass(order, prerequisites, ctx) {
     const start = new Map();
     const finish = new Map();
     for (const id of order) {
-        let ready = ctx.projectStart;
+        let ready = ctx.startOf(id);
         for (const p of prerequisites.get(id)) {
             const f = finish.get(p);
             if (f && f > ready)
@@ -166,11 +220,11 @@ function forwardPass(order, prerequisites, ctx) {
     return { start, finish };
 }
 /** Latest dates; `order` must list every successor before its predecessors. */
-function backwardPass(order, successorsOf, projectEnd, ctx) {
+function backwardPass(order, successorsOf, endOf, ctx) {
     const start = new Map();
     const finish = new Map();
     for (const id of order) {
-        let due = projectEnd;
+        let due = endOf(id);
         for (const s of successorsOf(id)) {
             const ls = start.get(s);
             if (ls && ls < due)
@@ -187,15 +241,16 @@ const PRIORITY_RANK = { urgent: 0, high: 1, medium: 2, low: 3, none: 4 };
 /**
  * Resource levelling with a serial schedule-generation scheme: repeatedly take the eligible task
  * (all predecessors placed) that ranks first under `rule`, and place it at the earliest time its
- * predecessors are finished and its assignee has `allocation` spare for its whole span on their
- * calendar. Each assignee's bookings total at most 1 at any moment; tasks are not split.
- * Unassigned tasks and zero-duration milestones do not occupy anyone.
+ * predecessors are finished and every resource it uses (see `resourceModel`) has `allocation`
+ * spare for its whole span on the task's calendar. Tasks are not split. Tasks without resources
+ * and zero-duration milestones do not occupy anything.
  *
  * Returns the levelled early dates, which task each delayed task waited for, and resource links
- * (`resourceSuccessors`): for every two tasks of one assignee that cannot overlap (allocations
- * sum above 1), the earlier one precedes the later one, so the backward pass keeps them apart.
+ * (`resourceSuccessors`) so the backward pass keeps the levelling: for every two tasks on one
+ * resource whose allocations exceed its capacity the earlier precedes the later, and each delayed
+ * task follows the task whose finish freed its capacity.
  */
-function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder }, ctx, unleveledSlack, rule) {
+function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder }, ctx, unleveledSlack, rule, resourcesOf, projectRankOf = () => 0) {
     const creation = new Map([...taskIds]
         .sort((a, b) => (taskMap.get(a).createdAt ?? '').localeCompare(taskMap.get(b).createdAt ?? '') || a.localeCompare(b))
         .map((id, i) => [id, i]));
@@ -210,18 +265,27 @@ function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder
         dueDate: (id) => [due(id), unleveledSlack.get(id), creation.get(id)],
         order: (id) => [creation.get(id)]
     };
-    const compare = (a, b) => {
-        const ka = keys[rule](a);
-        const kb = keys[rule](b);
+    // Keys never change, so compute them once; picking the next task is then a linear scan.
+    const keyOf = new Map(taskIds.map((id) => [id, [projectRankOf(id), ...keys[rule](id)]]));
+    const before = (a, b) => {
+        const [ka, kb] = [keyOf.get(a), keyOf.get(b)];
         for (let i = 0; i < ka.length; i++)
             if (ka[i] !== kb[i])
-                return ka[i] - kb[i];
-        return 0;
+                return ka[i] < kb[i];
+        return false;
+    };
+    const first = (ids) => {
+        let best;
+        for (const id of ids)
+            if (best === undefined || before(id, best))
+                best = id;
+        return best;
     };
     const start = new Map();
     const finish = new Map();
     const waitingOn = new Map();
     const busy = new Map();
+    const capacityOf = new Map();
     const placed = [];
     const remaining = new Map(taskIds.map((id) => [id, prerequisites.get(id).size]));
     const eligible = new Set(taskIds.filter((id) => remaining.get(id) === 0));
@@ -229,9 +293,9 @@ function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder
         // A dependency cycle leaves tasks that never become eligible; take them in topological order.
         if (eligible.size === 0)
             eligible.add(topoOrder.find((id) => !start.has(id)));
-        const id = [...eligible].sort(compare)[0];
+        const id = first(eligible);
         eligible.delete(id);
-        let ready = ctx.projectStart;
+        let ready = ctx.startOf(id);
         for (const p of prerequisites.get(id)) {
             const f = finish.get(p);
             if (f && f > ready)
@@ -239,13 +303,17 @@ function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder
         }
         const calendar = ctx.calendarOf.get(id);
         const duration = ctx.durationOf.get(id);
-        const assignee = taskMap.get(id).assigneeId;
-        const slots = assignee && duration > 0 ? busy.get(assignee) ?? [] : [];
+        const resources = duration > 0 ? resourcesOf(taskMap.get(id)) : [];
         const allocation = getTaskAllocation(taskMap.get(id));
         let es = nextWorkingTime(ready, calendar);
         let ef = addWorkingHours(es, duration, calendar);
         for (;;) {
-            const release = firstCapacityRelease(slots, es.getTime(), ef.getTime(), allocation);
+            let release;
+            for (const resource of resources) {
+                release = firstCapacityRelease(busy.get(resource.key) ?? [], es.getTime(), ef.getTime(), allocation, resource.capacity);
+                if (release)
+                    break;
+            }
             if (!release)
                 break;
             waitingOn.set(id, release.taskId);
@@ -254,8 +322,9 @@ function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder
         }
         start.set(id, es);
         finish.set(id, ef);
-        if (assignee && duration > 0) {
-            busy.set(assignee, [...slots, { start: es.getTime(), end: ef.getTime(), allocation, taskId: id }]);
+        for (const resource of resources) {
+            busy.set(resource.key, [...(busy.get(resource.key) ?? []), { start: es.getTime(), end: ef.getTime(), allocation, taskId: id }]);
+            capacityOf.set(resource.key, resource.capacity);
         }
         placed.push(id);
         for (const s of successors.get(id)) {
@@ -266,29 +335,42 @@ function levelSchedule({ taskMap, taskIds, prerequisites, successors, topoOrder
         }
     }
     const resourceSuccessors = new Map();
-    for (const slots of busy.values()) {
+    const link = (from, to) => {
+        if (from !== to)
+            resourceSuccessors.set(from, (resourceSuccessors.get(from) ?? new Set()).add(to));
+    };
+    for (const [key, slots] of busy) {
+        const capacity = capacityOf.get(key);
         const ordered = [...slots].sort((a, b) => a.start - b.start);
         for (let i = 0; i < ordered.length; i++) {
             for (let j = i + 1; j < ordered.length; j++) {
                 const [u, v] = [ordered[i], ordered[j]];
-                if (u.end <= v.start && u.allocation + v.allocation > 1 + EPSILON) {
-                    resourceSuccessors.set(u.taskId, [...(resourceSuccessors.get(u.taskId) ?? []), v.taskId]);
-                }
+                if (u.end <= v.start && u.allocation + v.allocation > capacity + EPSILON)
+                    link(u.taskId, v.taskId);
             }
         }
     }
+    // In pools a delayed task may not conflict pairwise with anything; it still follows the task
+    // whose finish freed its capacity.
+    for (const [taskId, blocker] of waitingOn)
+        link(blocker, taskId);
     // Every edge (dependency or resource chain) goes forward in levelled start time; ties are
     // zero-duration tasks, ordered by placement.
     const placement = new Map(placed.map((id, i) => [id, i]));
     const backwardOrder = [...taskIds].sort((a, b) => start.get(b).getTime() - start.get(a).getTime() || placement.get(b) - placement.get(a));
-    return { early: { start, finish }, waitingOn, resourceSuccessors, backwardOrder };
+    return {
+        early: { start, finish },
+        waitingOn,
+        resourceSuccessors: new Map([...resourceSuccessors].map(([k, v]) => [k, [...v]])),
+        backwardOrder
+    };
 }
 const EPSILON = 1e-9;
 /**
- * If `allocation` does not fit alongside `bookings` somewhere in [start, end), returns the booking
+ * If `allocation` does not fit alongside `bookings` within `capacity` somewhere in [start, end), returns the booking
  * whose end frees enough capacity soonest after the first overloaded moment; otherwise undefined.
  */
-function firstCapacityRelease(bookings, start, end, allocation) {
+function firstCapacityRelease(bookings, start, end, allocation, capacity) {
     const overlapping = bookings.filter((b) => b.start < end && b.end > start);
     if (overlapping.length === 0)
         return undefined;
@@ -297,51 +379,81 @@ function firstCapacityRelease(bookings, start, end, allocation) {
     for (const t of points) {
         const active = overlapping.filter((b) => b.start <= t && b.end > t);
         const used = active.reduce((sum, b) => sum + b.allocation, 0);
-        if (used + allocation <= 1 + EPSILON)
+        if (used + allocation <= capacity + EPSILON)
             continue;
         // Release bookings in end order until the task fits.
         let freed = used;
         for (const b of [...active].sort((x, y) => x.end - y.end)) {
             freed -= b.allocation;
-            if (freed + allocation <= 1 + EPSILON)
+            if (freed + allocation <= capacity + EPSILON)
                 return b;
         }
     }
     return undefined;
 }
-/** Periods in which an assignee's overlapping tasks need more than 100% of them. */
-function findOverallocations(taskMap, dates) {
-    const byAssignee = new Map();
+/**
+ * Which resources each task uses. An assigned task uses its assignee and every team pool the
+ * assignee belongs to (their own work takes up team capacity); a task with only `teamId` uses that
+ * team's pool. A pool's capacity is `team.headcount`, else its member count; pools with no capacity
+ * are ignored, so their tasks stay unconstrained.
+ */
+function resourceModel(teams = []) {
+    const pools = teams
+        .map((team) => ({ team, capacity: team.headcount ?? team.memberIds.length }))
+        .filter((pool) => pool.capacity > 0);
+    const poolResource = ({ team, capacity }) => ({ key: `team:${team.id}`, capacity, teamId: team.id });
+    return (task) => {
+        if (task.assigneeId) {
+            return [
+                { key: `user:${task.assigneeId}`, capacity: 1, assigneeId: task.assigneeId },
+                ...pools.filter((pool) => pool.team.memberIds.includes(task.assigneeId)).map(poolResource)
+            ];
+        }
+        const pool = task.teamId ? pools.find((p) => p.team.id === task.teamId) : undefined;
+        return pool ? [poolResource(pool)] : [];
+    };
+}
+/** Periods in which an assignee or team pool is booked above its capacity. */
+function findOverallocations(taskMap, dates, resourcesOf) {
+    const byResource = new Map();
     for (const [id, task] of taskMap) {
         const s = dates.start.get(id).getTime();
         const e = dates.finish.get(id).getTime();
-        if (!task.assigneeId || e <= s)
+        if (e <= s)
             continue;
-        byAssignee.set(task.assigneeId, [...(byAssignee.get(task.assigneeId) ?? []), { start: s, end: e, allocation: getTaskAllocation(task), taskId: id }]);
+        for (const resource of resourcesOf(task)) {
+            const entry = byResource.get(resource.key) ?? { resource, bookings: [] };
+            entry.bookings.push({ start: s, end: e, allocation: getTaskAllocation(task), taskId: id });
+            byResource.set(resource.key, entry);
+        }
     }
     const result = [];
-    for (const [assigneeId, bookings] of byAssignee) {
+    for (const { resource, bookings } of byResource.values()) {
+        const owner = resource.assigneeId ? { assigneeId: resource.assigneeId } : { teamId: resource.teamId };
         const points = [...new Set(bookings.flatMap((b) => [b.start, b.end]))].sort((a, b) => a - b);
+        let previous;
         for (let i = 0; i + 1 < points.length; i++) {
             const [from, to] = [points[i], points[i + 1]];
             const active = bookings.filter((b) => b.start <= from && b.end >= to);
             const allocation = round2(active.reduce((sum, b) => sum + b.allocation, 0));
-            if (allocation <= 1 + EPSILON)
+            if (allocation <= resource.capacity + EPSILON) {
+                previous = undefined;
                 continue;
+            }
             const taskIds = active.map((b) => b.taskId).sort();
-            const previous = result.at(-1);
-            if (previous && previous.assigneeId === assigneeId && previous.end === new Date(from).toISOString() && previous.taskIds.join() === taskIds.join()) {
+            if (previous && previous.end === new Date(from).toISOString() && previous.taskIds.join() === taskIds.join()) {
                 previous.end = new Date(to).toISOString();
             }
             else {
-                result.push({ assigneeId, start: new Date(from).toISOString(), end: new Date(to).toISOString(), allocation, taskIds });
+                previous = { ...owner, start: new Date(from).toISOString(), end: new Date(to).toISOString(), allocation, capacity: resource.capacity, taskIds };
+                result.push(previous);
             }
         }
     }
     return result;
 }
-function buildAnalysis(projectId, calculatedAt, taskIds, early, late, projectSchedule, ctx, extra = () => ({})) {
-    const { projectStart, calendarOf, durationOf, taskMap } = ctx;
+function buildAnalysis({ projectId, start: projectStart, schedule: projectSchedule, taskIds }, calculatedAt, early, late, ctx, extra = () => ({})) {
+    const { calendarOf, durationOf, taskMap } = ctx;
     const offset = (date) => date >= projectStart
         ? getWorkingHoursBetween(projectStart, date, projectSchedule)
         : -getWorkingHoursBetween(date, projectStart, projectSchedule);
@@ -374,7 +486,7 @@ function buildAnalysis(projectId, calculatedAt, taskIds, early, late, projectSch
             ...extra(id)
         });
     }
-    const projectEnd = latest(early.finish, projectStart);
+    const projectEnd = latest(taskIds.map((id) => early.finish.get(id)), projectStart);
     const totalHours = round2(offset(projectEnd));
     return {
         projectId,
@@ -387,6 +499,35 @@ function buildAnalysis(projectId, calculatedAt, taskIds, early, late, projectSch
         tasks: schedules
     };
 }
+/**
+ * Critical path analysis over several projects at once. Always date-based. Each task starts no
+ * earlier than its own project's start and is due by its project's end. Dependencies between tasks
+ * in different projects are honoured. With `levelResources` (requires `calendars: 'assignee'`),
+ * assignees and team pools are shared across all projects, so nobody is booked above capacity in
+ * total. Returns one analysis per project, the latest end, and the combined over-allocation report.
+ */
+export function calculatePortfolioCPM(projects, dependencies, options = {}) {
+    if (options.levelResources && options.calendars !== 'assignee') {
+        throw new Error("levelResources requires calendars: 'assignee'.");
+    }
+    const calculatedAt = new Date().toISOString();
+    const graph = buildGraph(projects.flatMap((p) => p.tasks), dependencies);
+    const segments = projects.map((p) => ({
+        projectId: p.projectId,
+        start: startOrToday(p.projectStartDate),
+        schedule: p.schedule || DEFAULT_WORK_SCHEDULE,
+        taskIds: p.tasks.map((t) => t.id)
+    }));
+    const result = scheduleOnDates(graph, segments, options, calculatedAt);
+    const ends = result.projects.map((a) => a.projectEndDate).filter(Boolean).sort();
+    return {
+        calculatedAt,
+        projects: result.projects,
+        ...(ends.length ? { projectEndDate: ends[ends.length - 1] } : {}),
+        ...(options.levelResources ? { leveled: true } : {}),
+        overallocations: result.overallocations
+    };
+}
 /**
  * Calculates the Critical Path Method (CPM) schedule for a set of tasks and their dependencies.
  * - Forward Pass: computes earlyStart and earlyFinish (in working hours and calendar dates)
@@ -422,7 +563,7 @@ export function calculateCPM(projectId, tasks, dependencies, options = {}) {
     const earlyFinish = new Map();
     for (const id of topoOrder) {
         const task = taskMap.get(id);
-        const duration = getTaskElapsedHours(task);
+        const duration = getTaskScheduledHours(task);
         const prereqs = prerequisites.get(id) || new Set();
         let maxPrereqFinish = 0;
         for (const p of prereqs) {
@@ -450,7 +591,7 @@ export function calculateCPM(projectId, tasks, dependencies, options = {}) {
     for (let i = topoOrder.length - 1; i >= 0; i--) {
         const id = topoOrder[i];
         const task = taskMap.get(id);
-        const duration = getTaskElapsedHours(task);
+        const duration = getTaskScheduledHours(task);
         const succs = successors.get(id) || new Set();
         let minSuccLateStart = totalDurationHours;
         if (succs.size > 0) {
@@ -485,7 +626,7 @@ export function calculateCPM(projectId, tasks, dependencies, options = {}) {
             criticalTaskIds.push(id);
         }
         const task = taskMap.get(id);
-        const duration = getTaskElapsedHours(task);
+        const duration = getTaskScheduledHours(task);
         const earlyStartDate = projectStartDate
             ? addWorkingHours(projectStartDate, es, schedule).toISOString()
             : undefined;