@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -0,0 +1,236 @@
+import type { CompiledAdmissionGraph } from "./compiled-graph.ts";
+import {
+  enqueueForcedTaskSlots,
+  freezeSelectionIndex,
+  numberFor,
+  statusForSelection,
+  statusForStore,
+  withNumberDeltas,
+  withStatusAt,
+  type AdmissionSelectionIndex,
+  type CoreTaskStatus,
+  type ForcedTaskQueue,
+  type NumberStore,
+  type StatusStore
+} from "./selection-index.ts";
+import { insertActiveScopeSlot } from "./selection-seed.ts";
+
+interface MutableTransitionFacts {
+  readonly activatedScopeSlot: number | undefined;
+  activeScopeSlots: readonly number[];
+  activeScopes: NumberStore;
+  forcedQueue: ForcedTaskQueue;
+  heldMutexBlockers: NumberStore;
+  mutexHolders: NumberStore;
+  nonCompletedDependencies: NumberStore;
+  pendingDependencies: NumberStore;
+  pendingObservations: NumberStore;
+  readonly previous: CoreTaskStatus;
+  remainingTaskCount: number;
+  resourceInUse: NumberStore;
+  runningTotal: number;
+  readonly status: CoreTaskStatus;
+  statuses: StatusStore;
+  readonly taskSlot: number;
+}
+
+/** Applies one status event through staged persistent index deltas. */
+export function transitionIndexedSelection(
+  compiled: CompiledAdmissionGraph,
+  selection: AdmissionSelectionIndex,
+  taskSlot: number,
+  status: CoreTaskStatus,
+  activatedScopeSlot: number | undefined
+): AdmissionSelectionIndex {
+  const facts = initialTransitionFacts(selection, taskSlot, status, activatedScopeSlot);
+  applyRunningOccupancyDelta(compiled, facts);
+  applySettlementRelationDelta(compiled, facts);
+  applyScopeLifecycleDelta(compiled, facts);
+  return freezeSelectionIndex({
+    activeScopeSlots: facts.activeScopeSlots,
+    activeScopes: facts.activeScopes,
+    forcedQueue: facts.forcedQueue,
+    heldMutexBlockers: facts.heldMutexBlockers,
+    legacyRunningMutexes: selection.legacyRunningMutexes,
+    mutexHolders: facts.mutexHolders,
+    nonCompletedDependencies: facts.nonCompletedDependencies,
+    pendingDependencies: facts.pendingDependencies,
+    pendingObservations: facts.pendingObservations,
+    remainingTaskCount: facts.remainingTaskCount,
+    resourceInUse: facts.resourceInUse,
+    runningTotal: facts.runningTotal,
+    statuses: facts.statuses
+  });
+}
+
+function initialTransitionFacts(
+  selection: AdmissionSelectionIndex,
+  taskSlot: number,
+  status: CoreTaskStatus,
+  activatedScopeSlot: number | undefined
+): MutableTransitionFacts {
+  return {
+    activatedScopeSlot,
+    activeScopeSlots: selection.activeScopeSlots,
+    activeScopes: selection.activeScopes,
+    forcedQueue: selection.forcedQueue,
+    heldMutexBlockers: selection.heldMutexBlockers,
+    mutexHolders: selection.mutexHolders,
+    nonCompletedDependencies: selection.nonCompletedDependencies,
+    pendingDependencies: selection.pendingDependencies,
+    pendingObservations: selection.pendingObservations,
+    previous: statusForSelection(selection, taskSlot),
+    remainingTaskCount: selection.remainingTaskCount,
+    resourceInUse: selection.resourceInUse,
+    runningTotal: selection.runningTotal,
+    status,
+    statuses: withStatusAt(selection.statuses, taskSlot, status),
+    taskSlot
+  };
+}
+
+/** Running admission/settlement changes the global count and owned constraint occupancy. */
+function applyRunningOccupancyDelta(
+  compiled: CompiledAdmissionGraph,
+  facts: MutableTransitionFacts
+): void {
+  const { previous, status, taskSlot } = facts;
+  if (previous.kind === "pending" && status.kind === "running") {
+    facts.runningTotal += 1;
+    facts.mutexHolders = withMutexHolderDelta(compiled, facts.mutexHolders, taskSlot, 1);
+    facts.heldMutexBlockers = withMutexBlockerDelta(compiled, facts.heldMutexBlockers, taskSlot, 1);
+    facts.resourceInUse = withResourceClaimDelta(compiled, facts.resourceInUse, taskSlot, 1);
+  } else if (previous.kind === "running" && status.kind === "settled") {
+    facts.runningTotal -= 1;
+    facts.remainingTaskCount -= 1;
+    facts.mutexHolders = withMutexHolderDelta(compiled, facts.mutexHolders, taskSlot, -1);
+    facts.heldMutexBlockers = withMutexBlockerDelta(
+      compiled,
+      facts.heldMutexBlockers,
+      taskSlot,
+      -1
+    );
+    facts.resourceInUse = withResourceClaimDelta(compiled, facts.resourceInUse, taskSlot, -1);
+  } else if (previous.kind === "pending" && status.kind === "settled") {
+    facts.remainingTaskCount -= 1;
+  }
+}
+
+function withResourceClaimDelta(
+  compiled: CompiledAdmissionGraph,
+  resourceInUse: NumberStore,
+  taskSlot: number,
+  direction: 1 | -1
+): NumberStore {
+  return withNumberDeltas(
+    resourceInUse,
+    compiled.taskResourceClaims[taskSlot].map(
+      ({ resourceSlot, units }) => [resourceSlot, direction * units] as const
+    )
+  );
+}
+
+function withMutexHolderDelta(
+  compiled: CompiledAdmissionGraph,
+  mutexHolders: NumberStore,
+  taskSlot: number,
+  delta: 1 | -1
+): NumberStore {
+  return withNumberDeltas(
+    mutexHolders,
+    compiled.taskMutexSlots[taskSlot].map((mutexSlot) => [mutexSlot, delta] as const)
+  );
+}
+
+function withMutexBlockerDelta(
+  compiled: CompiledAdmissionGraph,
+  blockers: NumberStore,
+  taskSlot: number,
+  delta: 1 | -1
+): NumberStore {
+  return withNumberDeltas(blockers, mutexBlockerDeltasFor(compiled, taskSlot, delta));
+}
+
+function mutexBlockerDeltasFor(
+  compiled: CompiledAdmissionGraph,
+  taskSlot: number,
+  delta: 1 | -1
+): readonly (readonly [number, number])[] {
+  const deltas: [number, number][] = [];
+  for (const mutexSlot of compiled.taskMutexSlots[taskSlot]) {
+    for (const blockedTaskSlot of compiled.relationIndexes.reverseMutexOccurrences[mutexSlot] ??
+      []) {
+      deltas.push([blockedTaskSlot, delta]);
+    }
+  }
+  return deltas;
+}
+
+/** Settlement changes only the changed task's relation reverse fanout and forced frontier. */
+function applySettlementRelationDelta(
+  compiled: CompiledAdmissionGraph,
+  facts: MutableTransitionFacts
+): void {
+  const { previous, status, taskSlot } = facts;
+  if (previous.kind === "settled" || status.kind !== "settled") return;
+  const reverseDependencies = compiled.relationIndexes.reverseDependencies[taskSlot];
+  facts.pendingDependencies = withNumberDeltas(
+    facts.pendingDependencies,
+    reverseDependencies.map((dependentSlot) => [dependentSlot, -1] as const)
+  );
+  if (status.settlementKind !== "completed") {
+    facts.nonCompletedDependencies = withNumberDeltas(
+      facts.nonCompletedDependencies,
+      reverseDependencies.map((dependentSlot) => [dependentSlot, 1] as const)
+    );
+  }
+  facts.pendingObservations = withNumberDeltas(
+    facts.pendingObservations,
+    compiled.relationIndexes.reverseObservations[taskSlot].map(
+      (observerSlot) => [observerSlot, -1] as const
+    )
+  );
+  facts.forcedQueue = enqueueForcedTaskSlots(
+    facts.forcedQueue,
+    newlyForcedTaskSlots(facts, reverseDependencies)
+  );
+}
+
+function newlyForcedTaskSlots(
+  facts: MutableTransitionFacts,
+  reverseDependencies: readonly number[]
+): ReadonlySet<number> {
+  const readyForced = new Set<number>();
+  for (const dependentSlot of reverseDependencies) {
+    if (
+      statusForStore(facts.statuses, dependentSlot).kind === "pending" &&
+      numberFor(facts.pendingDependencies, dependentSlot) === 0 &&
+      numberFor(facts.nonCompletedDependencies, dependentSlot) > 0
+    ) {
+      readyForced.add(dependentSlot);
+    }
+  }
+  return readyForced;
+}
+
+/** Activation happens before terminal close, preserving the canonical scope lifecycle order. */
+function applyScopeLifecycleDelta(
+  compiled: CompiledAdmissionGraph,
+  facts: MutableTransitionFacts
+): void {
+  const { activatedScopeSlot, previous, status, taskSlot } = facts;
+  if (activatedScopeSlot !== undefined && numberFor(facts.activeScopes, activatedScopeSlot) === 0) {
+    facts.activeScopes = withNumberDeltas(facts.activeScopes, [[activatedScopeSlot, 1]]);
+    facts.activeScopeSlots = insertActiveScopeSlot(
+      compiled,
+      facts.activeScopeSlots,
+      activatedScopeSlot
+    );
+  }
+  if (previous.kind === "settled" || status.kind !== "settled") return;
+  for (const scopeSlot of compiled.scopeSlotsByTerminalTaskSlot[taskSlot]) {
+    facts.activeScopeSlots = Object.freeze(
+      facts.activeScopeSlots.filter((candidate) => candidate !== scopeSlot)
+    );
+  }
+}

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

