@zxyycom/vibe-check 0.0.1

package/src/project-run/task-scheduler/execution-state.ts

@@ -0,0 +1,153 @@
+import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope, TaskGraph } from "./graph.ts";
+import type { DiagnosticLogger } from "../diagnostic-logging/logger.ts";
+import type { SchedulerSnapshot } from "./scheduler-decision.ts";
+
+export type TaskSettlement<TResult> = Readonly<
+  | { readonly kind: "completed"; readonly value: TResult }
+  | { readonly kind: "failed"; readonly error: unknown }
+  | { readonly kind: "blocked"; readonly dependencyIds: readonly string[] }
+  | { readonly kind: "cancelled-before-start" }
+>;
+
+export interface SettledTask<TResult> {
+  readonly task: PlannedTask;
+  readonly settlement: TaskSettlement<TResult>;
+}
+
+export interface TaskExecutionContext {
+  readonly signal: AbortSignal | undefined;
+}
+
+export interface TaskGraphRun<TResult> {
+  readonly cancelled: boolean;
+  /** One entry per static graph Task, in static graph order. */
+  readonly settlements: readonly SettledTask<TResult>[];
+}
+
+export interface RunTaskGraphOptions<TResult> {
+  readonly diagnosticLogger?: DiagnosticLogger;
+  readonly graph: TaskGraph;
+  readonly maxParallel: number;
+  readonly signal?: AbortSignal;
+  readonly execute: (
+    task: PlannedTask,
+    context: TaskExecutionContext
+  ) => TResult | Promise<TResult>;
+}
+
+export type RunningTaskCompletion<TResult> = Readonly<{
+  readonly taskId: string;
+  readonly settlement: TaskSettlement<TResult>;
+}>;
+
+export interface RunningTask<TResult> {
+  readonly task: PlannedTask;
+  readonly completion: Promise<RunningTaskCompletion<TResult>>;
+}
+
+export interface RuntimeScope {
+  readonly scope: PlannedTaskScope;
+  readonly activationTaskIds: ReadonlySet<string>;
+  isActive: boolean;
+}
+
+export interface SchedulerState<TResult> {
+  readonly diagnosticLogger: DiagnosticLogger | undefined;
+  readonly graph: PlannedTaskGraph;
+  readonly maxParallel: number;
+  readonly signal: AbortSignal | undefined;
+  readonly execute: RunTaskGraphOptions<TResult>["execute"];
+  readonly pending: PlannedTask[];
+  readonly runningById: Map<string, RunningTask<TResult>>;
+  readonly runningMutexes: Set<string>;
+  readonly settlementsByTaskId: Map<string, TaskSettlement<TResult>>;
+  readonly scopesById: ReadonlyMap<string, RuntimeScope>;
+  reservationTaskId: string | undefined;
+  isCancelled: boolean;
+}
+
+export function createSchedulerState<TResult>(
+  graph: PlannedTaskGraph,
+  options: RunTaskGraphOptions<TResult>
+): SchedulerState<TResult> {
+  const scopesById = new Map<string, RuntimeScope>();
+  for (const scope of graph.scopes) {
+    scopesById.set(scope.id, {
+      scope,
+      activationTaskIds: new Set(scope.activationTaskIds),
+      isActive: false
+    });
+  }
+  return {
+    diagnosticLogger: options.diagnosticLogger,
+    graph,
+    maxParallel: options.maxParallel,
+    signal: options.signal,
+    execute: options.execute,
+    pending: [...graph.tasks],
+    runningById: new Map(),
+    runningMutexes: new Set(),
+    settlementsByTaskId: new Map(),
+    scopesById,
+    reservationTaskId: undefined,
+    isCancelled: false
+  };
+}
+
+/** Projects mutable execution state into the pure scheduler-decision input. */
+export function snapshotSchedulerState<TResult>(state: SchedulerState<TResult>): SchedulerSnapshot {
+  return Object.freeze({
+    activeScopeIds: Object.freeze(
+      [...state.scopesById.values()]
+        .filter((scope) => scope.isActive)
+        .map((scope) => scope.scope.id)
+    ),
+    graph: state.graph,
+    isAbortRequested: state.signal?.aborted === true,
+    isCancelled: state.isCancelled,
+    maxParallel: state.maxParallel,
+    pendingTaskIds: Object.freeze(state.pending.map((task) => task.id)),
+    reservationTaskId: state.reservationTaskId,
+    runningMutexes: Object.freeze([...state.runningMutexes]),
+    runningTaskIds: Object.freeze([...state.runningById.keys()]),
+    settledTasks: Object.freeze(
+      [...state.settlementsByTaskId].map(([taskId, settlement]) =>
+        Object.freeze({ kind: settlement.kind, taskId })
+      )
+    )
+  });
+}
+
+export function scopeForTask<TResult>(
+  task: PlannedTask,
+  state: SchedulerState<TResult>
+): RuntimeScope | undefined {
+  return task.scopeId === undefined ? undefined : state.scopesById.get(task.scopeId);
+}
+
+export function cancelPendingTasks<TResult>(state: SchedulerState<TResult>): void {
+  state.isCancelled = true;
+  state.reservationTaskId = undefined;
+  while (state.pending.length > 0) {
+    const task = state.pending.shift();
+    if (task === undefined) {
+      throw new Error("task graph pending queue changed unexpectedly");
+    }
+    recordSettlement(state, task, Object.freeze({ kind: "cancelled-before-start" }));
+  }
+}
+
+export function recordSettlement<TResult>(
+  state: SchedulerState<TResult>,
+  task: PlannedTask,
+  settlement: TaskSettlement<TResult>
+): void {
+  if (state.settlementsByTaskId.has(task.id)) {
+    throw new Error(`task ${task.id} settled more than once`);
+  }
+  state.settlementsByTaskId.set(task.id, settlement);
+  const scope = scopeForTask(task, state);
+  if (scope?.scope.terminalTaskId === task.id) {
+    scope.isActive = false;
+  }
+}

