@blxzer/pactile 0.6.0-beta.2 → 0.6.0-beta.5

package/dist/pactile/scheduler/scheduler.d.ts

@@ -0,0 +1,91 @@
+export type SchedulerTaskStateV1 = "waiting" | "running" | "completed" | "failed" | "blocked";
+export interface SchedulerCostVectorV1 {
+    latencyMs: number;
+    waitingMs: number;
+    executionMs: number;
+    integrationMs: number;
+    reworkMs: number;
+    reviewMs: number;
+}
+export interface SchedulerTaskV1 {
+    taskId: string;
+    dependsOn: readonly string[];
+    state: SchedulerTaskStateV1;
+    /** null means the task's write scope is unknown and conflicts with every writer. */
+    writeSet: readonly string[] | null;
+    estimatedCosts: SchedulerCostVectorV1;
+    observedCosts?: Partial<SchedulerCostVectorV1>;
+}
+export interface ConflictParallelAuthorizationV1 {
+    taskIds: readonly [string, string];
+    approvedBy: string;
+    authorizationRef: string;
+    /** Person or role accountable for integrating explicitly parallelized writers. */
+    integrationOwner: string;
+    integrationPlan: string;
+}
+export interface JevSchedulerAdviceV1 {
+    /** Earlier entries are preferred only when critical-path costs tie. */
+    taskOrder: readonly string[];
+    evidenceRef: string;
+}
+export interface TaskScheduleRequestV1 {
+    schemaVersion: 1;
+    tasks: readonly SchedulerTaskV1[];
+    conflictParallelizations?: readonly ConflictParallelAuthorizationV1[];
+    jevAdvice?: JevSchedulerAdviceV1;
+}
+export type SchedulerErrorCodeV1 = "invalid-request" | "duplicate-task" | "missing-dependency" | "dependency-cycle" | "invalid-cost" | "invalid-write-set" | "invalid-conflict-authorization";
+export declare class TaskScheduleError extends Error {
+    readonly code: SchedulerErrorCodeV1;
+    constructor(code: SchedulerErrorCodeV1, message: string);
+}
+export type SchedulerTaskActionV1 = "scheduled" | "completed" | "in-flight" | "failed" | "blocked" | "deferred";
+export interface SchedulerTaskDecisionV1 {
+    taskId: string;
+    action: SchedulerTaskActionV1;
+    reasonCodes: string[];
+    criticalPathMs: number;
+    estimatedCostMs: number;
+    estimatedCosts: SchedulerCostVectorV1;
+    /** All fields are returned so a receipt can be stored without losing absent measurements. */
+    observedCosts: Record<keyof SchedulerCostVectorV1, number | null>;
+    jevHintRank: number | null;
+    jevHintApplied: boolean;
+    wave: number | null;
+}
+export interface TaskScheduleWaveV1 {
+    sequence: number;
+    taskIds: string[];
+    candidateTaskIds: string[];
+    startedAfterMs: number;
+    estimatedDurationMs: number;
+    estimatedCompletionMs: number;
+    serialEquivalentMs: number;
+    estimatedSavingsMs: number;
+    candidateSerialEquivalentMs: number;
+    candidateParallelDurationMs: number;
+    candidateEstimatedSavingsMs: number;
+    decision: "single-ready-task" | "parallel-time-saved" | "parallelism-rejected-no-time-saved";
+    conflictAuthorizations: ConflictParallelAuthorizationV1[];
+}
+export interface TaskScheduleReceiptV1 {
+    schemaVersion: 1;
+    decisions: SchedulerTaskDecisionV1[];
+    waves: TaskScheduleWaveV1[];
+    serialEstimatedCompletionMs: number;
+    plannedEstimatedCompletionMs: number;
+    estimatedCompletionSavingsMs: number;
+    jevAdvice: null | {
+        evidenceRef: string;
+        hintedTaskIds: string[];
+        tieBreakAppliedTaskIds: string[];
+        ignoredTaskIds: string[];
+    };
+}
+/**
+ * Produces a deterministic schedule receipt from a Task DAG snapshot. It never
+ * starts, approves, integrates, or reviews a Run; callers own those side effects.
+ */
+export declare function planTaskScheduleV1(input: TaskScheduleRequestV1): TaskScheduleReceiptV1;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/pactile/scheduler/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../../src/pactile/scheduler/scheduler.ts"],"names":[],"mappings":"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"}