@@ -0,0 +1,140 @@
+import type { CompiledAdmissionGraph } from "./compiled-graph.ts";
+import {
+  ABSENT,
+  PENDING,
+  withoutForcedTask,
+  forcedTaskSlotFor,
+  type AdmissionSelectionIndex,
+  type CoreTaskStatus
+} from "./selection-index.ts";
+import { isScopeInactiveForCore } from "./selection-query.ts";
+import { selectionIndexForSeed } from "./selection-seed.ts";
+import { transitionIndexedSelection } from "./selection-transition.ts";
+import type { SchedulerSettlementKind, SchedulerSnapshot } from "../scheduler-decision-model.ts";
+
+/** Private immutable core passed among Scheduler decision, policy and effect owners. */
+export interface AdmissionCoreState {
+  readonly compiled: CompiledAdmissionGraph;
+  /** Selection representation remains private to this lifecycle module family. */
+  readonly selection: AdmissionSelectionIndex;
+}
+
+/** Starts from the canonical all-pending selection seed. */
+export function createInitialAdmissionCoreState(
+  compiled: CompiledAdmissionGraph
+): AdmissionCoreState {
+  return freezeCoreState(
+    compiled,
+    selectionIndexForSeed(
+      compiled,
+      compiled.graph.tasks.map(() => PENDING),
+      undefined,
+      undefined
+    )
+  );
+}
+
+/** Seeds from a shell snapshot without exposing a mutable shell view. */
+export function createAdmissionCoreFromSchedulerSnapshot(
+  compiled: CompiledAdmissionGraph,
+  snapshot: SchedulerSnapshot
+): AdmissionCoreState {
+  const statuses = statusesForSchedulerSnapshot(compiled, snapshot);
+  return freezeCoreState(
+    compiled,
+    selectionIndexForSeed(compiled, statuses, snapshot.activeScopeIds, snapshot.runningMutexes)
+  );
+}
+
+/** Produces an immutable successor for a validated pending-to-running admission. */
+export function admitTaskForCore(state: AdmissionCoreState, taskSlot: number): AdmissionCoreState {
+  const scopeSlot = state.compiled.taskScopeSlots[taskSlot];
+  const activatedScopeSlot =
+    scopeSlot !== undefined &&
+    isScopeInactiveForCore(state, scopeSlot) &&
+    state.compiled.taskActivatesScope[taskSlot] === true
+      ? scopeSlot
+      : undefined;
+  return transitionState(state, taskSlot, Object.freeze({ kind: "running" }), activatedScopeSlot);
+}
+
+/** Produces an immutable successor for one already-validated settlement event. */
+export function settleTaskForCore(
+  state: AdmissionCoreState,
+  taskSlot: number,
+  settlementKind: SchedulerSettlementKind
+): AdmissionCoreState {
+  return transitionState(
+    state,
+    taskSlot,
+    Object.freeze({ kind: "settled", settlementKind }),
+    undefined
+  );
+}
+
+/** Pops the forced max-heap before recording its canonical blocked settlement. */
+export function settleForcedTaskForCore(
+  state: AdmissionCoreState,
+  taskSlot: number
+): AdmissionCoreState {
+  return settleTaskForCore(
+    freezeCoreState(state.compiled, withoutForcedTask(state.selection)),
+    taskSlot,
+    "blocked"
+  );
+}
+
+export function nextForcedTaskForCore(state: AdmissionCoreState): number | undefined {
+  return forcedTaskSlotFor(state.selection);
+}
+
+function statusesForSchedulerSnapshot(
+  compiled: CompiledAdmissionGraph,
+  snapshot: SchedulerSnapshot
+): CoreTaskStatus[] {
+  const statuses = compiled.graph.tasks.map(() => PENDING);
+  const presentTaskIds = new Set([
+    ...snapshot.pendingTaskIds,
+    ...snapshot.runningTaskIds,
+    ...snapshot.settledTasks.map((task) => task.taskId)
+  ]);
+  for (const [slot, task] of compiled.graph.tasks.entries()) {
+    if (!presentTaskIds.has(task.id)) statuses[slot] = ABSENT;
+  }
+  for (const taskId of snapshot.runningTaskIds) {
+    const slot = compiled.taskSlotsById.get(taskId);
+    if (slot !== undefined) statuses[slot] = Object.freeze({ kind: "running" });
+  }
+  for (const settled of snapshot.settledTasks) {
+    const slot = compiled.taskSlotsById.get(settled.taskId);
+    if (slot !== undefined) {
+      statuses[slot] = Object.freeze({ kind: "settled", settlementKind: settled.kind });
+    }
+  }
+  return statuses;
+}
+
+function transitionState(
+  state: AdmissionCoreState,
+  taskSlot: number,
+  status: CoreTaskStatus,
+  activatedScopeSlot: number | undefined
+): AdmissionCoreState {
+  return freezeCoreState(
+    state.compiled,
+    transitionIndexedSelection(
+      state.compiled,
+      state.selection,
+      taskSlot,
+      status,
+      activatedScopeSlot
+    )
+  );
+}
+
+function freezeCoreState(
+  compiled: CompiledAdmissionGraph,
+  selection: AdmissionSelectionIndex
+): AdmissionCoreState {
+  return Object.freeze({ compiled, selection });
+}

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

