@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -1,177 +1,186 @@
-import type { PlannedTask } from "./graph.ts";
-import {
-  activationScopeFor,
-  canAdmit,
-  capacityWaitReason,
-  isDependencyMutexEligible,
-  selectConstrainedContinuation,
-  selectTighteningTask,
-  type SchedulerInspection
-} from "./scheduler-decision-inspection.ts";
+import type { AdmissionPolicyContext } from "../../project-definition/project-definition.ts";
+import type {
+  AdmissionCandidate,
+  AdmissionPolicyDecision,
+  AdmissionSelectionPolicy
+} from "./admission-selection-policy.ts";
 import {
   freezeDecision,
-  reservationClear,
-  reservationSet,
-  reservationUnchanged,
-  type ReservationUpdate,
-  type SchedulerAdmissionReason,
-  type SchedulerAwaitReason,
+  type SchedulerAdmissionCandidateFact,
+  type SchedulerAdmissionHardGuard,
   type SchedulerDecision,
   type SchedulerDecisionContext,
   type SchedulerTrigger
 } from "./scheduler-decision-model.ts";
+import type { SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import {
+  admissionCandidatesForCore,
+  scopeToActivateForCore,
+  type AdmissionCoreState
+} from "./admission-core/core.ts";
 
 export interface SchedulerDecisionCycle {
+  readonly admissionCore: AdmissionCoreState;
   readonly context: SchedulerDecisionContext;
+  readonly policy: AdmissionSelectionPolicy;
+  /** Invoked immediately before the private policy seam enters a custom callback. */
+  readonly measurement?: () => AdmissionPolicyContext["measurement"];
   readonly state: SchedulerInspection;
   readonly trigger: SchedulerTrigger;
 }
 
-interface AdmissionSelection {
-  readonly reason: SchedulerAdmissionReason;
-  readonly reservationUpdate: ReservationUpdate;
-  readonly task: PlannedTask;
-}
-
-interface AwaitingSchedulerDecision {
-  readonly eligibleTasks: readonly PlannedTask[];
-  readonly reason: SchedulerAwaitReason;
-  readonly reservationUpdate: ReservationUpdate;
-}
-
 export function decideAdmission(cycle: SchedulerDecisionCycle): SchedulerDecision {
-  const eligibleTasks = cycle.state.pendingTasks.filter((task) =>
-    isDependencyMutexEligible(task, cycle.state)
+  const candidates = Object.freeze(
+    admissionCandidatesForCore(cycle.admissionCore).map((candidate) =>
+      Object.freeze({ canAdmit: candidate.canAdmit, task: candidate.task })
+    )
   );
-  if (eligibleTasks.length === 0) {
-    return awaitDecision(cycle, {
-      eligibleTasks,
-      reason: "dependency-or-mutex",
-      reservationUpdate: reservationUnchanged()
-    });
-  }
+  if (candidates.length === 0) return awaitDecision(cycle, candidates);
 
-  const reservedTask = taskById(cycle.state.reservationTaskId, eligibleTasks);
-  if (reservedTask !== undefined)
-    return decideReservedAdmission(cycle, eligibleTasks, reservedTask);
-
-  return decideUnreservedAdmission(cycle, eligibleTasks);
-}
-
-function decideReservedAdmission(
-  cycle: SchedulerDecisionCycle,
-  eligibleTasks: readonly PlannedTask[],
-  reservedTask: PlannedTask
-): SchedulerDecision {
-  const selection: AdmissionSelection = {
-    reason: "reservation",
-    reservationUpdate: reservationClear(),
-    task: reservedTask
-  };
-  if (canAdmit(cycle.state, reservedTask)) return admitDecision(cycle, selection, eligibleTasks);
-  return awaitDecision(cycle, {
-    eligibleTasks,
-    reason: "reserved-tightening-scope",
-    reservationUpdate: reservationUnchanged()
-  });
-}
-
-function decideUnreservedAdmission(
-  cycle: SchedulerDecisionCycle,
-  eligibleTasks: readonly PlannedTask[]
-): SchedulerDecision {
-  const reservationUpdate = staleReservationUpdate(cycle.state);
-  const tighteningTask = selectTighteningTask(
-    cycle.state,
-    eligibleTasks,
-    cycle.context.capacity.effectiveMaxParallel
-  );
-  if (tighteningTask !== undefined) {
-    return admissionOrCapacityWait(
-      cycle,
-      eligibleTasks,
-      { reason: "tightening-scope", reservationUpdate, task: tighteningTask },
-      "reserved-tightening-scope"
-    );
-  }
-
-  const continuation = selectConstrainedContinuation(
-    cycle.state,
-    eligibleTasks,
-    cycle.context.capacity.effectiveMaxParallel
-  );
-  if (continuation !== undefined) {
-    return admissionOrCapacityWait(
-      cycle,
-      eligibleTasks,
-      { reason: "constrained-continuation", reservationUpdate, task: continuation },
-      capacityWaitReason(cycle.state)
-    );
-  }
-
-  return admissionOrCapacityWait(
-    cycle,
-    eligibleTasks,
-    { reason: "canonical-order", reservationUpdate, task: eligibleTasks[0] },
-    capacityWaitReason(cycle.state)
+  const measurement = cycle.measurement?.();
+  const result = validatePolicyDecision(
+    cycle.policy.decide(
+      Object.freeze({
+        admissionCore: cycle.admissionCore,
+        candidates,
+        graph: cycle.state.graph,
+        graphSnapshot: cycle.context.graphIdentity,
+        inspection: cycle.state,
+        ...(measurement === undefined ? {} : { measurement })
+      })
+    )
   );
-}
-
-function admissionOrCapacityWait(
-  cycle: SchedulerDecisionCycle,
-  eligibleTasks: readonly PlannedTask[],
-  selection: AdmissionSelection,
-  waitReason: SchedulerAwaitReason
-): SchedulerDecision {
-  if (canAdmit(cycle.state, selection.task)) return admitDecision(cycle, selection, eligibleTasks);
-  const reservationUpdate =
-    selection.reason === "tightening-scope"
-      ? reservationSet(selection.task.id)
-      : selection.reservationUpdate;
-  return awaitDecision(cycle, { eligibleTasks, reason: waitReason, reservationUpdate });
+  return result.kind === "select"
+    ? admitDecision(cycle, candidates, result)
+    : awaitDecision(cycle, candidates, result);
 }
 
 function admitDecision(
   cycle: SchedulerDecisionCycle,
-  selection: AdmissionSelection,
-  eligibleTasks: readonly PlannedTask[]
+  candidates: readonly AdmissionCandidate[],
+  result: Extract<AdmissionPolicyDecision, { readonly kind: "select" }>
 ): SchedulerDecision {
+  const candidate = candidateFor(result.taskId, candidates);
+  if (candidate === undefined) {
+    throw new AdmissionPolicyFault("non-candidate-select");
+  }
+  if (!candidate.canAdmit) {
+    throw new AdmissionPolicyFault("capacity-invalid-select");
+  }
   return freezeDecision({
     ...cycle.context,
-    eligibleCount: eligibleTasks.length,
+    admissionPriority: candidate.task.admissionPriority,
+    candidates: candidateFacts(candidates),
+    eligibleCount: candidates.length,
+    hardGuard: selectHardGuard(candidate.task.id),
     kind: "admit",
-    reason: selection.reason,
-    reservationUpdate: selection.reservationUpdate,
-    scopeToActivate: activationScopeFor(cycle.state, selection.task)?.id ?? null,
-    taskId: selection.task.id,
+    proposal: result,
+    scopeToActivate: scopeToActivateForCore(cycle.admissionCore, candidate.task.id),
+    taskId: candidate.task.id,
     trigger: cycle.trigger
   });
 }
 
 function awaitDecision(
   cycle: SchedulerDecisionCycle,
-  waiting: AwaitingSchedulerDecision
+  candidates: readonly AdmissionCandidate[],
+  proposal: AdmissionPolicyDecision | null = null
 ): SchedulerDecision {
-  if (cycle.state.runningTaskIds.size === 0) {
-    throw new Error("scheduler has pending tasks but no runnable or running task");
+  if (cycle.state.runningTaskIds.length === 0) {
+    throw new AdmissionPolicyFault("undrainable-wait");
   }
   return freezeDecision({
     ...cycle.context,
-    eligibleCount: waiting.eligibleTasks.length,
+    candidates: candidateFacts(candidates),
+    eligibleCount: candidates.length,
+    hardGuard: waitHardGuard(),
     kind: "await-running",
-    reason: waiting.reason,
-    reservationUpdate: waiting.reservationUpdate,
+    proposal,
     trigger: cycle.trigger
   });
 }
 
-function staleReservationUpdate(state: SchedulerInspection): ReservationUpdate {
-  return state.reservationTaskId === undefined ? reservationUnchanged() : reservationClear();
+function candidateFacts(
+  candidates: readonly AdmissionCandidate[]
+): readonly SchedulerAdmissionCandidateFact[] {
+  return Object.freeze(
+    candidates.map((candidate) =>
+      Object.freeze({ canAdmit: candidate.canAdmit, taskId: candidate.task.id })
+    )
+  );
 }
 
-function taskById(
-  taskId: string | undefined,
-  tasks: readonly PlannedTask[]
-): PlannedTask | undefined {
-  return taskId === undefined ? undefined : tasks.find((task) => task.id === taskId);
+function selectHardGuard(
+  taskId: string
+): Extract<SchedulerAdmissionHardGuard, { readonly kind: "select" }> {
+  return Object.freeze({
+    canAdmit: true,
+    isCandidate: true,
+    kind: "select",
+    lifecycleOpen: true,
+    taskId
+  });
+}
+
+function waitHardGuard(): Extract<SchedulerAdmissionHardGuard, { readonly kind: "wait" }> {
+  return Object.freeze({ kind: "wait", runningCanDrain: true });
+}
+
+function validatePolicyDecision(value: unknown): AdmissionPolicyDecision {
+  if (!isRecord(value)) throw new AdmissionPolicyFault("malformed-proposal");
+  if (value["kind"] === "select") {
+    requireExactKeys(value, ["kind", "taskId"]);
+    if (typeof value["taskId"] !== "string") {
+      throw new AdmissionPolicyFault("malformed-proposal");
+    }
+    return Object.freeze({ kind: "select", taskId: value["taskId"] });
+  }
+  if (value["kind"] === "wait") {
+    requireExactKeys(value, ["kind"]);
+    return Object.freeze({ kind: "wait" });
+  }
+  throw new AdmissionPolicyFault("malformed-proposal");
+}
+
+function candidateFor(
+  taskId: string,
+  candidates: readonly AdmissionCandidate[]
+): AdmissionCandidate | undefined {
+  return candidates.find((candidate) => candidate.task.id === taskId);
+}
+
+function requireExactKeys(value: Readonly<Record<string, unknown>>, keys: readonly string[]): void {
+  const prototype = Reflect.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new AdmissionPolicyFault("malformed-proposal");
+  }
+  const actualKeys = Reflect.ownKeys(value);
+  if (
+    actualKeys.length !== keys.length ||
+    actualKeys.some((key) => typeof key !== "string" || !keys.includes(key))
+  ) {
+    throw new AdmissionPolicyFault("malformed-proposal");
+  }
+}
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+export type AdmissionPolicyFaultCategory =
+  | "callback-threw"
+  | "thenable-proposal"
+  | "malformed-proposal"
+  | "non-candidate-select"
+  | "capacity-invalid-select"
+  | "lifecycle-invalid-select"
+  | "undrainable-wait";
+
+export class AdmissionPolicyFault extends Error {
+  public readonly category: AdmissionPolicyFaultCategory;
+
+  public constructor(category: AdmissionPolicyFaultCategory) {
+    super("admission policy fault");
+    this.category = category;
+  }
 }

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

@@ -8,29 +8,47 @@ export function summarizeSchedulerBlockers(
 ): SchedulerBlockerSummary {
   let dependency = 0;
   let mutex = 0;
+  let resourceCapacity = 0;
   for (const task of state.pendingTasks) {
-    if (hasUncompletedDependency(task.dependsOn, state.settlementKindByTaskId)) {
+    if (hasUnsatisfiedRelation(task, state.settledTasks)) {
       dependency += 1;
       continue;
     }
     if (hasRunningMutex(task.mutex, state.runningMutexes)) mutex += 1;
+    else if (hasResourceShortage(task.resourceClaims, state.resources)) resourceCapacity += 1;
   }
   return Object.freeze({
     dependency,
     mutex,
-    rootCapacity: state.runningTaskIds.size >= state.maxParallel,
+    resourceCapacity,
+    rootCapacity: state.runningTaskIds.length >= state.maxParallel,
     scopeCapacity:
       capacity.effectiveMaxParallel < state.maxParallel &&
-      state.runningTaskIds.size >= capacity.effectiveMaxParallel
+      state.runningTaskIds.length >= capacity.effectiveMaxParallel
   });
 }
 
-function hasUncompletedDependency(
-  dependencyIds: readonly string[],
-  settlementKindByTaskId: SchedulerInspection["settlementKindByTaskId"]
+function hasResourceShortage(
+  claims: SchedulerInspection["pendingTasks"][number]["resourceClaims"],
+  resources: SchedulerInspection["resources"]
 ): boolean {
-  return dependencyIds.some(
-    (dependencyId) => settlementKindByTaskId.get(dependencyId) !== "completed"
+  return claims.some((claim) => {
+    const resource = resources.find(({ resourceId }) => resourceId === claim.resourceId);
+    return resource === undefined || claim.units > resource.available;
+  });
+}
+
+function hasUnsatisfiedRelation(
+  task: SchedulerInspection["pendingTasks"][number],
+  settledTasks: SchedulerInspection["settledTasks"]
+): boolean {
+  return (
+    task.dependsOn.some(
+      (dependencyId) => settlementKindFor(settledTasks, dependencyId) !== "completed"
+    ) ||
+    task.observes.some(
+      (observationId) => settlementKindFor(settledTasks, observationId) === undefined
+    )
   );
 }
 
@@ -38,5 +56,12 @@ function hasRunningMutex(
   mutexNames: readonly string[],
   runningMutexes: SchedulerInspection["runningMutexes"]
 ): boolean {
-  return mutexNames.some((mutexName) => runningMutexes.has(mutexName));
+  return mutexNames.some((mutexName) => runningMutexes.includes(mutexName));
+}
+
+function settlementKindFor(
+  settledTasks: SchedulerInspection["settledTasks"],
+  taskId: string
+): SchedulerInspection["settledTasks"][number]["kind"] | undefined {
+  return settledTasks.find((task) => task.taskId === taskId)?.kind;
 }

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

@@ -1,199 +1,57 @@
-import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope } from "./graph.ts";
+import type { PlannedTask, PlannedTaskGraph } from "./graph.ts";
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
 import { summarizeSchedulerBlockers } from "./scheduler-blocker-summary.ts";
 import type {
-  SchedulerAwaitReason,
   SchedulerCapacity,
   SchedulerDecisionContext,
-  SchedulerSettlementKind,
-  SchedulerSnapshot
+  SchedulerSettlementKind
 } from "./scheduler-decision-model.ts";
 
 export interface SchedulerInspection {
-  readonly activeScopeIds: ReadonlySet<string>;
+  readonly activeScopeIds: readonly string[];
   readonly graph: PlannedTaskGraph;
+  readonly isAbortRequested: boolean;
+  readonly isCancelled: boolean;
   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 {
+  readonly runningMutexes: readonly string[];
+  readonly resources: readonly Readonly<{
+    readonly available: number;
+    readonly capacity: number;
+    readonly inUse: number;
+    readonly resourceId: string;
+  }>[];
+  readonly runningTaskIds: readonly string[];
+  readonly settledTasks: readonly Readonly<{
+    readonly kind: SchedulerSettlementKind;
+    readonly taskId: string;
+  }>[];
+}
+
+export function decisionContext(
+  state: SchedulerInspection,
+  graphIdentity: SchedulerGraphSnapshot
+): SchedulerDecisionContext {
   const capacity = capacityFor(state);
   return Object.freeze({
     blockers: summarizeSchedulerBlockers(state, capacity),
     capacity,
-    reservation: Object.freeze({ taskId: state.reservationTaskId ?? null })
+    graphIdentity
   });
 }
 
-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 {
+export function capacityFor(state: SchedulerInspection): SchedulerCapacity {
   return Object.freeze({
     effectiveMaxParallel: effectiveMaxParallelFor(state),
     maxParallel: state.maxParallel,
-    running: state.runningTaskIds.size
+    running: state.runningTaskIds.length
   });
 }
 
 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);
+    if (state.activeScopeIds.includes(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);
-}