package/dist/pactile/scheduler/scheduler.js

@@ -0,0 +1,589 @@
+export class TaskScheduleError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "TaskScheduleError";
+        this.code = code;
+    }
+}
+const COST_FIELDS = [
+    "latencyMs",
+    "waitingMs",
+    "executionMs",
+    "integrationMs",
+    "reworkMs",
+    "reviewMs",
+];
+const TASK_STATES = new Set([
+    "waiting",
+    "running",
+    "completed",
+    "failed",
+    "blocked",
+]);
+function fail(code, message) {
+    throw new TaskScheduleError(code, message);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyText(value, field, code) {
+    if (typeof value !== "string" || !value.trim() || value !== value.trim()) {
+        fail(code, `${field} must be a non-empty trimmed string`);
+    }
+    return value;
+}
+function compareText(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function safeAdd(left, right, label) {
+    const sum = left + right;
+    if (!Number.isFinite(sum))
+        fail("invalid-cost", `${label} exceeds the finite millisecond range`);
+    return sum;
+}
+function parseCosts(value, field, partial) {
+    if (!isRecord(value))
+        fail("invalid-cost", `${field} must be an object`);
+    const allowed = new Set(COST_FIELDS);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            fail("invalid-cost", `${field} contains unknown cost field: ${key}`);
+    }
+    const result = {};
+    let total = 0;
+    for (const key of COST_FIELDS) {
+        const raw = value[key];
+        if (raw === undefined && partial) {
+            result[key] = null;
+            continue;
+        }
+        if (typeof raw !== "number" || !Number.isFinite(raw) || raw < 0) {
+            fail("invalid-cost", `${field}.${key} must be a finite non-negative number`);
+        }
+        result[key] = raw;
+        total = safeAdd(total, raw, field);
+    }
+    if (!partial) {
+        for (const key of COST_FIELDS) {
+            if (result[key] === null)
+                fail("invalid-cost", `${field}.${key} is required`);
+        }
+    }
+    return result;
+}
+function normalizeWritePath(value, taskId) {
+    if (typeof value !== "string" || !value.trim()) {
+        fail("invalid-write-set", `writeSet for ${taskId} must contain non-empty paths`);
+    }
+    const original = value.trim();
+    const slashed = original
+        .replaceAll("\\", "/")
+        .replace(/^\.\//, "")
+        .replace(/\/$/, "");
+    const segments = slashed.split("/");
+    const hasWindowsAlternateDataStream = process.platform === "win32" &&
+        segments.some((segment) => segment.includes(":"));
+    if (!slashed ||
+        slashed === "." ||
+        slashed.startsWith("/") ||
+        /^[A-Za-z]:/.test(slashed) ||
+        hasWindowsAlternateDataStream ||
+        slashed.includes("*") ||
+        slashed.includes("?") ||
+        slashed.includes("[") ||
+        slashed.includes("]") ||
+        segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        fail("invalid-write-set", `writeSet must use concrete project-relative paths: ${value}`);
+    }
+    return slashed.normalize("NFC").toLowerCase();
+}
+function pathSetsConflict(left, right) {
+    if (!left.length || !right.length)
+        return false;
+    if (left.includes("*") || right.includes("*"))
+        return true;
+    return left.some((a) => right.some((b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`)));
+}
+function pairKey(left, right) {
+    const [first, second] = compareText(left, right) <= 0 ? [left, right] : [right, left];
+    return JSON.stringify([first, second]);
+}
+function validateRequest(input) {
+    if (!isRecord(input) ||
+        input.schemaVersion !== 1 ||
+        !Array.isArray(input.tasks)) {
+        fail("invalid-request", "scheduler request requires schemaVersion 1 and a tasks array");
+    }
+    const tasks = new Map();
+    for (const candidate of input.tasks) {
+        if (!isRecord(candidate))
+            fail("invalid-request", "each scheduler task must be an object");
+        const taskId = nonEmptyText(candidate.taskId, "taskId", "invalid-request");
+        if (taskId.includes("\0"))
+            fail("invalid-request", `taskId contains a null byte: ${taskId}`);
+        if (tasks.has(taskId))
+            fail("duplicate-task", `duplicate taskId: ${taskId}`);
+        if (!TASK_STATES.has(candidate.state)) {
+            fail("invalid-request", `invalid state for ${taskId}`);
+        }
+        if (!Array.isArray(candidate.dependsOn)) {
+            fail("invalid-request", `dependsOn for ${taskId} must be an array`);
+        }
+        const dependsOn = candidate.dependsOn.map((dependency) => nonEmptyText(dependency, `dependsOn entry for ${taskId}`, "invalid-request"));
+        if (new Set(dependsOn).size !== dependsOn.length) {
+            fail("invalid-request", `dependsOn for ${taskId} contains duplicates`);
+        }
+        if (dependsOn.includes(taskId))
+            fail("dependency-cycle", `task depends on itself: ${taskId}`);
+        if (candidate.writeSet !== null && !Array.isArray(candidate.writeSet)) {
+            fail("invalid-write-set", `writeSet for ${taskId} must be an array or null`);
+        }
+        const writeSet = candidate.writeSet === null
+            ? ["*"]
+            : candidate.writeSet.length
+                ? [
+                    ...new Set(candidate.writeSet.map((entry) => normalizeWritePath(entry, taskId))),
+                ].sort(compareText)
+                : [];
+        const estimatedCosts = parseCosts(candidate.estimatedCosts, `estimatedCosts for ${taskId}`, false);
+        const observedCosts = parseCosts(candidate.observedCosts === undefined ? {} : candidate.observedCosts, `observedCosts for ${taskId}`, true);
+        const estimatedCostMs = COST_FIELDS.reduce((sum, key) => safeAdd(sum, estimatedCosts[key], `estimatedCosts for ${taskId}`), 0);
+        const parallelPhaseMs = [
+            estimatedCosts.latencyMs,
+            estimatedCosts.waitingMs,
+            estimatedCosts.executionMs,
+            estimatedCosts.reworkMs,
+        ].reduce((sum, value) => safeAdd(sum, value, `parallel phase for ${taskId}`), 0);
+        const integrationReviewMs = safeAdd(estimatedCosts.integrationMs, estimatedCosts.reviewMs, `integration and review costs for ${taskId}`);
+        tasks.set(taskId, {
+            taskId,
+            dependsOn,
+            state: candidate.state,
+            writeSet,
+            estimatedCosts,
+            observedCosts,
+            estimatedCostMs,
+            parallelPhaseMs,
+            integrationReviewMs,
+        });
+    }
+    const taskIds = [...tasks.keys()].sort(compareText);
+    for (const task of tasks.values()) {
+        for (const dependency of task.dependsOn) {
+            if (!tasks.has(dependency)) {
+                fail("missing-dependency", `task ${task.taskId} references missing dependency ${dependency}`);
+            }
+        }
+    }
+    const dependents = new Map(taskIds.map((taskId) => [taskId, []]));
+    const remainingDependencies = new Map();
+    for (const task of tasks.values()) {
+        remainingDependencies.set(task.taskId, task.dependsOn.length);
+        for (const dependency of task.dependsOn)
+            dependents.get(dependency)?.push(task.taskId);
+    }
+    for (const children of dependents.values())
+        children.sort(compareText);
+    const ready = taskIds.filter((taskId) => remainingDependencies.get(taskId) === 0);
+    const topologicalOrder = [];
+    while (ready.length) {
+        ready.sort(compareText);
+        const taskId = ready.shift();
+        if (!taskId)
+            break;
+        topologicalOrder.push(taskId);
+        for (const dependent of dependents.get(taskId) ?? []) {
+            const left = (remainingDependencies.get(dependent) ?? 0) - 1;
+            remainingDependencies.set(dependent, left);
+            if (left === 0)
+                ready.push(dependent);
+        }
+    }
+    if (topologicalOrder.length !== tasks.size) {
+        const cycleMembers = taskIds.filter((taskId) => (remainingDependencies.get(taskId) ?? 0) > 0);
+        fail("dependency-cycle", `dependency cycle detected among: ${cycleMembers.join(", ")}`);
+    }
+    const authorizations = new Map();
+    if (input.conflictParallelizations === null) {
+        fail("invalid-conflict-authorization", "conflictParallelizations must be an array");
+    }
+    const rawAuthorizations = input.conflictParallelizations ?? [];
+    if (!Array.isArray(rawAuthorizations)) {
+        fail("invalid-conflict-authorization", "conflictParallelizations must be an array");
+    }
+    for (const candidate of rawAuthorizations) {
+        if (!isRecord(candidate) ||
+            !Array.isArray(candidate.taskIds) ||
+            candidate.taskIds.length !== 2) {
+            fail("invalid-conflict-authorization", "each conflict authorization requires exactly two task IDs");
+        }
+        const left = nonEmptyText(candidate.taskIds[0], "authorized task ID", "invalid-conflict-authorization");
+        const right = nonEmptyText(candidate.taskIds[1], "authorized task ID", "invalid-conflict-authorization");
+        if (left === right || !tasks.has(left) || !tasks.has(right)) {
+            fail("invalid-conflict-authorization", `conflict authorization must reference two distinct known tasks: ${left}, ${right}`);
+        }
+        const approvedBy = nonEmptyText(candidate.approvedBy, "approvedBy", "invalid-conflict-authorization");
+        const authorizationRef = nonEmptyText(candidate.authorizationRef, "authorizationRef", "invalid-conflict-authorization");
+        const integrationOwner = nonEmptyText(candidate.integrationOwner, "integrationOwner", "invalid-conflict-authorization");
+        const integrationPlan = nonEmptyText(candidate.integrationPlan, "integrationPlan", "invalid-conflict-authorization");
+        const key = pairKey(left, right);
+        if (authorizations.has(key)) {
+            fail("invalid-conflict-authorization", `duplicate conflict authorization for ${left} and ${right}`);
+        }
+        if (!pathSetsConflict(tasks.get(left)?.writeSet ?? [], tasks.get(right)?.writeSet ?? [])) {
+            fail("invalid-conflict-authorization", `authorization does not match an overlapping write set: ${left}, ${right}`);
+        }
+        const [first, second] = compareText(left, right) <= 0 ? [left, right] : [right, left];
+        authorizations.set(key, {
+            taskIds: [first, second],
+            approvedBy,
+            authorizationRef,
+            integrationOwner,
+            integrationPlan,
+        });
+    }
+    const hints = new Map();
+    let advice;
+    if (input.jevAdvice !== undefined) {
+        if (!isRecord(input.jevAdvice) ||
+            !Array.isArray(input.jevAdvice.taskOrder)) {
+            fail("invalid-request", "jevAdvice requires taskOrder and evidenceRef");
+        }
+        const evidenceRef = nonEmptyText(input.jevAdvice.evidenceRef, "jevAdvice.evidenceRef", "invalid-request");
+        const advisedIds = input.jevAdvice.taskOrder.map((taskId) => nonEmptyText(taskId, "Jev advised task ID", "invalid-request"));
+        if (new Set(advisedIds).size !== advisedIds.length) {
+            fail("invalid-request", "jevAdvice.taskOrder contains duplicates");
+        }
+        for (const taskId of advisedIds) {
+            if (!tasks.has(taskId))
+                fail("invalid-request", `jevAdvice references unknown task: ${taskId}`);
+        }
+        advisedIds.forEach((taskId, rank) => hints.set(taskId, rank));
+        advice = { taskOrder: advisedIds, evidenceRef };
+    }
+    return { tasks, taskIds, topologicalOrder, authorizations, hints, advice };
+}
+function hasWriteConflict(left, right) {
+    return pathSetsConflict(left.writeSet, right.writeSet);
+}
+function approvedConflict(left, right, authorizations) {
+    return authorizations.get(pairKey(left, right));
+}
+function computeBlockedBy(tasks, topologicalOrder) {
+    const blockedBy = new Map();
+    for (const taskId of topologicalOrder) {
+        const task = tasks.get(taskId);
+        if (!task)
+            continue;
+        if (task.state === "blocked" || task.state === "failed") {
+            blockedBy.set(taskId, [taskId]);
+            continue;
+        }
+        const blockers = new Set();
+        for (const dependency of task.dependsOn) {
+            for (const blocker of blockedBy.get(dependency) ?? [])
+                blockers.add(blocker);
+        }
+        if (blockers.size)
+            blockedBy.set(taskId, [...blockers].sort(compareText));
+    }
+    return blockedBy;
+}
+function computeCriticalPaths(tasks, taskIds, topologicalOrder, blockedBy) {
+    const dependents = new Map(taskIds.map((taskId) => [taskId, []]));
+    for (const task of tasks.values()) {
+        for (const dependency of task.dependsOn)
+            dependents.get(dependency)?.push(task.taskId);
+    }
+    const criticalPath = new Map();
+    for (const taskId of [...topologicalOrder].reverse()) {
+        const task = tasks.get(taskId);
+        if (!task)
+            continue;
+        const downstream = (dependents.get(taskId) ?? []).reduce((maximum, dependent) => Math.max(maximum, criticalPath.get(dependent) ?? 0), 0);
+        const activeCost = blockedBy.has(taskId) || task.state === "completed"
+            ? 0
+            : task.estimatedCostMs;
+        criticalPath.set(taskId, safeAdd(activeCost, downstream, `critical path for ${taskId}`));
+    }
+    return criticalPath;
+}
+function priorityOrder(taskIds, criticalPath, hints, tieBreakApplied) {
+    const groups = new Map();
+    for (const taskId of taskIds) {
+        const pathCost = criticalPath.get(taskId) ?? 0;
+        const group = groups.get(pathCost) ?? [];
+        group.push(taskId);
+        groups.set(pathCost, group);
+    }
+    const result = [];
+    const costs = [...groups.keys()].sort((left, right) => right - left);
+    for (const cost of costs) {
+        const group = groups.get(cost) ?? [];
+        const lexical = [...group].sort(compareText);
+        const advised = [...group].sort((left, right) => {
+            const leftRank = hints.get(left) ?? Number.POSITIVE_INFINITY;
+            const rightRank = hints.get(right) ?? Number.POSITIVE_INFINITY;
+            return leftRank - rightRank || compareText(left, right);
+        });
+        if (advised.some((taskId, index) => taskId !== lexical[index] && hints.has(taskId))) {
+            for (const taskId of advised) {
+                if (hints.has(taskId))
+                    tieBreakApplied.add(taskId);
+            }
+        }
+        result.push(...advised);
+    }
+    return result;
+}
+function taskTotal(task) {
+    return task.estimatedCostMs;
+}
+function groupSerialCost(group) {
+    return group.reduce((sum, task) => safeAdd(sum, taskTotal(task), "serial wave cost"), 0);
+}
+function groupParallelCost(group) {
+    const parallelWork = group.reduce((maximum, task) => Math.max(maximum, task.parallelPhaseMs), 0);
+    const serialIntegrationAndReview = group.reduce((sum, task) => safeAdd(sum, task.integrationReviewMs, "integration and review wave cost"), 0);
+    return safeAdd(parallelWork, serialIntegrationAndReview, "parallel wave cost");
+}
+function normalizeObservedCosts(costs) {
+    return Object.fromEntries(COST_FIELDS.map((key) => [key, costs[key]]));
+}
+/**
+ * Produces a deterministic schedule receipt from a Task DAG snapshot. It never
+ * starts, approves, integrates, or reviews a Run; callers own those side effects.
+ */
+export function planTaskScheduleV1(input) {
+    const { tasks, taskIds, topologicalOrder, authorizations, hints, advice } = validateRequest(input);
+    const blockedBy = computeBlockedBy(tasks, topologicalOrder);
+    const criticalPath = computeCriticalPaths(tasks, taskIds, topologicalOrder, blockedBy);
+    const pending = new Set(taskIds.filter((taskId) => tasks.get(taskId)?.state === "waiting" && !blockedBy.has(taskId)));
+    const running = taskIds
+        .map((taskId) => tasks.get(taskId))
+        .filter((task) => task?.state === "running");
+    const simulatedCompleted = new Set(taskIds.filter((taskId) => tasks.get(taskId)?.state === "completed"));
+    const tieBreakApplied = new Set();
+    const waveByTask = new Map();
+    const schedulingReasons = new Map();
+    const addSchedulingReason = (taskId, reason) => {
+        const reasons = schedulingReasons.get(taskId) ?? new Set();
+        reasons.add(reason);
+        schedulingReasons.set(taskId, reasons);
+    };
+    const waves = [];
+    let elapsedMs = 0;
+    while (pending.size) {
+        const dependencyReady = [...pending].filter((taskId) => tasks
+            .get(taskId)
+            ?.dependsOn.every((dependency) => simulatedCompleted.has(dependency)));
+        if (!dependencyReady.length)
+            break;
+        const executable = [];
+        for (const taskId of dependencyReady) {
+            const task = tasks.get(taskId);
+            if (!task)
+                continue;
+            const blockedByRunning = running.some((active) => {
+                if (!hasWriteConflict(task, active))
+                    return false;
+                return !approvedConflict(taskId, active.taskId, authorizations);
+            });
+            if (!blockedByRunning)
+                executable.push(taskId);
+            else
+                addSchedulingReason(taskId, "active-write-set-conflict");
+        }
+        if (!executable.length)
+            break;
+        const ordered = priorityOrder(executable, criticalPath, hints, tieBreakApplied);
+        const groups = [];
+        for (const taskId of ordered) {
+            const compatibleGroup = groups.find((group) => group.every((memberId) => {
+                const left = tasks.get(taskId);
+                const right = tasks.get(memberId);
+                if (!left || !right || !hasWriteConflict(left, right))
+                    return true;
+                return !!approvedConflict(taskId, memberId, authorizations);
+            }));
+            if (compatibleGroup)
+                compatibleGroup.push(taskId);
+            else
+                groups.push([taskId]);
+        }
+        const group = groups[0] ?? [];
+        const priorityGroup = group
+            .map((taskId) => tasks.get(taskId))
+            .filter((task) => !!task);
+        if (!priorityGroup.length)
+            break;
+        const serialEquivalentMs = groupSerialCost(priorityGroup);
+        const candidateParallelMs = group.length > 1 ? groupParallelCost(priorityGroup) : serialEquivalentMs;
+        const candidateSavingsMs = serialEquivalentMs - candidateParallelMs;
+        const parallelize = group.length > 1 && candidateSavingsMs > 0;
+        const selectedIds = parallelize ? group : [ordered[0]];
+        const selectedTasks = selectedIds
+            .map((taskId) => tasks.get(taskId))
+            .filter((task) => !!task);
+        const selectedSerialMs = groupSerialCost(selectedTasks);
+        const estimatedDurationMs = parallelize
+            ? candidateParallelMs
+            : (selectedTasks[0]?.estimatedCostMs ?? 0);
+        const selectedSavingsMs = Math.max(0, selectedSerialMs - estimatedDurationMs);
+        const selectedSet = new Set(selectedIds);
+        for (const taskId of executable) {
+            if (selectedSet.has(taskId))
+                continue;
+            const conflictsWithSelected = selectedIds.some((selectedId) => {
+                const candidate = tasks.get(taskId);
+                const selected = tasks.get(selectedId);
+                return (!!candidate &&
+                    !!selected &&
+                    hasWriteConflict(candidate, selected) &&
+                    !approvedConflict(taskId, selectedId, authorizations));
+            });
+            if (conflictsWithSelected)
+                addSchedulingReason(taskId, "write-set-conflict-serialized");
+            else if (group.includes(taskId) && group.length > 1 && !parallelize) {
+                addSchedulingReason(taskId, "parallelism-rejected-no-time-savings");
+            }
+            else
+                addSchedulingReason(taskId, "later-ready-wave");
+        }
+        const selectedAuthorizations = [...authorizations.values()]
+            .filter((authorization) => {
+            const [left, right] = authorization.taskIds;
+            return ((selectedSet.has(left) && selectedSet.has(right)) ||
+                (selectedSet.has(left) &&
+                    running.some((active) => active.taskId === right)) ||
+                (selectedSet.has(right) &&
+                    running.some((active) => active.taskId === left)));
+        })
+            .sort((left, right) => compareText(pairKey(...left.taskIds), pairKey(...right.taskIds)));
+        const sequence = waves.length + 1;
+        const startedAfterMs = elapsedMs;
+        elapsedMs = safeAdd(elapsedMs, estimatedDurationMs, "planned completion time");
+        waves.push({
+            sequence,
+            taskIds: [...selectedIds],
+            candidateTaskIds: [...group],
+            startedAfterMs,
+            estimatedDurationMs,
+            estimatedCompletionMs: elapsedMs,
+            serialEquivalentMs: selectedSerialMs,
+            estimatedSavingsMs: selectedSavingsMs,
+            candidateSerialEquivalentMs: serialEquivalentMs,
+            candidateParallelDurationMs: candidateParallelMs,
+            candidateEstimatedSavingsMs: candidateSavingsMs,
+            decision: parallelize
+                ? "parallel-time-saved"
+                : group.length > 1
+                    ? "parallelism-rejected-no-time-saved"
+                    : "single-ready-task",
+            conflictAuthorizations: selectedAuthorizations,
+        });
+        for (const taskId of selectedIds) {
+            pending.delete(taskId);
+            simulatedCompleted.add(taskId);
+            waveByTask.set(taskId, sequence);
+        }
+    }
+    const decisions = taskIds.map((taskId) => {
+        const task = tasks.get(taskId);
+        if (!task)
+            throw new Error("validated task disappeared");
+        const wave = waveByTask.get(taskId) ?? null;
+        let action;
+        let reasonCodes;
+        if (wave !== null) {
+            action = "scheduled";
+            reasonCodes = [
+                ...(schedulingReasons.get(taskId) ?? []),
+                ...(waves[wave - 1]?.decision === "parallel-time-saved"
+                    ? ["ready-dependencies", "positive-completion-time-savings"]
+                    : ["ready-dependencies", "serial-wave"]),
+            ];
+        }
+        else if (task.state === "completed") {
+            action = "completed";
+            reasonCodes = ["already-completed"];
+        }
+        else if (task.state === "running") {
+            action = "in-flight";
+            reasonCodes = ["already-running"];
+        }
+        else if (task.state === "failed") {
+            action = "failed";
+            reasonCodes = ["task-failed"];
+        }
+        else if (task.state === "blocked") {
+            action = "blocked";
+            reasonCodes = ["task-blocked"];
+        }
+        else if (blockedBy.has(taskId)) {
+            action = "blocked";
+            reasonCodes = ["blocked-by-dependency"];
+        }
+        else {
+            action = "deferred";
+            const unresolvedDependencies = task.dependsOn.filter((dependency) => !simulatedCompleted.has(dependency));
+            if (unresolvedDependencies.length) {
+                reasonCodes = ["dependency-not-complete"];
+            }
+            else if (running.some((active) => hasWriteConflict(task, active) &&
+                !approvedConflict(taskId, active.taskId, authorizations))) {
+                reasonCodes = [
+                    ...new Set([
+                        "active-write-set-conflict",
+                        ...(schedulingReasons.get(taskId) ?? []),
+                    ]),
+                ];
+            }
+            else {
+                reasonCodes = ["deferred-after-current-plan"];
+            }
+        }
+        const appliedTieBreak = tieBreakApplied.has(taskId);
+        return {
+            taskId,
+            action,
+            reasonCodes,
+            criticalPathMs: criticalPath.get(taskId) ?? 0,
+            estimatedCostMs: task.estimatedCostMs,
+            estimatedCosts: { ...task.estimatedCosts },
+            observedCosts: normalizeObservedCosts(task.observedCosts),
+            jevHintRank: hints.get(taskId) ?? null,
+            jevHintApplied: appliedTieBreak,
+            wave,
+        };
+    });
+    const serialEstimatedCompletionMs = decisions
+        .filter((decision) => decision.action === "scheduled")
+        .reduce((sum, decision) => safeAdd(sum, decision.estimatedCostMs, "serial completion time"), 0);
+    const estimatedCompletionSavingsMs = Math.max(0, serialEstimatedCompletionMs - elapsedMs);
+    const hintedTaskIds = advice?.taskOrder ? [...advice.taskOrder] : [];
+    const ignoredTaskIds = hintedTaskIds
+        .filter((taskId) => !waveByTask.has(taskId))
+        .sort((left, right) => (hints.get(left) ?? 0) - (hints.get(right) ?? 0) ||
+        compareText(left, right));
+    return {
+        schemaVersion: 1,
+        decisions,
+        waves,
+        serialEstimatedCompletionMs,
+        plannedEstimatedCompletionMs: elapsedMs,
+        estimatedCompletionSavingsMs,
+        jevAdvice: advice
+            ? {
+                evidenceRef: advice.evidenceRef,
+                hintedTaskIds,
+                tieBreakAppliedTaskIds: [...tieBreakApplied]
+                    .filter((taskId) => waveByTask.has(taskId))
+                    .sort(compareText),
+                ignoredTaskIds,
+            }
+            : null,
+    };
+}
+//# sourceMappingURL=scheduler.js.map