@zxyycom/vibe-check 0.0.1 → 0.0.2

package/src/project-run/task-scheduler/admission-core/selection-query.ts

@@ -0,0 +1,295 @@
+import type { AdmissionSelectionRejectionReason } from "../../../project-definition/scheduler-policy.ts";
+import type { CompiledAdmissionGraph } from "./compiled-graph.ts";
+import {
+  numberFor,
+  statusForSelection,
+  type AdmissionSelectionIndex,
+  type CoreTaskStatus
+} from "./selection-index.ts";
+import {
+  compareScopeCapacityForCompiled,
+  requiredScopeForCompiled,
+  requiredTaskSlotForCompiled
+} from "./selection-seed.ts";
+import type { PlannedTask, PlannedTaskGraph } from "../graph.ts";
+
+type SelectionCoreState = Readonly<{
+  readonly compiled: CompiledAdmissionGraph;
+  readonly selection: AdmissionSelectionIndex;
+}>;
+
+export interface AdmissionCoreSelection {
+  readonly canAdmit: boolean;
+  readonly task: PlannedTask;
+}
+
+export function statusForCore(state: SelectionCoreState, taskSlot: number): CoreTaskStatus {
+  return statusForSelection(state.selection, taskSlot);
+}
+
+export function isCoreComplete(state: SelectionCoreState): boolean {
+  return state.selection.remainingTaskCount === 0;
+}
+
+export function requiredTaskForCore(state: SelectionCoreState, taskSlot: number): PlannedTask {
+  const task = state.compiled.graph.tasks[taskSlot];
+  if (task === undefined) throw new Error(`admission core task slot is unknown: ${taskSlot}`);
+  return task;
+}
+
+export function requiredTaskSlotForCore(state: SelectionCoreState, taskId: string): number {
+  return requiredTaskSlotForCompiled(state.compiled, taskId);
+}
+
+export function requiredScopeForCore(
+  state: SelectionCoreState,
+  scopeSlot: number
+): PlannedTaskGraph["scopes"][number] {
+  return requiredScopeForCompiled(state.compiled, scopeSlot);
+}
+
+export function requiredScopeSlotForCore(state: SelectionCoreState, scopeId: string): number {
+  const scopeSlot = state.compiled.scopeSlotById.get(scopeId);
+  if (scopeSlot === undefined) throw new Error(`admission core scope is unknown: ${scopeId}`);
+  return scopeSlot;
+}
+
+/** Public validation and catalog payloads preserve lexical duplicate occurrences. */
+export function selectionRejectionForPendingTask(
+  state: SelectionCoreState,
+  taskSlot: number
+): AdmissionSelectionRejectionReason | undefined {
+  const stage = blockerStageFor(state, taskSlot);
+  return stage === undefined
+    ? capacityRejectionFor(state, taskSlot)
+    : blockerPayloadFor(state, taskSlot, stage);
+}
+
+type PendingBlockerStage = "depends-on-pending" | "mutex-held" | "observes-pending";
+
+/** Candidate scheduling uses only indexed counters and does not materialize public payloads. */
+function blockerStageFor(
+  state: SelectionCoreState,
+  taskSlot: number
+): PendingBlockerStage | undefined {
+  const selection = state.selection;
+  if (numberFor(selection.pendingDependencies, taskSlot) > 0) return "depends-on-pending";
+  if (numberFor(selection.pendingObservations, taskSlot) > 0) return "observes-pending";
+  return numberFor(selection.heldMutexBlockers, taskSlot) > 0 ? "mutex-held" : undefined;
+}
+
+function blockerPayloadFor(
+  state: SelectionCoreState,
+  taskSlot: number,
+  stage: PendingBlockerStage
+): AdmissionSelectionRejectionReason {
+  const task = requiredTaskForCore(state, taskSlot);
+  if (stage === "depends-on-pending") {
+    return Object.freeze({
+      kind: stage,
+      taskIds: sorted(
+        task.dependsOn.filter(
+          (taskId) =>
+            statusForCore(state, requiredTaskSlotForCore(state, taskId)).kind !== "settled"
+        )
+      )
+    });
+  }
+  if (stage === "observes-pending") {
+    return Object.freeze({
+      kind: stage,
+      taskIds: sorted(
+        task.observes.filter(
+          (taskId) =>
+            statusForCore(state, requiredTaskSlotForCore(state, taskId)).kind !== "settled"
+        )
+      )
+    });
+  }
+  return Object.freeze({
+    kind: stage,
+    mutexIds: sorted(task.mutex.filter((mutexId) => isMutexHeld(state, mutexId)))
+  });
+}
+
+export function isAdmissionEligibleForPendingTask(
+  state: SelectionCoreState,
+  taskSlot: number
+): boolean {
+  return (
+    blockerStageFor(state, taskSlot) === undefined && hasCapacityForPendingTask(state, taskSlot)
+  );
+}
+
+function hasCapacityForPendingTask(state: SelectionCoreState, taskSlot: number): boolean {
+  const running = state.selection.runningTotal;
+  return (
+    scopeCapacityBlockerFor(state, taskSlot, running) === undefined &&
+    running < state.compiled.maxParallel &&
+    resourceCapacityRejectionFor(state, taskSlot) === undefined
+  );
+}
+
+function capacityRejectionFor(
+  state: SelectionCoreState,
+  taskSlot: number
+): AdmissionSelectionRejectionReason | undefined {
+  const running = state.selection.runningTotal;
+  const scope = scopeCapacityBlockerFor(state, taskSlot, running);
+  if (scope !== undefined) {
+    return Object.freeze({
+      kind: "scope-capacity-reached",
+      maxParallel: scope.maxParallel,
+      running,
+      scopeId: scope.id
+    });
+  }
+  if (running >= state.compiled.maxParallel) {
+    return Object.freeze({
+      kind: "root-capacity-reached",
+      maxParallel: state.compiled.maxParallel,
+      running
+    });
+  }
+  return resourceCapacityRejectionFor(state, taskSlot);
+}
+
+function resourceCapacityRejectionFor(
+  state: SelectionCoreState,
+  taskSlot: number
+):
+  | Extract<AdmissionSelectionRejectionReason, { readonly kind: "resource-capacity-insufficient" }>
+  | undefined {
+  const task = requiredTaskForCore(state, taskSlot);
+  const insufficient: Extract<
+    AdmissionSelectionRejectionReason,
+    { readonly kind: "resource-capacity-insufficient" }
+  >["resources"][number][] = [];
+  for (const claim of state.compiled.taskResourceClaims[taskSlot]) {
+    const capacity = state.compiled.resourceCapacityBySlot[claim.resourceSlot];
+    const inUse = numberFor(state.selection.resourceInUse, claim.resourceSlot);
+    if (capacity === undefined) {
+      throw new Error(`admission core resource slot is unknown: ${claim.resourceSlot}`);
+    }
+    if (inUse + claim.units <= capacity) continue;
+    const resourceId = state.compiled.graph.resourceCapacities[claim.resourceSlot]?.resourceId;
+    if (resourceId === undefined) {
+      throw new Error(`admission core task resource claim is missing: ${task.id}`);
+    }
+    insufficient.push(
+      Object.freeze({
+        available: capacity - inUse,
+        capacity,
+        inUse,
+        required: claim.units,
+        resourceId
+      })
+    );
+  }
+  return insufficient.length === 0
+    ? undefined
+    : Object.freeze({
+        kind: "resource-capacity-insufficient",
+        resources: Object.freeze(insufficient)
+      });
+}
+
+/** Active scope capacity is global; an activating candidate supplies one additional exact scope fact. */
+function scopeCapacityBlockerFor(
+  state: SelectionCoreState,
+  taskSlot: number,
+  running: number
+): PlannedTaskGraph["scopes"][number] | undefined {
+  let selectedScopeSlot: number | undefined = state.selection.activeScopeSlots[0];
+  if (
+    selectedScopeSlot !== undefined &&
+    requiredScopeForCore(state, selectedScopeSlot).maxParallel > running
+  ) {
+    selectedScopeSlot = undefined;
+  }
+  const taskScopeSlot = state.compiled.taskScopeSlots[taskSlot];
+  if (
+    taskScopeSlot !== undefined &&
+    isScopeInactiveForCore(state, taskScopeSlot) &&
+    state.compiled.taskActivatesScope[taskSlot] === true &&
+    requiredScopeForCore(state, taskScopeSlot).maxParallel <= running &&
+    (selectedScopeSlot === undefined ||
+      compareScopeCapacityForCompiled(state.compiled, taskScopeSlot, selectedScopeSlot) < 0)
+  ) {
+    selectedScopeSlot = taskScopeSlot;
+  }
+  return selectedScopeSlot === undefined
+    ? undefined
+    : requiredScopeForCore(state, selectedScopeSlot);
+}
+
+export function admissionCandidatesForCore(
+  state: SelectionCoreState
+): readonly AdmissionCoreSelection[] {
+  const candidates: AdmissionCoreSelection[] = [];
+  for (const [taskSlot, task] of state.compiled.graph.tasks.entries()) {
+    if (statusForCore(state, taskSlot).kind !== "pending") continue;
+    if (blockerStageFor(state, taskSlot) !== undefined) continue;
+    candidates.push(Object.freeze({ canAdmit: hasCapacityForPendingTask(state, taskSlot), task }));
+  }
+  return Object.freeze(candidates);
+}
+
+export function scopeToActivateForCore(state: SelectionCoreState, taskId: string): string | null {
+  const taskSlot = state.compiled.taskSlotsById.get(taskId);
+  if (taskSlot === undefined) return null;
+  const scopeSlot = state.compiled.taskScopeSlots[taskSlot];
+  if (scopeSlot === undefined || !isScopeInactiveForCore(state, scopeSlot)) return null;
+  return state.compiled.taskActivatesScope[taskSlot] === true
+    ? requiredScopeForCore(state, scopeSlot).id
+    : null;
+}
+
+export function activeScopesForCore(
+  state: SelectionCoreState
+): PlannedTaskGraph["scopes"][number][] {
+  return state.selection.activeScopeSlots.map((slot) => requiredScopeForCore(state, slot));
+}
+
+export function scopeLifecycleForCore(
+  state: SelectionCoreState,
+  scopeSlot: number
+): "inactive" | "active" | "closed" {
+  const scope = requiredScopeForCore(state, scopeSlot);
+  if (
+    statusForCore(state, requiredTaskSlotForCore(state, scope.terminalTaskId)).kind === "settled"
+  ) {
+    return "closed";
+  }
+  return numberFor(state.selection.activeScopes, scopeSlot) > 0 ? "active" : "inactive";
+}
+
+export function isScopeInactiveForCore(state: SelectionCoreState, scopeSlot: number): boolean {
+  return scopeLifecycleForCore(state, scopeSlot) === "inactive";
+}
+
+export function effectiveMaxParallelForCore(state: SelectionCoreState): number {
+  const constrainedScope = state.selection.activeScopeSlots[0];
+  return constrainedScope === undefined
+    ? state.compiled.maxParallel
+    : Math.min(
+        state.compiled.maxParallel,
+        requiredScopeForCore(state, constrainedScope).maxParallel
+      );
+}
+
+function isMutexHeld(state: SelectionCoreState, mutexId: string): boolean {
+  if (state.selection.legacyRunningMutexes?.includes(mutexId) === true) return true;
+  const mutexSlot = state.compiled.mutexSlotById.get(mutexId);
+  return mutexSlot !== undefined && numberFor(state.selection.mutexHolders, mutexSlot) > 0;
+}
+
+function sorted(values: readonly string[]): readonly string[] {
+  return Object.freeze([...values].sort(compareText));
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/src/project-run/task-scheduler/admission-core/selection-seed.ts

@@ -0,0 +1,252 @@
+import type { CompiledAdmissionGraph } from "./compiled-graph.ts";
+import {
+  forcedQueueFromTaskSlots,
+  freezeSelectionIndex,
+  persistentNumbersFor,
+  persistentStatuses,
+  statusForStore,
+  type AdmissionSelectionIndex,
+  type CoreTaskStatus,
+  type ForcedTaskQueue,
+  type StatusStore
+} from "./selection-index.ts";
+
+interface SeedTaskCounters {
+  readonly mutexHolders: number[];
+  readonly nonCompletedDependencies: number[];
+  readonly pendingDependencies: number[];
+  readonly pendingObservations: number[];
+  readonly remainingTaskCount: number;
+  readonly resourceInUse: number[];
+  readonly runningTotal: number;
+}
+
+/** Builds every immutable selection index from one static graph and one exact status seed. */
+export function selectionIndexForSeed(
+  compiled: CompiledAdmissionGraph,
+  statuses: readonly CoreTaskStatus[],
+  activeScopeIds: readonly string[] | undefined,
+  legacyRunningMutexes: readonly string[] | undefined
+): AdmissionSelectionIndex {
+  const persistentStatus = persistentStatuses(statuses);
+  const counters = seedTaskCounters(compiled, persistentStatus);
+  const activeScopes = seedActiveScopes(compiled, activeScopeIds);
+  return freezeSelectionIndex({
+    activeScopeSlots: activeScopeSlotsForSeed(compiled, persistentStatus, activeScopes),
+    activeScopes: persistentNumbersFor(activeScopes),
+    forcedQueue: forcedQueueForSeed(compiled, persistentStatus, counters),
+    heldMutexBlockers: persistentNumbersFor(
+      heldMutexBlockersForSeed(compiled, counters.mutexHolders, legacyRunningMutexes)
+    ),
+    legacyRunningMutexes:
+      legacyRunningMutexes === undefined ? undefined : Object.freeze([...legacyRunningMutexes]),
+    mutexHolders: persistentNumbersFor(counters.mutexHolders),
+    nonCompletedDependencies: persistentNumbersFor(counters.nonCompletedDependencies),
+    pendingDependencies: persistentNumbersFor(counters.pendingDependencies),
+    pendingObservations: persistentNumbersFor(counters.pendingObservations),
+    remainingTaskCount: counters.remainingTaskCount,
+    resourceInUse: persistentNumbersFor(counters.resourceInUse),
+    runningTotal: counters.runningTotal,
+    statuses: persistentStatus
+  });
+}
+
+/** Status/running/mutex and relation-counter seed stage. */
+function seedTaskCounters(
+  compiled: CompiledAdmissionGraph,
+  statuses: StatusStore
+): SeedTaskCounters {
+  const mutexHolders = Array.from({ length: compiled.mutexSlotById.size }, () => 0);
+  const pendingDependencies: number[] = [];
+  const nonCompletedDependencies: number[] = [];
+  const pendingObservations: number[] = [];
+  let remainingTaskCount = 0;
+  let runningTotal = 0;
+  const resourceInUse = compiled.resourceCapacityBySlot.map(() => 0);
+  for (const [taskSlot, task] of compiled.graph.tasks.entries()) {
+    const status = statusForStore(statuses, taskSlot);
+    if (status.kind === "pending" || status.kind === "running") remainingTaskCount += 1;
+    if (status.kind === "running") {
+      runningTotal += 1;
+      for (const mutexSlot of compiled.taskMutexSlots[taskSlot]) mutexHolders[mutexSlot] += 1;
+      for (const claim of compiled.taskResourceClaims[taskSlot]) {
+        resourceInUse[claim.resourceSlot] += claim.units;
+      }
+    }
+    appendDependencyCountsForSeed(
+      compiled,
+      statuses,
+      task.dependsOn,
+      pendingDependencies,
+      nonCompletedDependencies
+    );
+    pendingObservations.push(observationCountForSeed(compiled, statuses, task.observes));
+  }
+  return {
+    mutexHolders,
+    nonCompletedDependencies,
+    pendingDependencies,
+    pendingObservations,
+    remainingTaskCount,
+    resourceInUse,
+    runningTotal
+  };
+}
+
+function appendDependencyCountsForSeed(
+  compiled: CompiledAdmissionGraph,
+  statuses: StatusStore,
+  dependencyIds: readonly string[],
+  pendingDependencies: number[],
+  nonCompletedDependencies: number[]
+): void {
+  let pending = 0;
+  let nonCompleted = 0;
+  for (const dependencyId of dependencyIds) {
+    const dependency = statusForStore(
+      statuses,
+      requiredTaskSlotForCompiled(compiled, dependencyId)
+    );
+    if (dependency.kind !== "settled") pending += 1;
+    else if (dependency.settlementKind !== "completed") nonCompleted += 1;
+  }
+  pendingDependencies.push(pending);
+  nonCompletedDependencies.push(nonCompleted);
+}
+
+function observationCountForSeed(
+  compiled: CompiledAdmissionGraph,
+  statuses: StatusStore,
+  observationIds: readonly string[]
+): number {
+  let pending = 0;
+  for (const observationId of observationIds) {
+    if (
+      statusForStore(statuses, requiredTaskSlotForCompiled(compiled, observationId)).kind !==
+      "settled"
+    ) {
+      pending += 1;
+    }
+  }
+  return pending;
+}
+
+/** Legacy external mutexes and dynamic holder occurrences intentionally contribute independently. */
+function heldMutexBlockersForSeed(
+  compiled: CompiledAdmissionGraph,
+  mutexHolders: readonly number[],
+  legacyRunningMutexes: readonly string[] | undefined
+): number[] {
+  const blockers = compiled.graph.tasks.map(() => 0);
+  const legacyHeldMutexes = new Set(legacyRunningMutexes);
+  for (const [taskSlot, task] of compiled.graph.tasks.entries()) {
+    for (const [mutexOccurrence, mutexSlot] of compiled.taskMutexSlots[taskSlot].entries()) {
+      blockers[taskSlot] += mutexHolders[mutexSlot];
+      if (legacyHeldMutexes.has(task.mutex[mutexOccurrence])) blockers[taskSlot] += 1;
+    }
+  }
+  return blockers;
+}
+
+function seedActiveScopes(
+  compiled: CompiledAdmissionGraph,
+  activeScopeIds: readonly string[] | undefined
+): number[] {
+  const activeScopes = Array.from({ length: compiled.graph.scopes.length }, () => 0);
+  for (const scopeId of activeScopeIds ?? []) {
+    const scopeSlot = compiled.scopeSlotById.get(scopeId);
+    if (scopeSlot !== undefined) activeScopes[scopeSlot] = 1;
+  }
+  return activeScopes;
+}
+
+/** Active root seed stage excludes scopes whose terminal is already settled. */
+function activeScopeSlotsForSeed(
+  compiled: CompiledAdmissionGraph,
+  statuses: StatusStore,
+  activeScopes: readonly number[]
+): readonly number[] {
+  const slots = activeScopes
+    .map((active, scopeSlot) => (active > 0 ? scopeSlot : undefined))
+    .filter((scopeSlot): scopeSlot is number => scopeSlot !== undefined)
+    .filter(
+      (scopeSlot) =>
+        statusForStore(
+          statuses,
+          requiredTaskSlotForCompiled(
+            compiled,
+            requiredScopeForCompiled(compiled, scopeSlot).terminalTaskId
+          )
+        ).kind !== "settled"
+    );
+  return sortedActiveScopeSlots(compiled, slots);
+}
+
+/** Forced-frontier seed stage retains only eligible pending dependents. */
+function forcedQueueForSeed(
+  compiled: CompiledAdmissionGraph,
+  statuses: StatusStore,
+  counters: SeedTaskCounters
+): ForcedTaskQueue {
+  const forced = compiled.graph.tasks
+    .map((_, taskSlot) => taskSlot)
+    .filter(
+      (taskSlot) =>
+        statusForStore(statuses, taskSlot).kind === "pending" &&
+        counters.pendingDependencies[taskSlot] === 0 &&
+        (counters.nonCompletedDependencies[taskSlot] ?? 0) > 0
+    );
+  return forcedQueueFromTaskSlots(forced);
+}
+
+export function insertActiveScopeSlot(
+  compiled: CompiledAdmissionGraph,
+  slots: readonly number[],
+  next: number
+): readonly number[] {
+  if (slots.includes(next)) return slots;
+  return Object.freeze(sortedActiveScopeSlots(compiled, [...slots, next]));
+}
+
+export function sortedActiveScopeSlots(
+  compiled: CompiledAdmissionGraph,
+  slots: readonly number[]
+): readonly number[] {
+  return Object.freeze(
+    [...slots].sort((left, right) => compareScopeCapacityForCompiled(compiled, left, right))
+  );
+}
+
+export function compareScopeCapacityForCompiled(
+  compiled: CompiledAdmissionGraph,
+  left: number,
+  right: number
+): number {
+  const leftScope = requiredScopeForCompiled(compiled, left);
+  const rightScope = requiredScopeForCompiled(compiled, right);
+  return leftScope.maxParallel - rightScope.maxParallel || compareText(leftScope.id, rightScope.id);
+}
+
+export function requiredTaskSlotForCompiled(
+  compiled: CompiledAdmissionGraph,
+  taskId: string
+): number {
+  const taskSlot = compiled.taskSlotsById.get(taskId);
+  if (taskSlot === undefined) throw new Error(`admission core task is unknown: ${taskId}`);
+  return taskSlot;
+}
+
+export function requiredScopeForCompiled(
+  compiled: CompiledAdmissionGraph,
+  scopeSlot: number
+): CompiledAdmissionGraph["graph"]["scopes"][number] {
+  const scope = compiled.graph.scopes[scopeSlot];
+  if (scope === undefined) throw new Error(`admission core scope slot is unknown: ${scopeSlot}`);
+  return scope;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}