@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -0,0 +1,138 @@
+import type { AdmissionGraphInput } from "../../../project-definition/scheduler-policy.ts";
+import { prepareTaskGraph, type TaskGraph, type TaskScope } from "../graph.ts";
+import { compilePreparedAdmissionGraph, type CompiledAdmissionGraph } from "./compiled-graph.ts";
+
+/** Validates the exact standalone boundary before compiling the Scheduler-owned graph. */
+export function compileAdmissionGraphInput(input: AdmissionGraphInput): CompiledAdmissionGraph {
+  const data = exactRecord(input, "admission graph input", ["graph", "maxParallel"]);
+  const maxParallel = data.maxParallel;
+  if (typeof maxParallel !== "number" || !Number.isSafeInteger(maxParallel) || maxParallel <= 0) {
+    throw new TypeError("admission graph maxParallel must be a positive safe integer");
+  }
+  return compilePreparedAdmissionGraph(
+    prepareTaskGraph(taskGraphFromSchedulerSnapshot(data.graph), maxParallel),
+    maxParallel
+  );
+}
+
+function taskGraphFromSchedulerSnapshot(value: unknown): TaskGraph {
+  const graph = exactRecord(value, "admission graph", ["resourceCapacities", "scopes", "tasks"]);
+  const rawTasks = requiredArray(graph.tasks, "admission graph tasks");
+  const rawScopes = requiredArray(graph.scopes, "admission graph scopes");
+  const tasks = rawTasks.map(taskFromInput);
+  const scopes = rawScopes.map(scopeFromInput);
+  return Object.freeze({
+    resourceCapacities: resourceMappingFromInput(
+      graph.resourceCapacities,
+      "admission graph resourceCapacities"
+    ),
+    scopes: Object.freeze(scopes),
+    tasks: Object.freeze(tasks)
+  });
+}
+
+function taskFromInput(candidate: unknown, index: number): TaskGraph["tasks"][number] {
+  const label = `admission graph tasks[${index}]`;
+  const task = exactRecord(candidate, label, [
+    "admissionPriority",
+    "dependsOn",
+    "mutex",
+    "observes",
+    "resourceClaims",
+    "scopeId",
+    "taskId"
+  ]);
+  if (task.scopeId !== null && typeof task.scopeId !== "string") {
+    throw new TypeError(`${label}.scopeId must be a string or null`);
+  }
+  return Object.freeze({
+    admissionPriority: requiredNumber(task.admissionPriority, `${label}.admissionPriority`),
+    dependsOn: stringArray(task.dependsOn, `${label}.dependsOn`),
+    id: requiredString(task.taskId, `${label}.taskId`),
+    mutex: stringArray(task.mutex, `${label}.mutex`),
+    observes: stringArray(task.observes, `${label}.observes`),
+    resourceClaims: resourceMappingFromInput(task.resourceClaims, `${label}.resourceClaims`),
+    ...(task.scopeId === null ? {} : { scopeId: requiredString(task.scopeId, `${label}.scopeId`) })
+  });
+}
+
+function resourceMappingFromInput(value: unknown, label: string): Readonly<Record<string, number>> {
+  const items = requiredArray(value, label);
+  const entries: [string, number][] = [];
+  const ids = new Set<string>();
+  for (const [index, candidate] of items.entries()) {
+    const itemLabel = `${label}[${index}]`;
+    const item = exactRecord(candidate, itemLabel, ["resourceId", "units"]);
+    const resourceId = requiredString(item.resourceId, `${itemLabel}.resourceId`);
+    if (ids.has(resourceId)) throw new TypeError(`${label} repeats resource ${resourceId}`);
+    ids.add(resourceId);
+    entries.push([resourceId, requiredNumber(item.units, `${itemLabel}.units`)]);
+  }
+  return Object.freeze(Object.fromEntries(entries));
+}
+
+function scopeFromInput(candidate: unknown, index: number): TaskScope {
+  const label = `admission graph scopes[${index}]`;
+  const scope = exactRecord(candidate, label, [
+    "activationTaskIds",
+    "id",
+    "maxParallel",
+    "terminalTaskId"
+  ]);
+  return Object.freeze({
+    activationTaskIds: stringArray(scope.activationTaskIds, `${label}.activationTaskIds`),
+    id: requiredString(scope.id, `${label}.id`),
+    maxParallel: requiredNumber(scope.maxParallel, `${label}.maxParallel`),
+    terminalTaskId: requiredString(scope.terminalTaskId, `${label}.terminalTaskId`)
+  });
+}
+
+function exactRecord(
+  value: unknown,
+  label: string,
+  expectedKeys: readonly string[]
+): Readonly<Record<string, unknown>> {
+  if (!isPlainRecord(value)) throw new TypeError(`${label} must be a plain object`);
+  if (
+    Reflect.getPrototypeOf(value) !== Object.prototype &&
+    Reflect.getPrototypeOf(value) !== null
+  ) {
+    throw new TypeError(`${label} must be a plain object`);
+  }
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== expectedKeys.length ||
+    keys.some((key) => typeof key !== "string" || !expectedKeys.includes(key))
+  ) {
+    throw new TypeError(`${label} must have exactly: ${expectedKeys.join(", ")}`);
+  }
+  return value;
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function requiredArray(value: unknown, label: string): readonly unknown[] {
+  if (!Array.isArray(value)) throw new TypeError(`${label} must be an array`);
+  return value;
+}
+
+function requiredNumber(value: unknown, label: string): number {
+  if (typeof value !== "number") throw new TypeError(`${label} must be a number`);
+  return value;
+}
+
+function requiredString(value: unknown, label: string): string {
+  if (typeof value !== "string") throw new TypeError(`${label} must be a string`);
+  return value;
+}
+
+function stringArray(value: unknown, label: string): readonly string[] {
+  const strings: string[] = [];
+  for (const item of requiredArray(value, label)) {
+    if (typeof item !== "string") throw new TypeError(`${label} must contain only strings`);
+    strings.push(item);
+  }
+  return Object.freeze(strings);
+}

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