@@ -0,0 +1,177 @@
+import type {
+  AdmissionCatalog,
+  AdmissionInspection,
+  AdmissionSelectionValidation
+} from "../../../project-definition/scheduler-policy.ts";
+import {
+  admissionStateForCore,
+  cancelPendingAdmissionCore,
+  reconcileAdmissionCore,
+  selectAdmissionCore,
+  settleAdmissionCore,
+  settleRunningAdmissionCore,
+  type AdmissionCoreEffect,
+  type AdmissionCoreState,
+  type AdmissionCoreTransition
+} from "./core.ts";
+
+export type AdmissionTraceAction =
+  | Readonly<{ readonly kind: "select"; readonly taskId: string }>
+  | Readonly<{
+      readonly kind: "settle";
+      readonly outcome: "satisfied" | "unsatisfied";
+      readonly taskId: string;
+    }>
+  | Readonly<{
+      readonly kind: "settle-running";
+      readonly settlementKind: "completed" | "failed" | "prerequisite-unsatisfied";
+      readonly taskId: string;
+    }>
+  | Readonly<{ readonly kind: "cancel-pending" }>
+  | Readonly<{ readonly kind: "reconcile" }>;
+
+export interface AdmissionCoreTraceProjection {
+  readonly catalog: AdmissionCatalog;
+  readonly inspection: AdmissionInspection;
+  readonly validation: readonly Readonly<{
+    readonly taskId: string;
+    readonly value: AdmissionSelectionValidation;
+  }>[];
+}
+
+export interface AdmissionCoreTraceStep {
+  readonly action: AdmissionTraceAction;
+  /** The normalized public state after each matching canonical effect. */
+  readonly effectProjections: readonly AdmissionCoreTraceProjection[];
+  readonly effects: readonly AdmissionCoreEffect[];
+  readonly post: AdmissionCoreTraceProjection;
+  readonly pre: AdmissionCoreTraceProjection;
+  readonly result: Readonly<{ readonly accepted: boolean; readonly reasonKind: string | null }>;
+}
+
+interface AppliedTraceAction {
+  readonly accepted: boolean;
+  readonly effectStates: readonly AdmissionCoreState[];
+  readonly effects: readonly AdmissionCoreEffect[];
+  readonly reasonKind: string | null;
+  readonly state: AdmissionCoreState;
+}
+
+type AdmissionCoreActionResult =
+  | Readonly<{ readonly accepted: true; readonly transition: AdmissionCoreTransition }>
+  | Readonly<{ readonly accepted: false; readonly reason: Readonly<{ readonly kind: string }> }>;
+
+/**
+ * Private deterministic oracle: it invokes the shared reducer and only normalizes
+ * its public projection. It never recreates legality or exposes the effect stream.
+ */
+export function traceAdmissionCore(
+  seed: AdmissionCoreState,
+  actions: readonly AdmissionTraceAction[]
+): readonly AdmissionCoreTraceStep[] {
+  let state = seed;
+  const taskIds = state.compiled.taskIdsInPublicOrder;
+  const steps: AdmissionCoreTraceStep[] = [];
+  for (const action of actions) {
+    const pre = projectionFor(state, taskIds);
+    const applied = applyTraceAction(state, action);
+    state = applied.state;
+    steps.push(
+      Object.freeze({
+        action: Object.freeze({ ...action }),
+        effectProjections: Object.freeze(
+          applied.effectStates.map((effectState) => projectionFor(effectState, taskIds))
+        ),
+        effects: Object.freeze([...applied.effects]),
+        post: projectionFor(state, taskIds),
+        pre,
+        result: Object.freeze({ accepted: applied.accepted, reasonKind: applied.reasonKind })
+      })
+    );
+  }
+  return Object.freeze(steps);
+}
+
+function applyTraceAction(
+  state: AdmissionCoreState,
+  action: AdmissionTraceAction
+): AppliedTraceAction {
+  switch (action.kind) {
+    case "select":
+      return traceCoreActionResult(state, selectAdmissionCore(state, action.taskId));
+    case "settle":
+      return traceCoreActionResult(
+        state,
+        settleAdmissionCore(state, action.taskId, action.outcome)
+      );
+    case "settle-running":
+      return traceCoreActionResult(
+        state,
+        settleRunningAdmissionCore(state, action.taskId, action.settlementKind)
+      );
+    case "cancel-pending": {
+      const cancelled = cancelPendingAdmissionCore(state);
+      return Object.freeze({
+        accepted: true,
+        effectStates: cancelled.effectStates,
+        effects: cancelled.effects,
+        reasonKind: null,
+        state: cancelled.state
+      });
+    }
+    case "reconcile": {
+      const reconciled = reconcileAdmissionCore(state);
+      return Object.freeze({
+        accepted: true,
+        effectStates: reconciled.effectStates,
+        effects: reconciled.effects,
+        reasonKind: null,
+        state: reconciled.state
+      });
+    }
+  }
+}
+
+/** Normalizes the reducer's common accepted/rejected transition protocol for trace output. */
+function traceCoreActionResult(
+  state: AdmissionCoreState,
+  result: AdmissionCoreActionResult
+): AppliedTraceAction {
+  return result.accepted
+    ? Object.freeze({
+        accepted: true,
+        effectStates: result.transition.effectStates,
+        effects: result.transition.effects,
+        reasonKind: null,
+        state: result.transition.state
+      })
+    : Object.freeze({
+        accepted: false,
+        effectStates: [],
+        effects: [],
+        reasonKind: result.reason.kind,
+        state
+      });
+}
+
+export function admissionCoreTraceProjectionFor(
+  state: AdmissionCoreState
+): AdmissionCoreTraceProjection {
+  return projectionFor(state, state.compiled.taskIdsInPublicOrder);
+}
+
+function projectionFor(
+  state: AdmissionCoreState,
+  taskIds: readonly string[]
+): AdmissionCoreTraceProjection {
+  const publicState = admissionStateForCore(state);
+  return Object.freeze({
+    catalog: publicState.catalog,
+    inspection: publicState.inspection,
+    validation: Object.freeze(
+      [...taskIds, "__admission_trace_unknown__"].map((taskId) =>
+        Object.freeze({ taskId, value: publicState.validateSelection(taskId) })
+      )
+    )
+  });
+}