package/src/project-run/task-scheduler/graph-validation.ts

@@ -0,0 +1,176 @@
+import type { PlannedTask, PlannedTaskScope } from "./graph.ts";
+
+interface PreparedTaskGraphValidationInput {
+  readonly rootMaxParallel: number | undefined;
+  readonly scopeById: ReadonlyMap<string, PlannedTaskScope>;
+  readonly scopes: readonly PlannedTaskScope[];
+  readonly taskById: ReadonlyMap<string, PlannedTask>;
+  readonly tasks: readonly PlannedTask[];
+}
+
+interface DependencyPathQuery {
+  readonly requiredDependencyId: string;
+  readonly taskById: ReadonlyMap<string, PlannedTask>;
+  readonly taskId: string;
+}
+
+interface DependencyTraversal {
+  readonly pending: string[];
+  readonly query: DependencyPathQuery;
+  readonly visited: Set<string>;
+}
+
+/** Validates dependency and scope relations after graph-shaped input is normalized. */
+export function validatePreparedTaskGraph(input: PreparedTaskGraphValidationInput): void {
+  validateDependencies(input.tasks, input.taskById);
+  validateDependencyCycles(input.tasks, input.taskById);
+  validateScopes(input);
+}
+
+function validateDependencies(
+  tasks: readonly PlannedTask[],
+  taskById: ReadonlyMap<string, PlannedTask>
+): void {
+  for (const task of tasks) {
+    for (const dependency of task.dependsOn) {
+      if (!taskById.has(dependency)) {
+        throw new Error(`task ${task.id} depends on unknown task ${dependency}`);
+      }
+    }
+  }
+}
+
+function validateDependencyCycles(
+  tasks: readonly PlannedTask[],
+  taskById: ReadonlyMap<string, PlannedTask>
+): void {
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+
+  const visit = (task: PlannedTask): void => {
+    if (visiting.has(task.id)) {
+      throw new Error(`task dependency cycle includes ${task.id}`);
+    }
+    if (visited.has(task.id)) return;
+
+    visiting.add(task.id);
+    for (const dependency of task.dependsOn) {
+      const dependencyTask = taskById.get(dependency);
+      if (dependencyTask === undefined) {
+        throw new Error(`task ${task.id} depends on unknown task ${dependency}`);
+      }
+      visit(dependencyTask);
+    }
+    visiting.delete(task.id);
+    visited.add(task.id);
+  };
+
+  for (const task of tasks) {
+    visit(task);
+  }
+}
+
+function validateScopes(input: PreparedTaskGraphValidationInput): void {
+  validateRootMaxParallel(input.rootMaxParallel);
+  validateTaskScopeMembership(input.tasks, input.scopeById);
+  for (const scope of input.scopes) {
+    validateScopeCap(scope, input.rootMaxParallel);
+    validateScopeTerminal(scope, input.taskById);
+    validateScopeActivation(scope, input.taskById);
+    validateScopeTerminalReachability(scope, input.tasks, input.taskById);
+  }
+}
+
+function validateRootMaxParallel(rootMaxParallel: number | undefined): void {
+  if (
+    rootMaxParallel !== undefined &&
+    (!Number.isSafeInteger(rootMaxParallel) || rootMaxParallel <= 0)
+  ) {
+    throw new TypeError("task engine maxParallel must be a positive safe integer");
+  }
+}
+
+function validateTaskScopeMembership(
+  tasks: readonly PlannedTask[],
+  scopeById: ReadonlyMap<string, PlannedTaskScope>
+): void {
+  for (const task of tasks) {
+    if (task.scopeId !== undefined && !scopeById.has(task.scopeId)) {
+      throw new Error(`task ${task.id} references unknown scope ${task.scopeId}`);
+    }
+  }
+}
+
+function validateScopeCap(scope: PlannedTaskScope, rootMaxParallel: number | undefined): void {
+  if (rootMaxParallel !== undefined && scope.maxParallel > rootMaxParallel) {
+    throw new Error(`task scope ${scope.id} maxParallel exceeds task engine maxParallel`);
+  }
+}
+
+function validateScopeTerminal(
+  scope: PlannedTaskScope,
+  taskById: ReadonlyMap<string, PlannedTask>
+): void {
+  const terminal = taskById.get(scope.terminalTaskId);
+  if (terminal?.scopeId !== scope.id) {
+    throw new Error(`task scope ${scope.id} terminal task must belong to the scope`);
+  }
+}
+
+function validateScopeActivation(
+  scope: PlannedTaskScope,
+  taskById: ReadonlyMap<string, PlannedTask>
+): void {
+  const activationIds = new Set<string>();
+  for (const taskId of scope.activationTaskIds) {
+    if (activationIds.has(taskId)) {
+      throw new Error(`task scope ${scope.id} repeats activation task ${taskId}`);
+    }
+    activationIds.add(taskId);
+    const task = taskById.get(taskId);
+    if (task?.scopeId !== scope.id) {
+      throw new Error(`task scope ${scope.id} activation task must belong to the scope: ${taskId}`);
+    }
+  }
+}
+
+function validateScopeTerminalReachability(
+  scope: PlannedTaskScope,
+  tasks: readonly PlannedTask[],
+  taskById: ReadonlyMap<string, PlannedTask>
+): void {
+  for (const task of tasks) {
+    if (task.scopeId !== scope.id || task.id === scope.terminalTaskId) continue;
+    if (!dependsOnTask({ requiredDependencyId: task.id, taskById, taskId: scope.terminalTaskId })) {
+      throw new Error(`task scope ${scope.id} terminal task must depend on scoped task ${task.id}`);
+    }
+  }
+}
+
+function dependsOnTask(query: DependencyPathQuery): boolean {
+  return traverseDependencies({
+    pending: [...taskDependencies(query.taskById, query.taskId)],
+    query,
+    visited: new Set()
+  });
+}
+
+function traverseDependencies(traversal: DependencyTraversal): boolean {
+  while (traversal.pending.length > 0) {
+    const dependencyId = traversal.pending.pop();
+    if (dependencyId === undefined || traversal.visited.has(dependencyId)) continue;
+    if (dependencyId === traversal.query.requiredDependencyId) return true;
+
+    traversal.visited.add(dependencyId);
+    traversal.pending.push(...taskDependencies(traversal.query.taskById, dependencyId));
+  }
+  return false;
+}
+
+function taskDependencies(
+  taskById: ReadonlyMap<string, PlannedTask>,
+  taskId: string
+): readonly string[] {
+  const task = taskById.get(taskId);
+  return task === undefined ? [] : task.dependsOn;
+}

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