@@ -0,0 +1,164 @@
+import type {
+  AdmissionCatalog,
+  AdmissionInspection,
+  AdmissionSelectionRejectionReason,
+  AdmissionSettlementOutcome
+} from "../../../project-definition/scheduler-policy.ts";
+import type { PlannedTask, PlannedTaskGraph } from "../graph.ts";
+import {
+  activeScopesForCore,
+  effectiveMaxParallelForCore,
+  isAdmissionEligibleForPendingTask,
+  requiredScopeSlotForCore,
+  requiredTaskForCore,
+  scopeLifecycleForCore,
+  selectionRejectionForPendingTask,
+  statusForCore
+} from "./selection-query.ts";
+import { numberFor } from "./selection-index.ts";
+import type { AdmissionCoreState } from "./selection.ts";
+import type { SchedulerSettlementKind } from "../scheduler-decision-model.ts";
+
+/** Materializes the public catalog only when the public getter reads it. */
+export function catalogForCore(state: AdmissionCoreState): AdmissionCatalog {
+  const selectableTaskIds: string[] = [];
+  const nonSelectableTasks: { reason: AdmissionSelectionRejectionReason; taskId: string }[] = [];
+  for (const taskSlot of state.compiled.taskSlotsInPublicOrder) {
+    if (statusForCore(state, taskSlot).kind !== "pending") continue;
+    const reason = selectionRejectionForPendingTask(state, taskSlot);
+    const taskId = requiredTaskForCore(state, taskSlot).id;
+    if (reason === undefined) selectableTaskIds.push(taskId);
+    else nonSelectableTasks.push(Object.freeze({ reason, taskId }));
+  }
+  return Object.freeze({
+    nonSelectableTasks: Object.freeze(nonSelectableTasks),
+    selectableTaskIds: Object.freeze(selectableTaskIds)
+  });
+}
+
+export function inspectionForCore(state: AdmissionCoreState): AdmissionInspection {
+  const runningTaskIds: string[] = [];
+  const settledTasks: { outcome: AdmissionSettlementOutcome; taskId: string }[] = [];
+  for (const taskSlot of state.compiled.taskSlotsInPublicOrder) {
+    const task = requiredTaskForCore(state, taskSlot);
+    const status = statusForCore(state, taskSlot);
+    if (status.kind === "running") runningTaskIds.push(task.id);
+    if (status.kind === "settled") {
+      const outcome = publicOutcomeForSettlement(status.settlementKind);
+      if (outcome !== undefined) settledTasks.push(Object.freeze({ outcome, taskId: task.id }));
+    }
+  }
+  const hasSelectablePending = state.compiled.graph.tasks.some(
+    (_, taskSlot) =>
+      statusForCore(state, taskSlot).kind === "pending" &&
+      isAdmissionEligibleForPendingTask(state, taskSlot)
+  );
+  return Object.freeze({
+    capacity: Object.freeze({
+      effectiveMaxParallel: effectiveMaxParallelForCore(state),
+      maxParallel: state.compiled.maxParallel,
+      running: state.selection.runningTotal
+    }),
+    nextBoundary: nextBoundaryFor(hasSelectablePending, state.selection.runningTotal),
+    resources: resourceOccupancyForCore(state),
+    runningTaskIds: Object.freeze(runningTaskIds),
+    scopes: Object.freeze(
+      [...state.compiled.graph.scopes]
+        .sort((left, right) => compareText(left.id, right.id))
+        .map((scope) =>
+          Object.freeze({
+            lifecycle: scopeLifecycleForCore(state, requiredScopeSlotForCore(state, scope.id)),
+            scopeId: scope.id
+          })
+        )
+    ),
+    settledTasks: Object.freeze(settledTasks)
+  });
+}
+
+/** Scheduler-only projection retained for policy choice and diagnostics, not a second transition model. */
+export function schedulerInspectionForCore(state: AdmissionCoreState): Readonly<{
+  readonly activeScopeIds: readonly string[];
+  readonly effectiveMaxParallel: number;
+  readonly graph: PlannedTaskGraph;
+  readonly maxParallel: number;
+  readonly pendingTasks: readonly PlannedTask[];
+  readonly runningMutexes: readonly string[];
+  readonly resources: AdmissionInspection["resources"];
+  readonly runningTaskIds: readonly string[];
+  readonly settledTasks: readonly Readonly<{
+    readonly kind: SchedulerSettlementKind;
+    readonly taskId: string;
+  }>[];
+}> {
+  const pendingTasks: PlannedTask[] = [];
+  const runningTaskIds: string[] = [];
+  const runningMutexes = new Set<string>();
+  const settledTasks: { kind: SchedulerSettlementKind; taskId: string }[] = [];
+  for (const [taskSlot, task] of state.compiled.graph.tasks.entries()) {
+    const status = statusForCore(state, taskSlot);
+    if (status.kind === "pending") pendingTasks.push(task);
+    if (status.kind === "running") {
+      runningTaskIds.push(task.id);
+      for (const mutexId of task.mutex) runningMutexes.add(mutexId);
+    }
+    if (status.kind === "settled") {
+      settledTasks.push({ kind: status.settlementKind, taskId: task.id });
+    }
+  }
+  return Object.freeze({
+    activeScopeIds: Object.freeze(activeScopesForCore(state).map((scope) => scope.id)),
+    effectiveMaxParallel: effectiveMaxParallelForCore(state),
+    graph: state.compiled.graph,
+    maxParallel: state.compiled.maxParallel,
+    pendingTasks: Object.freeze(pendingTasks),
+    resources: resourceOccupancyForCore(state),
+    runningMutexes: Object.freeze([...runningMutexes]),
+    runningTaskIds: Object.freeze(runningTaskIds),
+    settledTasks: Object.freeze(settledTasks.map((task) => Object.freeze(task)))
+  });
+}
+
+function resourceOccupancyForCore(state: AdmissionCoreState): AdmissionInspection["resources"] {
+  return Object.freeze(
+    state.compiled.graph.resourceCapacities.map(({ resourceId, units }, resourceSlot) => {
+      const inUse = numberFor(state.selection.resourceInUse, resourceSlot);
+      return Object.freeze({
+        available: units - inUse,
+        capacity: units,
+        inUse,
+        resourceId
+      });
+    })
+  );
+}
+
+function nextBoundaryFor(
+  hasSelectablePending: boolean,
+  runningTaskCount: number
+): "select" | "wait" | "complete" {
+  if (hasSelectablePending) return "select";
+  if (runningTaskCount > 0) return "wait";
+  return "complete";
+}
+
+function publicOutcomeForSettlement(
+  settlementKind: SchedulerSettlementKind
+): AdmissionSettlementOutcome | undefined {
+  switch (settlementKind) {
+    case "completed":
+      return "satisfied";
+    case "prerequisite-unsatisfied":
+    case "failed":
+      return "unsatisfied";
+    case "blocked":
+    case "cancelled-before-start":
+      return undefined;
+  }
+}
+
+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-index.ts