package/src/project-run/task-scheduler/admission-scope-layers.ts

@@ -0,0 +1,44 @@
+import type { SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope } from "./graph.ts";
+
+/** Returns the declared scope for one Task without inferring membership from activation state. */
+export function scopeForTask(
+  graph: PlannedTaskGraph,
+  task: PlannedTask
+): PlannedTaskScope | undefined {
+  return task.scopeId === undefined
+    ? undefined
+    : graph.scopes.find((scope) => scope.id === task.scopeId);
+}
+
+/** Returns the inactive constrained scope that this Task would activate. */
+export function tighteningScopeForTask(
+  graph: PlannedTaskGraph,
+  inspection: SchedulerInspection,
+  task: PlannedTask
+): PlannedTaskScope | undefined {
+  const scope = scopeForTask(graph, task);
+  if (
+    scope === undefined ||
+    !scope.activationTaskIds.includes(task.id) ||
+    inspection.activeScopeIds.includes(scope.id) ||
+    scope.maxParallel >= inspection.maxParallel
+  ) {
+    return undefined;
+  }
+  return scope;
+}
+
+/** Reports whether a Task continues an active scope that constrains root parallelism. */
+export function isConstrainedScopeContinuation(
+  graph: PlannedTaskGraph,
+  inspection: SchedulerInspection,
+  task: PlannedTask
+): boolean {
+  const scope = scopeForTask(graph, task);
+  return (
+    scope !== undefined &&
+    inspection.activeScopeIds.includes(scope.id) &&
+    scope.maxParallel < inspection.maxParallel
+  );
+}