beadcyte 0.4.0

package/src/scheduler.mjs

@@ -0,0 +1,424 @@
+// scheduler.mjs — greedy WIP-cap simulator with TWO CLOCKS (bp-m0g).
+//
+// A bead's elapsed time is mostly waiting; its cost is the work. The model
+// keeps them apart, matching how allocation actually happens:
+//
+//   - Timestep = 1 calendar day, starting today.
+//   - Each human has a WIP cap (roster.json; default 5, per-human overrides,
+//     calibrated by velocity.mjs) and a daily WORK BUDGET: their observed
+//     hours per week spread over five working days, or eight hours a day
+//     when nothing has been recorded — never a whole calendar day.
+//   - WORK CLOCK. Each day a human's in-flight beads consume their remaining
+//     estimate from that budget, in order; a bead that finishes leaves
+//     budget for the next, so several small beads pack into one day (the
+//     day quantum this replaced completed one bead per slot per day, which
+//     projected twenty 17-minute beads as twenty days — bp-81h, decided).
+//     A bead that outruns the budget continues tomorrow.
+//   - WAIT CLOCK. Waiting comes from the project's own stage medians
+//     (stage-waits.mjs): a bead pulled from the unassigned pool waits the
+//     median UNCLAIMED time before its work starts (nobody has claimed it;
+//     the projection says who would); every bead waits the median REVIEW
+//     time after its work ends before it lands. Review holds the WIP slot —
+//     a bead in review is in flight — but spends no work budget. Where the
+//     review median is unknown, the landing is floored at the estimator's
+//     lead-time median so waiting is never assumed to cost nothing.
+//   - A bead is READY when its status is live, every `blocks` dependency is
+//     closed or has LANDED (end_day) by this day, and — for the first pass
+//     of pool picks — it carries `spec:ready`. Dispatch order is priority
+//     ascending, then created_at ascending.
+//   - Beads already in_progress at t=0 start in flight with the estimate
+//     less the time since started_at; beads already in_review sit in the
+//     review wait.
+//   - Backlog (not spec:ready) is scheduled identically and tagged so the
+//     renderer can draw it faint. Pool picks are tagged synthetic_assignee.
+//
+// Entries carry both clocks: work_start_day → work_end_day is the bright
+// part of a bar; start_day → end_day is the whole span including waits and
+// is the landing date. Deliberately no cross-human load balancing and no
+// auto-reassignment: the planner may PROPOSE moves (bp-ufa) and the owner
+// confirms; the simulation projects the allocation as it stands.
+
+const MS_PER_DAY = 86_400_000;
+const DEFAULT_WIP_CAP = 5;
+const WORK_DAYS_PER_WEEK = 5;
+const DEFAULT_HOURS_PER_DAY = 8;
+
+/**
+ * A human's daily work budget in estimate units (fractions of a 24-hour
+ * day, which is what the estimator's `days` are): observed hours per week
+ * over five working days, else eight hours.
+ * @param {{ _hoursPerWeek?: number, hoursPerDay?: number } | undefined} human
+ */
+export function dailyCapacityFor(human) {
+  if (human && typeof human.hoursPerDay === "number" && human.hoursPerDay > 0) return human.hoursPerDay / 24;
+  const perWeek = human?._hoursPerWeek;
+  if (typeof perWeek === "number" && perWeek > 0) return perWeek / WORK_DAYS_PER_WEEK / 24;
+  return DEFAULT_HOURS_PER_DAY / 24;
+}
+
+/**
+ * @param {Array} beads       — all beads (open + closed) from bd list --all
+ * @param {Object} roster     — { humans: [{handle, cap?}], cap: default }
+ * @param {Function} estimate — (bead) → { days, p90, source }
+ * @param {Date} horizon      — stop scheduling past this date
+ * @param {Object} [opts]
+ * @param {{ unclaimedDays?: number|null, reviewDays?: number|null }} [opts.waits]  stage medians (stage-waits.mjs)
+ * @param {number} [opts.minLeadDays]  the estimator's lead-time median: the landing floor where review data is missing
+ * @param {(human: object) => number} [opts.capacityFor]  daily work budget per human; default dailyCapacityFor
+ * @param {Date} [opts.now]  test hook
+ * @returns {{ schedule: Map<string, object>, unscheduled: string[], unassignedBacklog: object[], unassignedProjection: Map<string, object>, waits: object }}
+ */
+export function scheduleGreedy(beads, roster, estimate, horizon, opts = {}) {
+  const today = startOfDay(opts.now ?? new Date());
+  const nowMs = (opts.now ?? new Date()).getTime();
+  const horizonDay = daysBetween(today, startOfDay(horizon));
+  const waits = {
+    unclaimedDays: Math.max(0, opts.waits?.unclaimedDays ?? 0),
+    reviewDays: opts.waits?.reviewDays ?? null,
+  };
+  const minLeadDays = Math.max(0, opts.minLeadDays ?? 0);
+  const capacityFor = opts.capacityFor ?? dailyCapacityFor;
+  const wipCap = new Map();
+  const capacity = new Map();
+  const defaultCap = roster.cap ?? DEFAULT_WIP_CAP;
+  for (const h of roster.humans ?? []) {
+    wipCap.set(h.handle, h.cap ?? defaultCap);
+    capacity.set(h.handle, capacityFor(h));
+  }
+  // The landing of a bead whose work ends at `workEnd` (fractional day).
+  const landingFor = (workStart, workEnd) => {
+    if (waits.reviewDays !== null) return workEnd + Math.max(0, waits.reviewDays);
+    return Math.max(workEnd, workStart + minLeadDays);
+  };
+  const finish = (human, entry, workEnd) => {
+    const end = landingFor(entry.work_start_day, workEnd);
+    schedule.set(entry.bead.id, {
+      id: entry.bead.id,
+      start_day: entry.start_day,
+      end_day: end,
+      work_start_day: entry.work_start_day,
+      work_end_day: workEnd,
+      wait_before_days: entry.work_start_day - entry.start_day,
+      wait_after_days: end - workEnd,
+      backlog: entry.backlog,
+      assignee: human,
+      synthetic_assignee: entry.synthetic ?? false,
+      in_progress_at_start: entry.start_day < 0,
+    });
+    entry.landing = end;
+  };
+
+  const byId = new Map(beads.map((b) => [b.id, b]));
+  const isClosed = (b) => b?.status === "closed";
+  const isFuture = (b) =>
+    b &&
+    b.status !== "closed" &&
+    b.status !== "deferred" &&
+    b.status !== "superseded";
+  const isReady = (b) => {
+    if (!isFuture(b)) return false;
+    for (const d of b.dependencies ?? []) {
+      if (d.type !== "blocks") continue;
+      const dep = byId.get(d.depends_on_id);
+      if (dep && !isClosed(dep)) return false;
+    }
+    return true;
+  };
+  const isSpecReady = (b) => (b.labels ?? []).includes("spec:ready");
+
+  // Priority sort key: priority asc, then created_at asc
+  const prioKey = (b) => [b.priority ?? 4, b.created_at ?? ""];
+  const cmp = (a, b) => {
+    const [pa, ca] = prioKey(a);
+    const [pb, cb] = prioKey(b);
+    return pa - pb || ca.localeCompare(cb);
+  };
+
+  const schedule = new Map();
+  const inFlight = new Map(); // human → [{bead, remaining, start_day, backlog}]
+
+  // Seed in-flight from currently in_progress / in_review beads. In-progress
+  // work has the estimate less what has elapsed (a sliver at least, so it
+  // lands today rather than yesterday); in-review work is done and sits in
+  // the review wait from now.
+  for (const b of beads) {
+    if (b.status !== "in_progress" && b.status !== "in_review") continue;
+    if (!b.assignee) continue;
+    const est = estimate(b);
+    const elapsedDays = b.started_at
+      ? (nowMs - new Date(b.started_at).getTime()) / MS_PER_DAY
+      : 0;
+    const startDay = -Math.max(0, elapsedDays);
+    if (!inFlight.has(b.assignee)) inFlight.set(b.assignee, []);
+    const entry = {
+      bead: b,
+      remaining: b.status === "in_review" ? 0 : Math.max(0.001, est.days - Math.max(0, elapsedDays)),
+      start_day: startDay,
+      work_start_day: startDay,
+      working: true, // already begun: its start is its recorded start
+      backlog: !isSpecReady(b),
+      landing: null,
+    };
+    inFlight.get(b.assignee).push(entry);
+    if (b.status === "in_review") finish(b.assignee, entry, 0);
+  }
+
+  // The queues of unstarted beads per human (spec:ready and backlog together;
+  // rendered distinctly, scheduled identically), plus a SHARED unassigned pool
+  // that any human can dip into when their own queue is empty (or from the
+  // start if `--force-synthetic` is on). Beads pulled from the pool land in
+  // schedule entries with `synthetic_assignee: true` so the renderer can
+  // signal "we made this up."
+  const queueByHuman = new Map();
+  const unassignedPool = [];
+  for (const b of beads) {
+    if (!isFuture(b)) continue;
+    if (b.status === "in_progress" || b.status === "in_review") continue;
+    if (!b.assignee) {
+      unassignedPool.push(b);
+      continue;
+    }
+    if (!queueByHuman.has(b.assignee)) queueByHuman.set(b.assignee, []);
+    queueByHuman.get(b.assignee).push(b);
+  }
+  for (const q of queueByHuman.values()) q.sort(cmp);
+  unassignedPool.sort(cmp);
+
+  // Affinity map: human handle → array of area/label markers that match beads
+  // they should prefer. Built from roster.json's per-human `labels` and
+  // `areas`. Used to give the pool a soft-preference dispatch, so
+  // component::Data drifts to one person and component::UX to another.
+  // Falls through to "any spec:ready bead" if no affinity match.
+  const affinityByHuman = new Map();
+  for (const h of roster.humans ?? []) affinityByHuman.set(h.handle, affinityMarksFor(h));
+
+  function poolPickFor(human, day) {
+    const marks = affinityByHuman.get(human);
+    // Two-pass: affinity spec:ready → any spec:ready → any (incl. backlog).
+    const passes = [
+      (b) => isSpecReady(b) && beadMatchesAffinity(b, marks),
+      (b) => isSpecReady(b),
+      (b) => true,
+    ];
+    for (const pred of passes) {
+      const idx = unassignedPool.findIndex(
+        (b) => pred(b) && depsMetBy(b, byId, schedule, day),
+      );
+      if (idx >= 0) return unassignedPool.splice(idx, 1)[0];
+    }
+    return null;
+  }
+
+  // Timestep loop. Each day, per human: free slots whose review wait has
+  // ended; spend the day's work budget on in-flight beads in order, then on
+  // newly dispatched ones while budget and slots remain.
+  for (let day = 0; day <= horizonDay; day++) {
+    for (const [human, cap] of wipCap.entries()) {
+      const list = inFlight.get(human) ?? [];
+      // 1. Landed beads leave their slot. A landing inside a day frees the
+      // slot for that day, so a cap of one can still chain several short
+      // beads through it.
+      const prune = () => {
+        for (let i = list.length - 1; i >= 0; i--) {
+          const entry = list[i];
+          if (entry.landing !== null && Math.floor(entry.landing) <= day) list.splice(i, 1);
+        }
+      };
+      prune();
+      // 2. Work: spend the budget on beads still working, in order. Work
+      // advances at wall-clock rate within the day — a 2.4h bead is 0.1 of a
+      // day wide — and the budget caps how much of the day is worked.
+      const dayBudget = capacity.get(human) ?? dailyCapacityFor(undefined);
+      let budget = dayBudget;
+      const spend = (entry) => {
+        if (entry.landing !== null) return; // in review already
+        if (entry.work_start_day > day + 1 - 1e-9) return; // still in its unclaimed wait
+        if (budget <= 1e-9) return;
+        const usedBefore = dayBudget - budget;
+        // A bead whose work begins today begins after what was already
+        // worked today.
+        if (!entry.working) {
+          entry.working = true;
+          entry.work_start_day = Math.max(entry.work_start_day, day + usedBefore);
+        }
+        const used = Math.min(entry.remaining, budget);
+        entry.remaining -= used;
+        budget -= used;
+        if (entry.remaining <= 1e-9) finish(human, entry, day + (dayBudget - budget));
+      };
+      for (const entry of list) spend(entry);
+      prune();
+      // 3. Dispatch: while a slot is free and budget remains (or the bead
+      // will wait first), take the next ready bead — own queue first, then
+      // the shared pool with affinity preference (synthetic, marked).
+      const q = queueByHuman.get(human) ?? [];
+      while (list.length < cap) {
+        let bead = null;
+        let synthetic = false;
+        const idx = q.findIndex((b) => depsMetBy(b, byId, schedule, day));
+        if (idx >= 0) {
+          bead = q.splice(idx, 1)[0];
+        } else {
+          bead = poolPickFor(human, day);
+          synthetic = !!bead;
+        }
+        if (!bead) break;
+        const est = estimate(bead);
+        const waitBefore = synthetic ? waits.unclaimedDays : 0;
+        const entry = {
+          bead,
+          remaining: Math.max(0.001, est.days),
+          start_day: day,
+          work_start_day: day + waitBefore,
+          working: false,
+          backlog: !isSpecReady(bead),
+          synthetic,
+          landing: null,
+        };
+        list.push(entry);
+        spend(entry);
+        prune();
+        // Out of budget: whatever was dispatched keeps its slot and works
+        // tomorrow; nothing more starts today.
+        if (budget <= 1e-9) break;
+      }
+      inFlight.set(human, list);
+    }
+
+    // Everyone drained? (Landed-but-not-yet-freed entries do not count as
+    // live work.)
+    let live = 0;
+    for (const l of inFlight.values()) live += l.filter((e) => e.landing === null).length;
+    let queued = 0;
+    for (const q of queueByHuman.values()) queued += q.length;
+    if (live === 0 && queued === 0 && unassignedPool.length === 0) break;
+  }
+
+  // Anything still working at the horizon → clamped there, marked truncated.
+  // Beads that landed but were waiting to free their slot already have an
+  // entry.
+  const unscheduled = [];
+  for (const [human, list] of inFlight) {
+    for (const entry of list) {
+      if (entry.landing !== null) continue;
+      schedule.set(entry.bead.id, {
+        id: entry.bead.id,
+        start_day: entry.start_day,
+        end_day: horizonDay,
+        work_start_day: entry.work_start_day,
+        work_end_day: horizonDay,
+        wait_before_days: entry.work_start_day - entry.start_day,
+        wait_after_days: 0,
+        backlog: entry.backlog,
+        assignee: human,
+        synthetic_assignee: entry.synthetic ?? false,
+        in_progress_at_start: entry.start_day < 0,
+        truncated: true,
+      });
+    }
+  }
+  for (const q of queueByHuman.values())
+    for (const b of q) unscheduled.push(b.id);
+
+  // Pool beads that ran out the clock (horizon reached, still queued) — project
+  // them at earliest-possible start so they render somewhere honest rather than
+  // vanish. These represent "backlog depth beyond the window," and are drawn
+  // extra-dim.
+  const unassignedProjection = new Map();
+  for (const b of unassignedPool) {
+    let earliest = horizonDay; // if it didn't dispatch within window, it starts past horizon
+    for (const d of b.dependencies ?? []) {
+      if (d.type !== "blocks") continue;
+      const dep = byId.get(d.depends_on_id);
+      if (!dep) continue;
+      if (dep.status === "closed") continue;
+      const sched = schedule.get(d.depends_on_id);
+      if (sched) earliest = Math.max(earliest, sched.end_day);
+      else earliest = horizonDay;
+    }
+    const est = estimate(b);
+    const workStart = earliest + waits.unclaimedDays;
+    const workEnd = Math.min(horizonDay, workStart + est.days);
+    unassignedProjection.set(b.id, {
+      id: b.id,
+      start_day: earliest,
+      end_day: Math.min(horizonDay, landingFor(workStart, workEnd)),
+      work_start_day: Math.min(horizonDay, workStart),
+      work_end_day: workEnd,
+      wait_before_days: waits.unclaimedDays,
+      wait_after_days: Math.max(0, Math.min(horizonDay, landingFor(workStart, workEnd)) - workEnd),
+      backlog: !((b.labels ?? []).includes("spec:ready")),
+      unassigned: true,
+    });
+    unscheduled.push(b.id);
+  }
+
+  return {
+    schedule,
+    unscheduled,
+    unassignedBacklog: unassignedPool,
+    unassignedProjection,
+    waits: { ...waits, minLeadDays },
+  };
+}
+
+/**
+ * A human's affinity marks: roster labels as written, areas lower-cased.
+ * Exported (bp-wfe) so the frontier's proposals read the SAME routing the
+ * scheduler applies, rather than a second definition that drifts.
+ * @param {{ labels?: string[], areas?: string[] }} h
+ * @returns {Set<string>}
+ */
+export function affinityMarksFor(h) {
+  const marks = new Set(h.labels ?? []);
+  for (const a of h.areas ?? []) marks.add(a.toLowerCase());
+  return marks;
+}
+
+/**
+ * Which of a human's marks a bead matches: a label as written, or an area
+ * keyword found in the title/labels (component::/track:: marks only match
+ * as labels). Empty when none.
+ * @param {{ title?: string, labels?: string[] | null }} b
+ * @param {Set<string> | undefined} marks
+ * @returns {string[]}
+ */
+export function beadAffinityMatches(b, marks) {
+  if (!marks || marks.size === 0) return [];
+  const labels = b.labels ?? [];
+  const out = [];
+  for (const l of labels) if (marks.has(l)) out.push(l);
+  // Also match a bead's title/label text against seat-area keywords
+  const hay = `${b.title ?? ""} ${labels.join(" ")}`.toLowerCase();
+  for (const m of marks) {
+    if (m.startsWith("component::") || m.startsWith("track::")) continue;
+    if (!out.includes(m) && hay.includes(m)) out.push(m);
+  }
+  return out;
+}
+
+function beadMatchesAffinity(b, marks) {
+  return beadAffinityMatches(b, marks).length > 0;
+}
+
+function depsMetBy(bead, byId, schedule, day) {
+  for (const d of bead.dependencies ?? []) {
+    if (d.type !== "blocks") continue;
+    const dep = byId.get(d.depends_on_id);
+    if (!dep) continue;
+    if (dep.status === "closed") continue;
+    const sched = schedule.get(d.depends_on_id);
+    if (sched && sched.end_day <= day) continue;
+    return false;
+  }
+  return true;
+}
+
+function startOfDay(d) {
+  const x = new Date(d);
+  x.setHours(0, 0, 0, 0);
+  return x;
+}
+function daysBetween(a, b) {
+  return Math.round((b.getTime() - a.getTime()) / MS_PER_DAY);
+}