makersclaw 0.7.0 → 0.8.1

package/registry/blocks/schedule-engine/engine.js

@@ -0,0 +1,769 @@
+// Schedule engine: the rules every date in a plan follows.
+//
+// Pure functions over plain rows: no React, no lib/, no I/O. The browser
+// runs them on every pointer move of a drag (the live preview), the server
+// runs them again on fresh rows before it writes, and the block's tests
+// (test/schedule-engine.test.mjs) run them under node. A database function
+// and an agent's reference can state the same rules. README.md beside this
+// file lists them.
+//
+// Rows in:
+//   task  { id, parent_id, start_date, due_date, is_milestone, progress, status }
+//   link  { id, task_id, depends_on_id, kind, lag_days }  (task_id waits on depends_on_id)
+// Dates are 'YYYY-MM-DD' text: calendar days, never instants.
+//
+// The model, in working days (Monday to Friday by default):
+//   * A task occupies [s, s + d): it starts at the beginning of working day s
+//     and runs d working days (d >= 1). Its due date is working day s + d - 1.
+//   * A milestone takes no time. It sits at the end of its day, so s is the
+//     index after that day and d = 0. A finish-to-start successor of a task
+//     that ends on Friday starts Monday; a milestone after it shows Friday.
+//   * A task's own planned start is a floor ("not before"): the forward pass
+//     never moves a task earlier than its planned start, only later.
+//   * Finished work (status done, or 100%) is pinned where it happened.
+//   * A task with sub-tasks is a summary: its dates are its leaves' span. A
+//     link to a summary binds every leaf under it; a link from a summary
+//     reads the summary's span.
+//   * Cancelled tasks are off the plan; so are tasks with no dates.
+
+const DAY_MS = 86400000;
+
+const pad = (n) => String(n).padStart(2, "0");
+
+/** 'YYYY-MM-DD' (or a longer ISO string) → whole UTC day number, or null. */
+export function dayOf(iso) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(String(iso ?? ""));
+  return m ? Math.round(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3])) / DAY_MS) : null;
+}
+
+/** Whole UTC day number → 'YYYY-MM-DD'. */
+export function isoOf(day) {
+  const d = new Date(day * DAY_MS);
+  return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+}
+
+/** Monday 0 … Sunday 6 (1970-01-01 was a Thursday). */
+export const weekdayOf = (day) => (((day + 3) % 7) + 7) % 7;
+
+/**
+ * A working calendar over day numbers.
+ *   startIndex(day)  the working day on or after `day`, as an index
+ *   lastIndex(day)   the working day on or before `day`, as an index
+ *   dayAt(index)     back to a day number
+ * "weekdays" (the default) works Monday to Friday; "everyday" works all
+ * seven days.
+ */
+export function makeCalendar(kind = "weekdays") {
+  if (kind && typeof kind === "object") return kind;
+  if (kind === "everyday") {
+    return { kind: "everyday", isWorkday: () => true, startIndex: (d) => d, lastIndex: (d) => d, dayAt: (i) => i };
+  }
+  const index = (day) => Math.floor((day + 3) / 7) * 5 + weekdayOf(day);
+  return {
+    kind: "weekdays",
+    isWorkday: (day) => weekdayOf(day) < 5,
+    startIndex: (day) => {
+      const w = weekdayOf(day);
+      return index(w >= 5 ? day + 7 - w : day);
+    },
+    lastIndex: (day) => {
+      const w = weekdayOf(day);
+      return index(w >= 5 ? day - (w - 4) : day);
+    },
+    dayAt: (i) => {
+      const weeks = Math.floor(i / 5);
+      return weeks * 7 + (i - weeks * 5) - 3;
+    },
+  };
+}
+
+const KINDS = {
+  finish_to_start: "FS",
+  start_to_start: "SS",
+  finish_to_finish: "FF",
+  start_to_finish: "SF",
+  fs: "FS",
+  ss: "SS",
+  ff: "FF",
+  sf: "SF",
+};
+/** The link kinds as the database writes them. */
+export const LINK_KINDS = { FS: "finish_to_start", SS: "start_to_start", FF: "finish_to_finish", SF: "start_to_finish" };
+
+/** finish_to_start | start_to_start | … (or FS/SS/FF/SF) → "FS" | "SS" | "FF" | "SF". */
+export function linkKind(kind) {
+  return KINDS[String(kind ?? "").toLowerCase()] ?? "FS";
+}
+
+/** A task's stored dates as a span in working days: { dated, s, d, milestone }. */
+export function spanOf(task, calendar = "weekdays") {
+  const cal = makeCalendar(calendar);
+  const milestone = Boolean(task?.is_milestone);
+  const a = dayOf(task?.start_date);
+  const b = dayOf(task?.due_date);
+  if (a == null && b == null) return { dated: false, s: 0, d: 0, milestone };
+  if (milestone) return { dated: true, s: cal.lastIndex(b ?? a) + 1, d: 0, milestone };
+  const start = a ?? b;
+  const due = Math.max(start, b ?? a);
+  const s = cal.startIndex(start);
+  return { dated: true, s, d: Math.max(1, cal.lastIndex(due) + 1 - s), milestone };
+}
+
+/** A span back to dates: { start, due } ('YYYY-MM-DD'). A milestone shows its day. */
+export function datesOf(s, d, milestone, calendar = "weekdays") {
+  const cal = makeCalendar(calendar);
+  if (milestone) {
+    const day = isoOf(cal.dayAt(s - 1));
+    return { start: day, due: day };
+  }
+  return { start: isoOf(cal.dayAt(s)), due: isoOf(cal.dayAt(s + Math.max(1, d) - 1)) };
+}
+
+/** Working days from `from` to `to`: 0 when the same working day, negative when `to` is earlier. */
+export function workdaysBetween(from, to, calendar = "weekdays") {
+  const cal = makeCalendar(calendar);
+  const a = dayOf(from);
+  const b = dayOf(to);
+  if (a == null || b == null) return null;
+  return cal.lastIndex(b) - cal.lastIndex(a);
+}
+
+/** The date `n` working days after `iso` (n may be negative). A weekend `iso` counts from the Friday before. */
+export function addWorkdays(iso, n, calendar = "weekdays") {
+  const cal = makeCalendar(calendar);
+  const day = dayOf(iso);
+  if (day == null) return null;
+  return isoOf(cal.dayAt(cal.lastIndex(day) + n));
+}
+
+/** Working days a task runs, from its dates (milestones 0). */
+export function durationOf(start, due, milestone = false, calendar = "weekdays") {
+  const span = spanOf({ start_date: start, due_date: due, is_milestone: milestone }, calendar);
+  return span.dated ? span.d : null;
+}
+
+/* ------------------------------------------------------------------ */
+/* The network                                                          */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Build the scheduling network: nodes for tasks (leaf, summary or undated),
+ * dependency edges expanded to the successor's leaves, and a topological
+ * order over both the edges and the summary roll-ups. Tasks stuck in (or
+ * behind) a loop are left out of the order and listed in `stuck`.
+ */
+export function buildNetwork(tasks, links, { calendar = "weekdays" } = {}) {
+  const cal = makeCalendar(calendar);
+  const nodes = new Map();
+  const list = [];
+  for (const t of tasks ?? []) {
+    if (!t || t.id == null) continue;
+    const status = String(t.status ?? "");
+    if (status === "cancelled") continue;
+    const id = String(t.id);
+    if (nodes.has(id)) continue;
+    const span = spanOf(t, cal);
+    const node = {
+      id,
+      task: t,
+      parentId: t.parent_id == null ? null : String(t.parent_id),
+      children: [],
+      milestone: span.milestone,
+      pinned: status === "done" || Number(t.progress ?? 0) >= 100,
+      datedSelf: span.dated,
+      s: span.s,
+      d: span.d,
+      kind: null,
+      es: null,
+      ef: null,
+      ls: null,
+      lf: null,
+      slack: null,
+      stuck: false,
+      in: [],
+      out: [],
+      lfLimit: Infinity,
+      lsLimit: Infinity,
+      leaves: null,
+    };
+    nodes.set(id, node);
+    list.push(node);
+  }
+
+  // Parents: one outside the set (another project, cancelled) makes a
+  // root, and a parent chain that loops is cut where it closes.
+  for (const n of list) if (n.parentId && (!nodes.has(n.parentId) || n.parentId === n.id)) n.parentId = null;
+  for (const n of list) {
+    const seen = new Set([n.id]);
+    let cur = n;
+    while (cur.parentId) {
+      if (seen.has(cur.parentId)) {
+        cur.parentId = null;
+        break;
+      }
+      seen.add(cur.parentId);
+      cur = nodes.get(cur.parentId);
+    }
+  }
+  for (const n of list) if (n.parentId) nodes.get(n.parentId).children.push(n);
+
+  // Kinds, bottom up: a task with a dated leaf below it is a summary.
+  const kindOf = (n) => {
+    if (n.kind) return n.kind;
+    let dated = false;
+    for (const c of n.children) {
+      const k = kindOf(c);
+      if (k === "leaf" || k === "summary") dated = true;
+    }
+    n.kind = dated ? "summary" : n.datedSelf ? "leaf" : "undated";
+    return n.kind;
+  };
+  for (const n of list) kindOf(n);
+  const leavesOf = (n) => {
+    if (n.leaves) return n.leaves;
+    n.leaves = n.kind === "leaf" ? [n] : n.kind === "summary" ? n.children.flatMap(leavesOf) : [];
+    return n.leaves;
+  };
+  for (const n of list) leavesOf(n);
+  const isAncestor = (a, b) => {
+    for (let p = b.parentId ? nodes.get(b.parentId) : null; p; p = p.parentId ? nodes.get(p.parentId) : null) if (p === a) return true;
+    return false;
+  };
+
+  // Stored spans of summaries (for the conflict check on stored dates).
+  for (const n of list) {
+    if (n.kind !== "summary") continue;
+    let s = Infinity;
+    let f = -Infinity;
+    for (const l of n.leaves) {
+      s = Math.min(s, l.s);
+      f = Math.max(f, l.s + l.d);
+    }
+    n.s = s;
+    n.d = f - s;
+  }
+
+  // Dependency edges.
+  const linkInfo = new Map();
+  const edges = [];
+  for (const l of links ?? []) {
+    if (!l) continue;
+    const id = String(l.id ?? `${l.task_id}>${l.depends_on_id}`);
+    const kind = linkKind(l.kind);
+    const lag = Math.trunc(Number(l.lag_days ?? 0)) || 0;
+    const info = { id, taskId: String(l.task_id), dependsOnId: String(l.depends_on_id), kind, lag, valid: false, reason: null, edges: [] };
+    linkInfo.set(id, info);
+    const succ = nodes.get(info.taskId);
+    const pred = nodes.get(info.dependsOnId);
+    if (!succ || !pred) info.reason = "missing";
+    else if (succ === pred) info.reason = "self";
+    else if (succ.kind === "undated" || pred.kind === "undated") info.reason = "undated";
+    else if (isAncestor(succ, pred) || isAncestor(pred, succ)) info.reason = "family";
+    else {
+      info.valid = true;
+      for (const leaf of succ.leaves) {
+        const e = { link: info, from: pred, to: leaf, kind, lag };
+        edges.push(e);
+        info.edges.push(e);
+        pred.out.push(e);
+        leaf.in.push(e);
+      }
+    }
+  }
+
+  // Topological order over dependency edges and roll-ups (child → summary).
+  const active = list.filter((n) => n.kind === "leaf" || n.kind === "summary");
+  const indeg = new Map(active.map((n) => [n, 0]));
+  const next = new Map(active.map((n) => [n, []]));
+  const edge = (a, b) => {
+    next.get(a).push(b);
+    indeg.set(b, indeg.get(b) + 1);
+  };
+  for (const e of edges) edge(e.from, e.to);
+  for (const n of active) if (n.parentId) edge(n, nodes.get(n.parentId));
+  const order = active.filter((n) => indeg.get(n) === 0);
+  for (let i = 0; i < order.length; i += 1) {
+    for (const m of next.get(order[i])) {
+      indeg.set(m, indeg.get(m) - 1);
+      if (indeg.get(m) === 0) order.push(m);
+    }
+  }
+  const stuck = active.filter((n) => indeg.get(n) > 0);
+  for (const n of stuck) n.stuck = true;
+
+  return { calendar: cal, nodes, list, order, stuck, edges, links: linkInfo, isAncestor, finish: null, start: null };
+}
+
+/** The earliest start a dependency edge allows its successor leaf. */
+function required(e, pred = e.from) {
+  const d = e.to.d;
+  switch (e.kind) {
+    case "SS":
+      return pred.es + e.lag;
+    case "FF":
+      return pred.ef + e.lag - d;
+    case "SF":
+      return pred.es + e.lag - d;
+    default:
+      return pred.ef + e.lag;
+  }
+}
+
+/** The same, on stored dates (the conflict check). */
+function requiredStored(e) {
+  return required(e, { es: e.from.s, ef: e.from.s + e.from.d });
+}
+
+/**
+ * Forward pass: each leaf starts at the later of its own planned start and
+ * what every link into it allows (pinned work stays put); each summary
+ * spans its children. Sets es/ef (working-day indexes) on every node, and
+ * net.start / net.finish.
+ */
+export function forwardPass(net) {
+  const rollup = (n) => {
+    let es = Infinity;
+    let ef = -Infinity;
+    for (const c of n.children) {
+      if (c.es == null) continue;
+      es = Math.min(es, c.es);
+      ef = Math.max(ef, c.ef);
+    }
+    n.es = es;
+    n.ef = ef;
+  };
+  for (const n of net.order) {
+    if (n.kind === "summary") {
+      rollup(n);
+      continue;
+    }
+    let es = n.s;
+    if (!n.pinned) for (const e of n.in) es = Math.max(es, required(e));
+    n.es = es;
+    n.ef = es + n.d;
+  }
+  // Stuck in a loop: keep the stored dates; summaries roll up deepest first.
+  const depth = (n) => {
+    let k = 0;
+    for (let p = n.parentId; p; p = net.nodes.get(p).parentId) k += 1;
+    return k;
+  };
+  for (const n of net.stuck) {
+    if (n.kind === "leaf") {
+      n.es = n.s;
+      n.ef = n.s + n.d;
+    }
+  }
+  for (const n of [...net.stuck].filter((k) => k.kind === "summary").sort((a, b) => depth(b) - depth(a))) rollup(n);
+
+  let start = Infinity;
+  let finish = -Infinity;
+  for (const n of net.list) {
+    if (n.kind !== "leaf") continue;
+    start = Math.min(start, n.es);
+    finish = Math.max(finish, n.ef);
+  }
+  net.start = Number.isFinite(start) ? start : null;
+  net.finish = Number.isFinite(finish) ? finish : null;
+  return net;
+}
+
+/**
+ * Backward pass: the latest each leaf may finish without moving the
+ * project's finish (or breaking a link to work that is itself as late as
+ * it may be). Total slack = latest finish − earliest finish, in working
+ * days. A link to a summary binds its leaves; a link from a summary binds
+ * every leaf for a finish (FS, FF) and the leaves that set its start for a
+ * start (SS, SF).
+ */
+export function backwardPass(net) {
+  if (net.finish == null) return net;
+  for (const n of net.list) {
+    n.lfLimit = Infinity;
+    n.lsLimit = Infinity;
+    n.ls = null;
+    n.lf = null;
+    n.slack = null;
+  }
+  for (let i = net.order.length - 1; i >= 0; i -= 1) {
+    const n = net.order[i];
+    if (n.kind !== "leaf") continue;
+    let lf = Math.min(net.finish, n.lfLimit, n.lsLimit + n.d);
+    for (let a = n.parentId ? net.nodes.get(n.parentId) : null; a; a = a.parentId ? net.nodes.get(a.parentId) : null) {
+      lf = Math.min(lf, a.lfLimit);
+      if (n.es === a.es) lf = Math.min(lf, a.lsLimit + n.d);
+    }
+    n.lf = lf;
+    n.ls = lf - n.d;
+    n.slack = n.lf - n.ef;
+    for (const e of n.in) {
+      const p = e.from;
+      if (e.kind === "SS") p.lsLimit = Math.min(p.lsLimit, n.ls - e.lag);
+      else if (e.kind === "FF") p.lfLimit = Math.min(p.lfLimit, n.lf - e.lag);
+      else if (e.kind === "SF") p.lsLimit = Math.min(p.lsLimit, n.lf - e.lag);
+      else p.lfLimit = Math.min(p.lfLimit, n.ls - e.lag);
+    }
+  }
+  // Summaries: the least slack of their leaves.
+  for (const n of net.list) {
+    if (n.kind !== "summary") continue;
+    let slack = null;
+    for (const l of n.leaves) if (l.slack != null) slack = slack == null ? l.slack : Math.min(slack, l.slack);
+    n.slack = slack;
+  }
+  return net;
+}
+
+/** The critical path: leaves with no slack, in plan order (start, then finish). */
+export function criticalPath(net) {
+  return net.list
+    .filter((n) => n.kind === "leaf" && n.slack != null && n.slack <= 0)
+    .sort((a, b) => a.es - b.es || a.ef - b.ef || net.list.indexOf(a) - net.list.indexOf(b))
+    .map((n) => n.id);
+}
+
+/* ------------------------------------------------------------------ */
+/* The plan: everything the screen draws                                */
+/* ------------------------------------------------------------------ */
+
+const iso10 = (v) => (v == null ? null : String(v).slice(0, 10));
+
+/**
+ * Forward pass, backward pass and critical path over one project's tasks
+ * and links, described in dates.
+ *
+ * → {
+ *   rows: Map(id → { id, parentId, summary, milestone, pinned, dated, stuck,
+ *                    start, due            stored dates (a summary: its leaves' span)
+ *                    planStart, planDue    where the forward pass puts it
+ *                    lateStart, lateDue    the latest it may run (leaves)
+ *                    duration              working days
+ *                    slack, critical, progress, shifted, drivers, leafIds }),
+ *   links: Map(id → { id, taskId, dependsOnId, kind, lag, valid, reason,
+ *                     slack, critical, violated, violation }),
+ *   start, finish,     the plan's first and last working day
+ *   critical,          critical leaf ids in plan order
+ *   stuck, violations, link ids whose stored dates break them
+ * }
+ */
+export function schedule(tasks, links, opts = {}) {
+  const net = buildNetwork(tasks, links, opts);
+  forwardPass(net);
+  backwardPass(net);
+  return describe(net);
+}
+
+function describe(net) {
+  const cal = net.calendar;
+  const rows = new Map();
+  const criticalIds = criticalPath(net);
+  const critical = new Set(criticalIds);
+
+  for (const n of net.list) {
+    const t = n.task;
+    const base = {
+      id: n.id,
+      parentId: n.parentId,
+      summary: n.kind === "summary",
+      milestone: n.milestone,
+      pinned: n.pinned,
+      dated: n.kind !== "undated",
+      stuck: n.stuck,
+      progress: Math.max(0, Math.min(100, Number(t.progress ?? 0) || 0)),
+      start: null,
+      due: null,
+      planStart: null,
+      planDue: null,
+      lateStart: null,
+      lateDue: null,
+      duration: null,
+      slack: n.slack,
+      critical: false,
+      shifted: false,
+      drivers: [],
+      leafIds: n.leaves.map((l) => l.id),
+    };
+    if (n.kind === "leaf") {
+      const a = iso10(t.start_date);
+      const b = iso10(t.due_date);
+      const stored = datesOf(n.s, n.d, n.milestone, cal);
+      const plan = datesOf(n.es, n.d, n.milestone, cal);
+      base.start = n.milestone ? b ?? a : a ?? b;
+      base.due = n.milestone ? b ?? a : b ?? a;
+      base.planStart = plan.start;
+      base.planDue = plan.due;
+      if (n.ls != null) {
+        const late = datesOf(n.ls, n.d, n.milestone, cal);
+        base.lateStart = late.start;
+        base.lateDue = late.due;
+      }
+      base.duration = n.d;
+      base.critical = critical.has(n.id);
+      base.shifted = plan.start !== stored.start || plan.due !== stored.due;
+      const drivers = new Set();
+      if (!n.pinned) for (const e of n.in) if (required(e) === n.es && n.es > n.s) drivers.add(e.link.id);
+      base.drivers = [...drivers];
+    }
+    rows.set(n.id, base);
+  }
+
+  // Summaries: the span of their leaves, stored and planned; progress
+  // weighted by working days.
+  for (const n of net.list) {
+    if (n.kind !== "summary") continue;
+    const row = rows.get(n.id);
+    let work = 0;
+    let done = 0;
+    for (const l of n.leaves) {
+      const r = rows.get(l.id);
+      if (!row.start || r.start < row.start) row.start = r.start;
+      if (!row.due || r.due > row.due) row.due = r.due;
+      if (!row.planStart || r.planStart < row.planStart) row.planStart = r.planStart;
+      if (!row.planDue || r.planDue > row.planDue) row.planDue = r.planDue;
+      if (r.critical) row.critical = true;
+      if (r.shifted) row.shifted = true;
+      work += l.d;
+      done += (l.d * r.progress) / 100;
+    }
+    row.duration = Math.max(0, cal.lastIndex(dayOf(row.due)) + 1 - cal.startIndex(dayOf(row.start)));
+    row.progress = work > 0 ? Math.round((done / work) * 100) : n.leaves.every((l) => l.pinned) ? 100 : 0;
+  }
+
+  // Links: tightness on the plan, and conflicts on the stored dates.
+  const outLinks = new Map();
+  const violations = [];
+  for (const info of net.links.values()) {
+    const out = { id: info.id, taskId: info.taskId, dependsOnId: info.dependsOnId, kind: info.kind, lag: info.lag, valid: info.valid, reason: info.reason, slack: null, critical: false, violated: false, violation: 0 };
+    if (info.valid && !info.edges.some((e) => e.to.stuck || e.from.stuck)) {
+      let slack = Infinity;
+      let tightCritical = false;
+      let worst = 0;
+      for (const e of info.edges) {
+        const gap = e.to.es - required(e);
+        slack = Math.min(slack, gap);
+        if (gap <= 0 && critical.has(e.to.id)) tightCritical = true;
+        if (!e.to.pinned) worst = Math.max(worst, requiredStored(e) - e.to.s);
+      }
+      out.slack = slack;
+      const predCritical = info.edges[0].from.kind === "summary" ? info.edges[0].from.leaves.some((l) => critical.has(l.id)) : critical.has(info.dependsOnId);
+      out.critical = tightCritical && predCritical;
+      if (worst > 0) {
+        out.violated = true;
+        out.violation = worst;
+        violations.push(info.id);
+      }
+    }
+    outLinks.set(info.id, out);
+  }
+
+  let start = null;
+  let finish = null;
+  for (const r of rows.values()) {
+    if (!r.dated || r.summary) continue;
+    if (!start || r.planStart < start) start = r.planStart;
+    if (!finish || r.planDue > finish) finish = r.planDue;
+  }
+
+  return {
+    calendar: cal.kind,
+    rows,
+    links: outLinks,
+    start,
+    finish,
+    critical: criticalIds,
+    stuck: net.stuck.filter((n) => n.kind === "leaf").map((n) => n.id),
+    violations,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Moving work                                                          */
+/* ------------------------------------------------------------------ */
+
+const sameDates = (task, start, due) => iso10(task?.start_date) === start && iso10(task?.due_date) === due;
+
+/**
+ * Move tasks and shift everything that depends on them.
+ *
+ * `moves` is [{ id, start, due }]: a task's new dates (a summary's `start`
+ * moves its whole block of unfinished leaves by the same working days).
+ * Each moved task keeps its new start as its floor; the forward pass then
+ * pushes every task a link binds, as far as it must and no further.
+ *
+ * → { changes: [{ id, start_date, due_date, from: { start_date, due_date }, summary? }],
+ *     clamped: [{ id, asked, got, drivers }]   a move the links pushed later
+ *     before, after (plans), finishBefore, finishAfter }
+ *
+ * Only tasks the move affects are in `changes`: a task whose plan did not
+ * change keeps its stored dates, even if they were already off.
+ *
+ * `opts.nextLinks`: the links after the change, when the change is a link
+ * (a new link pushes its successor the same way a move does).
+ * `opts.nextTasks`: the tasks after a change of outline (a task put under
+ * another: the new parent's links now bind it). Their dates are the same.
+ */
+export function shiftDependents(tasks, links, moves, opts = {}) {
+  const cal = makeCalendar(opts.calendar ?? "weekdays");
+  const before = schedule(tasks, links, { ...opts, calendar: cal });
+  const byId = new Map((tasks ?? []).filter(Boolean).map((t) => [String(t.id), t]));
+  const patched = new Map();
+  const asked = new Map();
+
+  const put = (id, start, due) => {
+    const t = patched.get(id) ?? byId.get(id);
+    const milestone = Boolean(t.is_milestone);
+    patched.set(id, { ...t, start_date: milestone ? due ?? start : start, due_date: milestone ? due ?? start : due });
+    asked.set(id, milestone ? due ?? start : start);
+  };
+
+  for (const m of moves ?? []) {
+    const id = String(m?.id ?? "");
+    const row = before.rows.get(id);
+    if (!row || !byId.has(id)) continue;
+    if (row.summary) {
+      const target = dayOf(m.start);
+      if (target == null || !row.start) continue;
+      const delta = cal.startIndex(target) - cal.startIndex(dayOf(row.start));
+      if (!delta) continue;
+      for (const leafId of row.leafIds) {
+        const leaf = before.rows.get(leafId);
+        if (!leaf || leaf.pinned) continue;
+        const span = spanOf(patched.get(leafId) ?? byId.get(leafId), cal);
+        const moved = datesOf(span.s + delta, span.d, span.milestone, cal);
+        put(leafId, moved.start, moved.due);
+      }
+    } else {
+      const t = byId.get(id);
+      const start = iso10(m.start) ?? iso10(t.start_date) ?? iso10(m.due);
+      const due = iso10(m.due) ?? iso10(t.due_date) ?? start;
+      put(id, start, due);
+    }
+  }
+
+  const base = opts.nextTasks ?? tasks ?? [];
+  const movedTasks = base.map((t) => (t && patched.has(String(t.id)) ? { ...t, ...patched.get(String(t.id)), parent_id: t.parent_id } : t));
+  const after = schedule(movedTasks, opts.nextLinks ?? links, { ...opts, calendar: cal });
+
+  const changes = [];
+  const changedLeaves = new Set();
+  for (const [id, a] of after.rows) {
+    if (!a.dated || a.summary) continue;
+    const b = before.rows.get(id);
+    const touched = patched.has(id) || !b || a.planStart !== b.planStart || a.planDue !== b.planDue;
+    if (!touched) continue;
+    const t = byId.get(id);
+    if (sameDates(t, a.planStart, a.planDue)) continue;
+    changes.push({ id, start_date: a.planStart, due_date: a.planDue, from: { start_date: iso10(t.start_date), due_date: iso10(t.due_date) } });
+    changedLeaves.add(id);
+  }
+  for (const [id, a] of after.rows) {
+    if (!a.summary || !a.leafIds.some((l) => changedLeaves.has(l))) continue;
+    const t = byId.get(id);
+    if (sameDates(t, a.planStart, a.planDue)) continue;
+    changes.push({ id, start_date: a.planStart, due_date: a.planDue, from: { start_date: iso10(t.start_date), due_date: iso10(t.due_date) }, summary: true });
+  }
+
+  const clamped = [];
+  for (const [id, wanted] of asked) {
+    const a = after.rows.get(id);
+    if (!a) continue;
+    const want = datesOf(spanOf(patched.get(id), cal).s, 1, a.milestone, cal).start;
+    if (a.planStart > want) clamped.push({ id, asked: wanted, got: a.planStart, drivers: a.drivers });
+  }
+
+  return { changes, clamped, before, after, finishBefore: before.finish, finishAfter: after.finish };
+}
+
+/**
+ * Re-plan unfinished work off the past, the way the morning check does:
+ *   * not started (0%) and its start has passed → it starts today
+ *   * started, and its due date has passed → it keeps its start and needs
+ *     its remaining share of the work from today: ceil(duration × (100 −
+ *     progress) / 100) working days, at least 1
+ *   * a milestone whose day has passed, not done → today
+ * Then every dependent shifts. `today` is 'YYYY-MM-DD'; on a weekend
+ * "today" is the next Monday. Dates compared are the plan's.
+ *
+ * → shiftDependents' result, plus `moves` [{ id, start, due, reason }]
+ *   (reason: not_started | overdue | milestone).
+ */
+export function replanFromToday(tasks, links, today, opts = {}) {
+  const cal = makeCalendar(opts.calendar ?? "weekdays");
+  const t0 = dayOf(today);
+  const plan = schedule(tasks, links, { ...opts, calendar: cal });
+  const moves = [];
+  if (t0 != null) {
+    const ti = cal.startIndex(t0);
+    const todayIso = isoOf(cal.dayAt(ti));
+    for (const r of plan.rows.values()) {
+      if (!r.dated || r.summary || r.pinned || r.stuck) continue;
+      if (r.milestone) {
+        if (dayOf(r.planDue) < t0) moves.push({ id: r.id, start: todayIso, due: todayIso, reason: "milestone" });
+        continue;
+      }
+      if (r.progress === 0 && dayOf(r.planStart) < t0) {
+        moves.push({ id: r.id, start: todayIso, due: isoOf(cal.dayAt(ti + r.duration - 1)), reason: "not_started" });
+      } else if (r.progress > 0 && dayOf(r.planDue) < t0) {
+        const remaining = Math.max(1, Math.ceil((r.duration * (100 - r.progress)) / 100));
+        moves.push({ id: r.id, start: r.planStart, due: isoOf(cal.dayAt(ti + remaining - 1)), reason: "overdue" });
+      }
+    }
+  }
+  return { ...shiftDependents(tasks, links, moves, { ...opts, calendar: cal }), moves };
+}
+
+/**
+ * Mend broken links: every unfinished task that starts earlier than its
+ * links allow moves to its earliest date, and whatever waits on it follows.
+ * → shiftDependents' result, plus `moves`.
+ */
+export function alignConflicts(tasks, links, opts = {}) {
+  const plan = schedule(tasks, links, opts);
+  const moves = [];
+  for (const r of plan.rows.values()) if (r.dated && !r.summary && !r.pinned && !r.stuck && r.shifted) moves.push({ id: r.id, start: r.planStart, due: r.planDue });
+  return { ...shiftDependents(tasks, links, moves, opts), moves };
+}
+
+/**
+ * Why `taskId` can't wait on `dependsOnId`, in words, or null when it can.
+ * Refuses: itself, its own summary or sub-task, a pair already linked
+ * (either way round), and any link that would close a loop.
+ */
+export function linkProblem(tasks, links, taskId, dependsOnId, opts = {}) {
+  const a = String(taskId ?? "");
+  const b = String(dependsOnId ?? "");
+  if (!a || !b) return "Pick two tasks.";
+  if (a === b) return "A task can't wait on itself.";
+  const net = buildNetwork(tasks, links, opts);
+  const succ = net.nodes.get(a);
+  const pred = net.nodes.get(b);
+  if (!succ || !pred) return "Both tasks must be in this project.";
+  if (net.isAncestor(succ, pred) || net.isAncestor(pred, succ)) return "A task can't wait on its own summary or sub-task.";
+  if ((links ?? []).some((l) => l && ((String(l.task_id) === a && String(l.depends_on_id) === b) || (String(l.task_id) === b && String(l.depends_on_id) === a))))
+    return "These two are already linked.";
+  if (succ.kind === "undated" || pred.kind === "undated") return "Give both tasks dates first.";
+  const trial = buildNetwork(tasks, [...(links ?? []), { id: "__trial", task_id: a, depends_on_id: b }], opts);
+  if (trial.stuck.length > net.stuck.length) return "That would make a loop: the other task already waits on this one.";
+  return null;
+}
+
+/**
+ * The long pole: the unfinished critical task with the most work left
+ * (working days × share not done); the later wins a tie (it sits nearer
+ * the finish, so the finish waits on it most directly). Null when
+ * nothing critical is left.
+ */
+export function longPole(plan) {
+  let best = null;
+  let bestLeft = -1;
+  for (const id of plan?.critical ?? []) {
+    const r = plan.rows.get(id);
+    if (!r || r.pinned || r.milestone) continue;
+    const left = (r.duration * (100 - r.progress)) / 100;
+    if (left >= bestLeft) {
+      best = r;
+      bestLeft = left;
+    }
+  }
+  return best ? best.id : null;
+}