@zxyycom/vibe-check 0.0.1

package/src/project-run/task-scheduler/scheduler-blocker-summary.ts

@@ -0,0 +1,42 @@
+import type { SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import type { SchedulerBlockerSummary, SchedulerCapacity } from "./scheduler-decision-model.ts";
+
+/** Summarizes why pending Tasks cannot currently advance. */
+export function summarizeSchedulerBlockers(
+  state: SchedulerInspection,
+  capacity: SchedulerCapacity
+): SchedulerBlockerSummary {
+  let dependency = 0;
+  let mutex = 0;
+  for (const task of state.pendingTasks) {
+    if (hasUncompletedDependency(task.dependsOn, state.settlementKindByTaskId)) {
+      dependency += 1;
+      continue;
+    }
+    if (hasRunningMutex(task.mutex, state.runningMutexes)) mutex += 1;
+  }
+  return Object.freeze({
+    dependency,
+    mutex,
+    rootCapacity: state.runningTaskIds.size >= state.maxParallel,
+    scopeCapacity:
+      capacity.effectiveMaxParallel < state.maxParallel &&
+      state.runningTaskIds.size >= capacity.effectiveMaxParallel
+  });
+}
+
+function hasUncompletedDependency(
+  dependencyIds: readonly string[],
+  settlementKindByTaskId: SchedulerInspection["settlementKindByTaskId"]
+): boolean {
+  return dependencyIds.some(
+    (dependencyId) => settlementKindByTaskId.get(dependencyId) !== "completed"
+  );
+}
+
+function hasRunningMutex(
+  mutexNames: readonly string[],
+  runningMutexes: SchedulerInspection["runningMutexes"]
+): boolean {
+  return mutexNames.some((mutexName) => runningMutexes.has(mutexName));
+}

package/src/project-run/task-scheduler/scheduler-decision-inspection.ts

@@ -0,0 +1,199 @@
+import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope } from "./graph.ts";
+import { summarizeSchedulerBlockers } from "./scheduler-blocker-summary.ts";
+import type {
+  SchedulerAwaitReason,
+  SchedulerCapacity,
+  SchedulerDecisionContext,
+  SchedulerSettlementKind,
+  SchedulerSnapshot
+} from "./scheduler-decision-model.ts";
+
+export interface SchedulerInspection {
+  readonly activeScopeIds: ReadonlySet<string>;
+  readonly graph: PlannedTaskGraph;
+  readonly maxParallel: number;
+  readonly pendingTasks: readonly PlannedTask[];
+  readonly reservationTaskId: string | undefined;
+  readonly runningMutexes: ReadonlySet<string>;
+  readonly runningTaskIds: ReadonlySet<string>;
+  readonly settlementKindByTaskId: ReadonlyMap<string, SchedulerSettlementKind>;
+}
+
+export function inspectSnapshot(snapshot: SchedulerSnapshot): SchedulerInspection {
+  const tasksById = new Map(snapshot.graph.tasks.map((task) => [task.id, task] as const));
+  const pendingTasks = snapshot.pendingTaskIds.map((taskId) => pendingTaskFor(taskId, tasksById));
+  return Object.freeze({
+    activeScopeIds: new Set(snapshot.activeScopeIds),
+    graph: snapshot.graph,
+    maxParallel: snapshot.maxParallel,
+    pendingTasks: Object.freeze(pendingTasks),
+    reservationTaskId: snapshot.reservationTaskId,
+    runningMutexes: new Set(snapshot.runningMutexes),
+    runningTaskIds: new Set(snapshot.runningTaskIds),
+    settlementKindByTaskId: new Map(
+      snapshot.settledTasks.map(({ taskId, kind }) => [taskId, kind] as const)
+    )
+  });
+}
+
+export function decisionContext(state: SchedulerInspection): SchedulerDecisionContext {
+  const capacity = capacityFor(state);
+  return Object.freeze({
+    blockers: summarizeSchedulerBlockers(state, capacity),
+    capacity,
+    reservation: Object.freeze({ taskId: state.reservationTaskId ?? null })
+  });
+}
+
+export function selectBlockedTask(
+  state: SchedulerInspection
+): Readonly<{ readonly dependencyIds: readonly string[]; readonly task: PlannedTask }> | undefined {
+  for (let index = state.pendingTasks.length - 1; index >= 0; index -= 1) {
+    const task = state.pendingTasks[index];
+    const dependencyIds = blockingDependencyIds(task, state.settlementKindByTaskId);
+    if (dependencyIds !== undefined)
+      return Object.freeze({ dependencyIds: Object.freeze(dependencyIds), task });
+  }
+  return undefined;
+}
+
+export function isDependencyMutexEligible(task: PlannedTask, state: SchedulerInspection): boolean {
+  return (
+    task.dependsOn.every(
+      (dependencyId) => state.settlementKindByTaskId.get(dependencyId) === "completed"
+    ) && task.mutex.every((mutex) => !state.runningMutexes.has(mutex))
+  );
+}
+
+export function capacityWaitReason(state: SchedulerInspection): SchedulerAwaitReason {
+  return state.runningTaskIds.size >= state.maxParallel ? "root-capacity" : "active-scope-capacity";
+}
+
+export function canAdmit(state: SchedulerInspection, task: PlannedTask): boolean {
+  return state.runningTaskIds.size < prospectiveMaxParallel(state, task);
+}
+
+export function activationScopeFor(
+  state: SchedulerInspection,
+  task: PlannedTask
+): PlannedTaskScope | undefined {
+  const scope = scopeForTask(state, task);
+  return scope?.activationTaskIds.includes(task.id) === true && !state.activeScopeIds.has(scope.id)
+    ? scope
+    : undefined;
+}
+
+export function selectTighteningTask(
+  state: SchedulerInspection,
+  eligibleTasks: readonly PlannedTask[],
+  effectiveMaxParallel: number
+): PlannedTask | undefined {
+  return eligibleTasks
+    .filter((task) => activatesTighteningScope(state, task, effectiveMaxParallel))
+    .sort((left, right) => compareConstrainedTasks(state, left, right))[0];
+}
+
+export function selectConstrainedContinuation(
+  state: SchedulerInspection,
+  eligibleTasks: readonly PlannedTask[],
+  effectiveMaxParallel: number
+): PlannedTask | undefined {
+  return eligibleTasks
+    .filter((task) => isConstrainedContinuation(state, task, effectiveMaxParallel))
+    .sort((left, right) => compareConstrainedTasks(state, left, right))[0];
+}
+
+function pendingTaskFor(taskId: string, tasksById: ReadonlyMap<string, PlannedTask>): PlannedTask {
+  const task = tasksById.get(taskId);
+  if (task === undefined) throw new Error(`scheduler snapshot has unknown pending task ${taskId}`);
+  return task;
+}
+
+function blockingDependencyIds(
+  task: PlannedTask,
+  settlementKindByTaskId: ReadonlyMap<string, SchedulerSettlementKind>
+): string[] | undefined {
+  const settlementKinds = task.dependsOn.map(
+    (dependencyId) => [dependencyId, settlementKindByTaskId.get(dependencyId)] as const
+  );
+  if (settlementKinds.some(([, kind]) => kind === undefined)) return undefined;
+  const dependencyIds = settlementKinds.flatMap(([dependencyId, kind]) =>
+    kind === "completed" ? [] : [dependencyId]
+  );
+  return dependencyIds.length === 0 ? undefined : dependencyIds;
+}
+
+function capacityFor(state: SchedulerInspection): SchedulerCapacity {
+  return Object.freeze({
+    effectiveMaxParallel: effectiveMaxParallelFor(state),
+    maxParallel: state.maxParallel,
+    running: state.runningTaskIds.size
+  });
+}
+
+function effectiveMaxParallelFor(state: SchedulerInspection): number {
+  let effective = state.maxParallel;
+  for (const scope of state.graph.scopes) {
+    if (state.activeScopeIds.has(scope.id)) effective = Math.min(effective, scope.maxParallel);
+  }
+  return effective;
+}
+
+function prospectiveMaxParallel(state: SchedulerInspection, task: PlannedTask): number {
+  const scope = activationScopeFor(state, task);
+  return scope === undefined
+    ? effectiveMaxParallelFor(state)
+    : Math.min(effectiveMaxParallelFor(state), scope.maxParallel);
+}
+
+function activatesTighteningScope(
+  state: SchedulerInspection,
+  task: PlannedTask,
+  effectiveMaxParallel: number
+): boolean {
+  const scope = activationScopeFor(state, task);
+  return scope !== undefined && scope.maxParallel < effectiveMaxParallel;
+}
+
+function isConstrainedContinuation(
+  state: SchedulerInspection,
+  task: PlannedTask,
+  effectiveMaxParallel: number
+): boolean {
+  const scope = scopeForTask(state, task);
+  return (
+    scope !== undefined &&
+    state.activeScopeIds.has(scope.id) &&
+    scope.maxParallel < state.maxParallel &&
+    scope.maxParallel === effectiveMaxParallel
+  );
+}
+
+function compareConstrainedTasks(
+  state: SchedulerInspection,
+  left: PlannedTask,
+  right: PlannedTask
+): number {
+  const leftScope = scopeForTask(state, left);
+  const rightScope = scopeForTask(state, right);
+  if (leftScope === undefined || rightScope === undefined) {
+    throw new Error("constrained task is missing a scope");
+  }
+  return (
+    leftScope.maxParallel - rightScope.maxParallel ||
+    compareText(leftScope.id, rightScope.id) ||
+    compareText(left.id, right.id)
+  );
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function scopeForTask(state: SchedulerInspection, task: PlannedTask): PlannedTaskScope | undefined {
+  return task.scopeId === undefined
+    ? undefined
+    : state.graph.scopes.find((scope) => scope.id === task.scopeId);
+}

package/src/project-run/task-scheduler/scheduler-decision-model.ts

@@ -0,0 +1,158 @@
+import type { PlannedTaskGraph } from "./graph.ts";
+
+export type SchedulerSettlementKind = "completed" | "failed" | "blocked" | "cancelled-before-start";
+
+export type SchedulerTrigger =
+  | Readonly<{ readonly kind: "execution-started" }>
+  | Readonly<{ readonly kind: "admission-continued" }>
+  | Readonly<{ readonly kind: "blocked-settled"; readonly taskId: string }>
+  | Readonly<{
+      readonly kind: "task-settled";
+      readonly settlementKind: SchedulerSettlementKind;
+      readonly taskId: string;
+    }>
+  | Readonly<{ readonly kind: "cancellation-observed" }>
+  | Readonly<{ readonly kind: "cancellation-applied" }>;
+
+export interface SchedulerSnapshot {
+  readonly graph: PlannedTaskGraph;
+  readonly isAbortRequested: boolean;
+  readonly isCancelled: boolean;
+  readonly pendingTaskIds: readonly string[];
+  readonly reservationTaskId: string | undefined;
+  readonly runningMutexes: readonly string[];
+  readonly runningTaskIds: readonly string[];
+  readonly settledTasks: readonly Readonly<{
+    readonly kind: SchedulerSettlementKind;
+    readonly taskId: string;
+  }>[];
+  readonly activeScopeIds: readonly string[];
+  readonly maxParallel: number;
+}
+
+export interface SchedulerCapacity {
+  readonly effectiveMaxParallel: number;
+  readonly maxParallel: number;
+  readonly running: number;
+}
+
+export interface SchedulerBlockerSummary {
+  readonly dependency: number;
+  readonly mutex: number;
+  readonly rootCapacity: boolean;
+  readonly scopeCapacity: boolean;
+}
+
+export interface SchedulerReservationContext {
+  readonly taskId: string | null;
+}
+
+export interface SchedulerDecisionContext {
+  readonly blockers: SchedulerBlockerSummary;
+  readonly capacity: SchedulerCapacity;
+  readonly reservation: SchedulerReservationContext;
+}
+
+export type ReservationUpdate =
+  | Readonly<{ readonly kind: "unchanged" }>
+  | Readonly<{ readonly kind: "set"; readonly taskId: string }>
+  | Readonly<{ readonly kind: "clear" }>;
+
+export type SchedulerAdmissionReason =
+  | "reservation"
+  | "tightening-scope"
+  | "constrained-continuation"
+  | "canonical-order";
+
+export type SchedulerAwaitReason =
+  | "cancellation-drain"
+  | "dependency-or-mutex"
+  | "running-drain"
+  | "root-capacity"
+  | "active-scope-capacity"
+  | "reserved-tightening-scope";
+
+export type SchedulerDecision = SchedulerDecisionContext &
+  (
+    | Readonly<{
+        readonly eligibleCount: number;
+        readonly kind: "admit";
+        readonly reason: SchedulerAdmissionReason;
+        readonly reservationUpdate: ReservationUpdate;
+        readonly scopeToActivate: string | null;
+        readonly taskId: string;
+        readonly trigger: SchedulerTrigger;
+      }>
+    | Readonly<{
+        readonly dependencyIds: readonly string[];
+        readonly kind: "settle-blocked";
+        readonly taskId: string;
+        readonly trigger: SchedulerTrigger;
+      }>
+    | Readonly<{
+        readonly eligibleCount: number;
+        readonly kind: "await-running";
+        readonly reason: SchedulerAwaitReason;
+        readonly reservationUpdate: ReservationUpdate;
+        readonly trigger: SchedulerTrigger;
+      }>
+    | Readonly<{
+        readonly kind: "cancel-pending";
+        readonly taskIds: readonly string[];
+        readonly trigger: SchedulerTrigger;
+      }>
+    | Readonly<{
+        readonly cancelled: boolean;
+        readonly kind: "complete";
+        readonly trigger: SchedulerTrigger;
+      }>
+  );
+
+export function reservationUnchanged(): ReservationUpdate {
+  return Object.freeze({ kind: "unchanged" });
+}
+
+export function reservationSet(taskId: string): ReservationUpdate {
+  return Object.freeze({ kind: "set", taskId });
+}
+
+export function reservationClear(): ReservationUpdate {
+  return Object.freeze({ kind: "clear" });
+}
+
+export function freezeDecision(decision: SchedulerDecision): SchedulerDecision {
+  const trigger = freezeTrigger(decision.trigger);
+  switch (decision.kind) {
+    case "admit":
+    case "await-running":
+      return Object.freeze({ ...decision, trigger });
+    case "settle-blocked":
+      return Object.freeze({
+        ...decision,
+        dependencyIds: Object.freeze([...decision.dependencyIds]),
+        trigger
+      });
+    case "cancel-pending":
+      return Object.freeze({ ...decision, taskIds: Object.freeze([...decision.taskIds]), trigger });
+    case "complete":
+      return Object.freeze({ ...decision, trigger });
+  }
+}
+
+function freezeTrigger(trigger: SchedulerTrigger): SchedulerTrigger {
+  switch (trigger.kind) {
+    case "execution-started":
+    case "admission-continued":
+    case "cancellation-observed":
+    case "cancellation-applied":
+      return Object.freeze({ kind: trigger.kind });
+    case "blocked-settled":
+      return Object.freeze({ kind: trigger.kind, taskId: trigger.taskId });
+    case "task-settled":
+      return Object.freeze({
+        kind: trigger.kind,
+        settlementKind: trigger.settlementKind,
+        taskId: trigger.taskId
+      });
+  }
+}

package/src/project-run/task-scheduler/scheduler-decision.ts

@@ -0,0 +1,103 @@
+import { decideAdmission, type SchedulerDecisionCycle } from "./scheduler-admission-decision.ts";
+import {
+  decisionContext,
+  inspectSnapshot,
+  selectBlockedTask
+} from "./scheduler-decision-inspection.ts";
+import { freezeDecision, reservationUnchanged } from "./scheduler-decision-model.ts";
+import type {
+  SchedulerDecision,
+  SchedulerSnapshot,
+  SchedulerTrigger
+} from "./scheduler-decision-model.ts";
+
+export type {
+  SchedulerDecision,
+  SchedulerSettlementKind,
+  SchedulerSnapshot,
+  SchedulerTrigger
+} from "./scheduler-decision-model.ts";
+
+/**
+ * Computes the next generic task-engine action from an immutable state projection.
+ * Starting work, awaiting promises, cancellation, and diagnostic output remain in
+ * the imperative scheduler shell.
+ */
+export function decideScheduler(
+  snapshot: SchedulerSnapshot,
+  trigger: SchedulerTrigger
+): SchedulerDecision {
+  const state = inspectSnapshot(snapshot);
+  const cycle: SchedulerDecisionCycle = Object.freeze({
+    context: decisionContext(state),
+    state,
+    trigger
+  });
+  const terminalDecision = decideTerminalSchedulerAction(cycle, snapshot);
+  if (terminalDecision !== undefined) return terminalDecision;
+
+  const blocked = selectBlockedTask(state);
+  if (blocked !== undefined) {
+    return freezeDecision({
+      ...cycle.context,
+      dependencyIds: blocked.dependencyIds,
+      kind: "settle-blocked",
+      taskId: blocked.task.id,
+      trigger
+    });
+  }
+
+  return decideAdmission(cycle);
+}
+
+function decideTerminalSchedulerAction(
+  cycle: SchedulerDecisionCycle,
+  snapshot: SchedulerSnapshot
+): SchedulerDecision | undefined {
+  if (cycle.state.pendingTasks.length === 0 && cycle.state.runningTaskIds.size === 0) {
+    return freezeDecision({
+      ...cycle.context,
+      cancelled: snapshot.isCancelled,
+      kind: "complete",
+      trigger: cycle.trigger
+    });
+  }
+  if (snapshot.isAbortRequested && !snapshot.isCancelled) {
+    return freezeDecision({
+      ...cycle.context,
+      kind: "cancel-pending",
+      taskIds: snapshot.pendingTaskIds,
+      trigger: Object.freeze({ kind: "cancellation-observed" })
+    });
+  }
+  if (snapshot.isCancelled) {
+    if (cycle.state.pendingTasks.length > 0) {
+      throw new Error("cancelled scheduler state retains pending tasks");
+    }
+    return cancellationDrainDecision(cycle);
+  }
+  if (cycle.state.pendingTasks.length === 0) return runningDrainDecision(cycle);
+  return undefined;
+}
+
+function cancellationDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {
+  return awaitDrainDecision(cycle, "cancellation-drain");
+}
+
+function runningDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {
+  return awaitDrainDecision(cycle, "running-drain");
+}
+
+function awaitDrainDecision(
+  cycle: SchedulerDecisionCycle,
+  reason: Extract<SchedulerDecision, { readonly kind: "await-running" }>["reason"]
+): SchedulerDecision {
+  return freezeDecision({
+    ...cycle.context,
+    eligibleCount: 0,
+    kind: "await-running",
+    reason,
+    reservationUpdate: reservationUnchanged(),
+    trigger: cycle.trigger
+  });
+}