@@ -0,0 +1,185 @@
+import { validatePreparedTaskGraph } from "./graph-validation.ts";
+
+export interface TaskNode {
+  readonly id: string;
+  readonly dependsOn?: readonly string[];
+  readonly mutex?: readonly string[];
+  readonly scopeId?: string;
+}
+
+/**
+ * A scheduling scope is intentionally product-agnostic. Product adapters may
+ * use its opaque id to bind local Check semantics, but the engine only uses
+ * membership, a cap, activation candidates, and the terminal relation.
+ */
+export interface TaskScope {
+  readonly id: string;
+  readonly maxParallel: number;
+  readonly activationTaskIds: readonly string[];
+  readonly terminalTaskId: string;
+}
+
+export interface TaskGraph {
+  readonly tasks: readonly TaskNode[];
+  readonly scopes?: readonly TaskScope[];
+}
+
+export interface PlannedTask {
+  readonly id: string;
+  readonly dependsOn: readonly string[];
+  readonly mutex: readonly string[];
+  readonly scopeId: string | undefined;
+}
+
+export interface PlannedTaskScope {
+  readonly id: string;
+  readonly maxParallel: number;
+  readonly activationTaskIds: readonly string[];
+  readonly terminalTaskId: string;
+}
+
+export interface PlannedTaskGraph {
+  readonly tasks: readonly PlannedTask[];
+  readonly scopes: readonly PlannedTaskScope[];
+}
+
+const TASK_GRAPH_KEYS = ["tasks", "scopes"] as const;
+const TASK_NODE_KEYS = ["id", "dependsOn", "mutex", "scopeId"] as const;
+const TASK_SCOPE_KEYS = ["id", "maxParallel", "activationTaskIds", "terminalTaskId"] as const;
+
+/** Validates untrusted graph-shaped input without admitting it to scheduler execution. */
+export function validateTaskGraph(graph: unknown): void {
+  prepareTaskGraph(graph);
+}
+
+export function prepareTaskGraph(graph: unknown, rootMaxParallel?: number): PlannedTaskGraph {
+  const data = record(graph, "task graph", TASK_GRAPH_KEYS);
+  const tasks = normalizeTasks(data.tasks);
+  const scopes = normalizeScopes(data.scopes);
+  const taskById = new Map(tasks.map((task) => [task.id, task] as const));
+  const scopeById = new Map(scopes.map((scope) => [scope.id, scope] as const));
+
+  validatePreparedTaskGraph({ rootMaxParallel, scopeById, scopes, taskById, tasks });
+
+  return Object.freeze({
+    tasks: Object.freeze(tasks),
+    scopes: Object.freeze(scopes)
+  });
+}
+
+function normalizeTasks(value: unknown): PlannedTask[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError("task graph tasks must be an array");
+  }
+
+  const ids = new Set<string>();
+  const tasks: PlannedTask[] = [];
+  for (const [index, candidate] of value.entries()) {
+    const data = record(candidate, `task graph tasks[${index}]`, TASK_NODE_KEYS);
+    const id = nonEmptyString(data.id, `task graph tasks[${index}].id`);
+    if (ids.has(id)) {
+      throw new TypeError(`duplicate task id: ${id}`);
+    }
+    ids.add(id);
+    const scopeId = optionalNonEmptyString(data.scopeId, `task ${id}.scopeId`);
+    tasks.push(
+      Object.freeze({
+        id,
+        dependsOn: Object.freeze(stringList(data.dependsOn, `task ${id}.dependsOn`)),
+        mutex: Object.freeze(stringList(data.mutex, `task ${id}.mutex`)),
+        scopeId
+      })
+    );
+  }
+  return tasks;
+}
+
+function normalizeScopes(value: unknown): PlannedTaskScope[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError("task graph scopes must be an array");
+  }
+
+  const ids = new Set<string>();
+  const scopes: PlannedTaskScope[] = [];
+  for (const [index, candidate] of value.entries()) {
+    const data = record(candidate, `task graph scopes[${index}]`, TASK_SCOPE_KEYS);
+    const id = nonEmptyString(data.id, `task graph scopes[${index}].id`);
+    if (ids.has(id)) {
+      throw new TypeError(`duplicate task scope id: ${id}`);
+    }
+    ids.add(id);
+    const maxParallel = positiveSafeInteger(data.maxParallel, `task scope ${id}.maxParallel`);
+    const activationTaskIds = requiredStringList(
+      data.activationTaskIds,
+      `task scope ${id}.activationTaskIds`
+    );
+    const terminalTaskId = nonEmptyString(data.terminalTaskId, `task scope ${id}.terminalTaskId`);
+    scopes.push(
+      Object.freeze({
+        id,
+        maxParallel,
+        activationTaskIds: Object.freeze(activationTaskIds),
+        terminalTaskId
+      })
+    );
+  }
+  return scopes;
+}
+
+function record(
+  value: unknown,
+  fieldName: string,
+  allowedKeys: readonly string[]
+): Readonly<Record<string, unknown>> {
+  if (!isTaskGraphRecord(value)) {
+    throw new TypeError(`${fieldName} must be an object`);
+  }
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.includes(key)) {
+      throw new TypeError(`${fieldName} has unknown property: ${key}`);
+    }
+  }
+  return value;
+}
+
+function isTaskGraphRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown, fieldName: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${fieldName} must be a non-empty string`);
+  }
+  return value;
+}
+
+function optionalNonEmptyString(value: unknown, fieldName: string): string | undefined {
+  return value === undefined ? undefined : nonEmptyString(value, fieldName);
+}
+
+function stringList(value: unknown, fieldName: string): string[] {
+  if (value === undefined) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${fieldName} must be an array of non-empty strings`);
+  }
+  return value.map((item, index) => nonEmptyString(item, `${fieldName}[${index}]`));
+}
+
+function requiredStringList(value: unknown, fieldName: string): string[] {
+  if (value === undefined) {
+    throw new TypeError(`${fieldName} must be an array of non-empty strings`);
+  }
+  return stringList(value, fieldName);
+}
+
+function positiveSafeInteger(value: unknown, fieldName: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${fieldName} must be a positive safe integer`);
+  }
+  return value;
+}

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

@@ -0,0 +1,177 @@
+import type { PlannedTask } from "./graph.ts";
+import {
+  activationScopeFor,
+  canAdmit,
+  capacityWaitReason,
+  isDependencyMutexEligible,
+  selectConstrainedContinuation,
+  selectTighteningTask,
+  type SchedulerInspection
+} from "./scheduler-decision-inspection.ts";
+import {
+  freezeDecision,
+  reservationClear,
+  reservationSet,
+  reservationUnchanged,
+  type ReservationUpdate,
+  type SchedulerAdmissionReason,
+  type SchedulerAwaitReason,
+  type SchedulerDecision,
+  type SchedulerDecisionContext,
+  type SchedulerTrigger
+} from "./scheduler-decision-model.ts";
+
+export interface SchedulerDecisionCycle {
+  readonly context: SchedulerDecisionContext;
+  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)
+  );
+  if (eligibleTasks.length === 0) {
+    return awaitDecision(cycle, {
+      eligibleTasks,
+      reason: "dependency-or-mutex",
+      reservationUpdate: reservationUnchanged()
+    });
+  }
+
+  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)
+  );
+}
+
+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 });
+}
+
+function admitDecision(
+  cycle: SchedulerDecisionCycle,
+  selection: AdmissionSelection,
+  eligibleTasks: readonly PlannedTask[]
+): SchedulerDecision {
+  return freezeDecision({
+    ...cycle.context,
+    eligibleCount: eligibleTasks.length,
+    kind: "admit",
+    reason: selection.reason,
+    reservationUpdate: selection.reservationUpdate,
+    scopeToActivate: activationScopeFor(cycle.state, selection.task)?.id ?? null,
+    taskId: selection.task.id,
+    trigger: cycle.trigger
+  });
+}
+
+function awaitDecision(
+  cycle: SchedulerDecisionCycle,
+  waiting: AwaitingSchedulerDecision
+): SchedulerDecision {
+  if (cycle.state.runningTaskIds.size === 0) {
+    throw new Error("scheduler has pending tasks but no runnable or running task");
+  }
+  return freezeDecision({
+    ...cycle.context,
+    eligibleCount: waiting.eligibleTasks.length,
+    kind: "await-running",
+    reason: waiting.reason,
+    reservationUpdate: waiting.reservationUpdate,
+    trigger: cycle.trigger
+  });
+}
+
+function staleReservationUpdate(state: SchedulerInspection): ReservationUpdate {
+  return state.reservationTaskId === undefined ? reservationUnchanged() : reservationClear();
+}
+
+function taskById(
+  taskId: string | undefined,
+  tasks: readonly PlannedTask[]
+): PlannedTask | undefined {
+  return taskId === undefined ? undefined : tasks.find((task) => task.id === taskId);
+}