@@ -0,0 +1,165 @@
+import { List } from "immutable";
+
+import type { SchedulerSettlementKind } from "../scheduler-decision-model.ts";
+
+export type CoreTaskStatus =
+  | Readonly<{ readonly kind: "pending" }>
+  /** Only used while adapting private partial SchedulerSnapshot test inputs. */
+  | Readonly<{ readonly kind: "absent" }>
+  | Readonly<{ readonly kind: "running" }>
+  | Readonly<{ readonly kind: "settled"; readonly settlementKind: SchedulerSettlementKind }>;
+
+export const PENDING: CoreTaskStatus = Object.freeze({ kind: "pending" });
+export const ABSENT: CoreTaskStatus = Object.freeze({ kind: "absent" });
+
+/** Immutable.List is the persistent indexed backing for every dense selection counter. */
+export type PersistentIndexedStore<T> = Readonly<{
+  readonly values: List<T>;
+}>;
+
+export type NumberStore = PersistentIndexedStore<number>;
+export type StatusStore = PersistentIndexedStore<CoreTaskStatus>;
+
+/** Persistent leftist max-heap: task slots are the canonical forced-effect priority. */
+export type ForcedTaskQueue =
+  | undefined
+  | Readonly<{
+      readonly left: ForcedTaskQueue;
+      readonly rank: number;
+      readonly right: ForcedTaskQueue;
+      readonly taskSlot: number;
+    }>;
+
+/** Private dynamic index shared by the seed, delta reducer and read-only query owners. */
+export interface AdmissionSelectionIndex {
+  readonly activeScopeSlots: readonly number[];
+  readonly activeScopes: NumberStore;
+  readonly forcedQueue: ForcedTaskQueue;
+  readonly legacyRunningMutexes: readonly string[] | undefined;
+  readonly mutexHolders: NumberStore;
+  /** Per-task reverse-mutex occurrence count; candidate sieving never builds mutex payloads. */
+  readonly heldMutexBlockers: NumberStore;
+  readonly nonCompletedDependencies: NumberStore;
+  readonly pendingObservations: NumberStore;
+  readonly pendingDependencies: NumberStore;
+  readonly remainingTaskCount: number;
+  readonly resourceInUse: NumberStore;
+  readonly runningTotal: number;
+  readonly statuses: StatusStore;
+}
+
+export function persistentStatuses(values: readonly CoreTaskStatus[]): StatusStore {
+  return Object.freeze({ values: List(values) });
+}
+
+export function persistentNumbersFor(values: readonly number[]): NumberStore {
+  return Object.freeze({ values: List(values) });
+}
+
+export function statusForSelection(
+  selection: AdmissionSelectionIndex,
+  taskSlot: number
+): CoreTaskStatus {
+  return statusForStore(selection.statuses, taskSlot);
+}
+
+export function statusForStore(store: StatusStore, taskSlot: number): CoreTaskStatus {
+  const value = store.values.get(taskSlot);
+  if (value === undefined) throw new Error(`admission core task slot is unknown: ${taskSlot}`);
+  return value;
+}
+
+export function withStatusAt(
+  store: StatusStore,
+  taskSlot: number,
+  value: CoreTaskStatus
+): StatusStore {
+  if (taskSlot < 0 || taskSlot >= store.values.size)
+    throw new Error(`admission core task slot is unknown: ${taskSlot}`);
+  return Object.freeze({ values: store.values.set(taskSlot, value) });
+}
+
+export function numberFor(store: NumberStore, slot: number): number {
+  const value = store.values.get(slot);
+  if (value === undefined) throw new Error(`admission core index slot is unknown: ${slot}`);
+  return value;
+}
+
+/** Applies all occurrence deltas through one new persistent List value. */
+export function withNumberDeltas(
+  store: NumberStore,
+  deltas: readonly (readonly [number, number])[]
+): NumberStore {
+  if (deltas.length === 0) return store;
+  const aggregated = new Map<number, number>();
+  for (const [slot, delta] of deltas) aggregated.set(slot, (aggregated.get(slot) ?? 0) + delta);
+  let values = store.values;
+  for (const [slot, delta] of aggregated) {
+    const current = values.get(slot);
+    if (current === undefined) throw new Error(`admission core index slot is unknown: ${slot}`);
+    values = values.set(slot, current + delta);
+  }
+  return Object.freeze({ values });
+}
+
+export function forcedTaskSlotFor(selection: AdmissionSelectionIndex): number | undefined {
+  return selection.forcedQueue?.taskSlot;
+}
+
+/** Removes just the persistent heap root; all retained branches remain shared. */
+export function withoutForcedTask(selection: AdmissionSelectionIndex): AdmissionSelectionIndex {
+  const root = selection.forcedQueue;
+  if (root === undefined) return selection;
+  return freezeSelectionIndex({
+    ...selection,
+    forcedQueue: mergeForcedTaskQueues(root.left, root.right)
+  });
+}
+
+export function forcedQueueFromTaskSlots(taskSlots: readonly number[]): ForcedTaskQueue {
+  let queue: ForcedTaskQueue;
+  for (const taskSlot of taskSlots) queue = forcedQueueWithTask(queue, taskSlot);
+  return queue;
+}
+
+/** Additions are newly-ready reverse dependents, so no extant frontier is copied or sorted. */
+export function enqueueForcedTaskSlots(
+  existing: ForcedTaskQueue,
+  additions: ReadonlySet<number>
+): ForcedTaskQueue {
+  let queue = existing;
+  for (const taskSlot of additions) queue = forcedQueueWithTask(queue, taskSlot);
+  return queue;
+}
+
+export function freezeSelectionIndex(selection: AdmissionSelectionIndex): AdmissionSelectionIndex {
+  return Object.freeze(selection);
+}
+
+function forcedQueueRank(queue: ForcedTaskQueue): number {
+  return queue?.rank ?? 0;
+}
+
+/** Merges by task slot; only the right spine is copied and retained branches stay shared. */
+function mergeForcedTaskQueues(left: ForcedTaskQueue, right: ForcedTaskQueue): ForcedTaskQueue {
+  if (left === undefined) return right;
+  if (right === undefined) return left;
+  if (left.taskSlot < right.taskSlot) return mergeForcedTaskQueues(right, left);
+  const mergedRight = mergeForcedTaskQueues(left.right, right);
+  const nextLeft =
+    forcedQueueRank(left.left) >= forcedQueueRank(mergedRight) ? left.left : mergedRight;
+  const nextRight = nextLeft === left.left ? mergedRight : left.left;
+  return Object.freeze({
+    left: nextLeft,
+    rank: forcedQueueRank(nextRight) + 1,
+    right: nextRight,
+    taskSlot: left.taskSlot
+  });
+}
+
+function forcedQueueWithTask(queue: ForcedTaskQueue, taskSlot: number): ForcedTaskQueue {
+  return mergeForcedTaskQueues(
+    queue,
+    Object.freeze({ left: undefined, rank: 1, right: undefined, taskSlot })
+  );
+}