@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -0,0 +1,116 @@
+import type { PlannedTask, PlannedTaskGraph } from "./graph.ts";
+import type { AdmissionCoreState } from "./admission-core/core.ts";
+import {
+  isConstrainedScopeContinuation,
+  scopeForTask,
+  tighteningScopeForTask
+} from "./admission-scope-layers.ts";
+import type { SchedulerInspection } from "./scheduler-decision-inspection.ts";
+import type {
+  AdmissionPolicyContext,
+  SchedulerGraphSnapshot
+} from "../../project-definition/project-definition.ts";
+
+export interface AdmissionCandidate {
+  readonly canAdmit: boolean;
+  readonly task: PlannedTask;
+}
+
+export interface AdmissionPolicyInput {
+  /** Shared immutable core at this decision boundary; only custom context projects its public handle. */
+  readonly admissionCore: AdmissionCoreState;
+  /** Scheduler-owned decision-boundary measurement, present only for custom policy. */
+  readonly measurement?: AdmissionPolicyContext["measurement"];
+  readonly candidates: readonly AdmissionCandidate[];
+  readonly graph: PlannedTaskGraph;
+  readonly graphSnapshot: SchedulerGraphSnapshot;
+  readonly inspection: SchedulerInspection;
+}
+
+export type AdmissionPolicyDecision =
+  | Readonly<{ readonly kind: "select"; readonly taskId: string }>
+  | Readonly<{ readonly kind: "wait" }>;
+
+/** A Product-private pure admission policy; it receives no executor or mutable scheduler state. */
+export interface AdmissionSelectionPolicy {
+  /** Only custom policies require Scheduler sampling before every callback. */
+  readonly requiresMeasurement?: true;
+  readonly decide: (input: AdmissionPolicyInput) => AdmissionPolicyDecision;
+}
+
+export const staticAdmissionSelectionPolicy: AdmissionSelectionPolicy = Object.freeze({
+  decide: decideStaticAdmission
+});
+
+function decideStaticAdmission(input: AdmissionPolicyInput): AdmissionPolicyDecision {
+  const tightening = selectTighteningCandidate(input);
+  if (tightening !== undefined) return proposalFor(tightening);
+
+  const continuation = selectConstrainedContinuation(input);
+  if (continuation !== undefined) return proposalFor(continuation);
+
+  return proposalFor(selectOrdinaryReadyCandidate(input.candidates));
+}
+
+function proposalFor(candidate: AdmissionCandidate): AdmissionPolicyDecision {
+  return candidate.canAdmit
+    ? Object.freeze({ kind: "select", taskId: candidate.task.id })
+    : Object.freeze({ kind: "wait" });
+}
+
+function selectTighteningCandidate(input: AdmissionPolicyInput): AdmissionCandidate | undefined {
+  return input.candidates
+    .filter(
+      (candidate) =>
+        tighteningScopeForTask(input.graph, input.inspection, candidate.task) !== undefined
+    )
+    .sort((left, right) => compareConstrainedCandidates(input, left, right))[0];
+}
+
+function selectConstrainedContinuation(
+  input: AdmissionPolicyInput
+): AdmissionCandidate | undefined {
+  return input.candidates
+    .filter((candidate) =>
+      isConstrainedScopeContinuation(input.graph, input.inspection, candidate.task)
+    )
+    .sort((left, right) => compareConstrainedCandidates(input, left, right))[0];
+}
+
+function selectOrdinaryReadyCandidate(
+  candidates: readonly AdmissionCandidate[]
+): AdmissionCandidate {
+  const admissible = candidates.filter(({ canAdmit }) => canAdmit);
+  const selectable = admissible.length === 0 ? candidates : admissible;
+  const [first, ...remaining] = selectable;
+  if (first === undefined) throw new Error("static scheduler selection requires a candidate");
+  return remaining.reduce(
+    (selected, candidate) =>
+      candidate.task.admissionPriority > selected.task.admissionPriority ? candidate : selected,
+    first
+  );
+}
+
+function compareConstrainedCandidates(
+  input: AdmissionPolicyInput,
+  left: AdmissionCandidate,
+  right: AdmissionCandidate
+): number {
+  const leftScope = scopeForTask(input.graph, left.task);
+  const rightScope = scopeForTask(input.graph, right.task);
+  if (leftScope === undefined || rightScope === undefined) {
+    throw new Error("constrained task is missing a scope");
+  }
+  return (
+    leftScope.maxParallel - rightScope.maxParallel ||
+    right.task.admissionPriority - left.task.admissionPriority ||
+    compareText(leftScope.id, rightScope.id) ||
+    compareText(left.task.id, right.task.id)
+  );
+}
+
+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/custom-admission-policy.ts

@@ -0,0 +1,128 @@
+import type {
+  AdmissionPolicyContext,
+  AdmissionProposal
+} from "../../project-definition/project-definition.ts";
+import type {
+  AdmissionPolicyInput,
+  AdmissionSelectionPolicy
+} from "./admission-selection-policy.ts";
+import {
+  AdmissionPolicyFault,
+  type AdmissionPolicyFaultCategory
+} from "./scheduler-admission-decision.ts";
+import { capacityFor } from "./scheduler-decision-inspection.ts";
+import { admissionStateForCore } from "./admission-core/core.ts";
+
+/** Adapts the public, trusted callback to the Scheduler's private pure policy seam. */
+export function admissionSelectionPolicyFor(
+  decide: (this: void, context: AdmissionPolicyContext) => AdmissionProposal
+): AdmissionSelectionPolicy {
+  return Object.freeze({
+    requiresMeasurement: true,
+    decide: (input: AdmissionPolicyInput) => invokeCustomPolicy(decide, input)
+  });
+}
+
+function invokeCustomPolicy(
+  decide: (this: void, context: AdmissionPolicyContext) => AdmissionProposal,
+  input: AdmissionPolicyInput
+): AdmissionProposal {
+  let proposal: unknown;
+  try {
+    proposal = decide(admissionPolicyContext(input));
+  } catch {
+    throw new AdmissionPolicyFault("callback-threw");
+  }
+  if (isThenable(proposal)) throw new AdmissionPolicyFault("thenable-proposal");
+  return validateProposal(proposal);
+}
+
+function admissionPolicyContext(input: AdmissionPolicyInput): AdmissionPolicyContext {
+  if (input.measurement === undefined)
+    throw new Error("custom admission policy requires measurement");
+  return deepFreeze({
+    activeScopeIds: [...input.inspection.activeScopeIds],
+    admissionState: admissionStateForCore(input.admissionCore),
+    candidates: input.candidates.map((candidate) => ({
+      canAdmit: candidate.canAdmit,
+      taskId: candidate.task.id
+    })),
+    capacity: capacityFor(input.inspection),
+    measurement: input.measurement,
+    graph: input.graphSnapshot,
+    runningTaskIds: [...input.inspection.runningTaskIds],
+    runtime: {
+      abortRequested: input.inspection.isAbortRequested,
+      cancelled: input.inspection.isCancelled
+    },
+    settledTaskIds: input.inspection.settledTasks.map((task) => task.taskId)
+  });
+}
+
+function validateProposal(value: unknown): AdmissionProposal {
+  if (!isPlainRecord(value)) throw new AdmissionPolicyFault("malformed-proposal");
+  try {
+    return parseProposalRecord(value);
+  } catch (error) {
+    if (error instanceof AdmissionPolicyFault) throw error;
+    throw new AdmissionPolicyFault("malformed-proposal");
+  }
+}
+
+function parseProposalRecord(value: Record<string, unknown>): AdmissionProposal {
+  switch (value.kind) {
+    case "select":
+      return parseSelectProposal(value);
+    case "wait":
+      return parseWaitProposal(value);
+  }
+  throw new AdmissionPolicyFault("malformed-proposal");
+}
+
+function parseSelectProposal(value: Record<string, unknown>): AdmissionProposal {
+  const keys = Reflect.ownKeys(value);
+  if (
+    keys.length !== 2 ||
+    !keys.includes("kind") ||
+    !keys.includes("taskId") ||
+    typeof value.taskId !== "string"
+  ) {
+    throw new AdmissionPolicyFault("malformed-proposal");
+  }
+  return Object.freeze({ kind: "select", taskId: value.taskId });
+}
+
+function parseWaitProposal(value: Record<string, unknown>): AdmissionProposal {
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 1 || keys[0] !== "kind") {
+    throw new AdmissionPolicyFault("malformed-proposal");
+  }
+  return Object.freeze({ kind: "wait" });
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  try {
+    const prototype = Reflect.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+  } catch {
+    return false;
+  }
+}
+
+function isThenable(value: unknown): boolean {
+  if (value === null || (typeof value !== "object" && typeof value !== "function")) return false;
+  try {
+    return typeof Reflect.get(value, "then") === "function";
+  } catch {
+    return true;
+  }
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
+  for (const item of Object.values(value)) deepFreeze(item);
+  return Object.freeze(value);
+}
+
+export type { AdmissionPolicyFaultCategory };

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

@@ -1,9 +1,27 @@
+import type {
+  SchedulerMeasurementContext,
+  SchedulerTerminalEffect
+} from "../../project-definition/project-definition.ts";
 import type { PlannedTask, PlannedTaskGraph, PlannedTaskScope, TaskGraph } from "./graph.ts";
+import {
+  staticAdmissionSelectionPolicy,
+  type AdmissionSelectionPolicy
+} from "./admission-selection-policy.ts";
 import type { DiagnosticLogger } from "../diagnostic-logging/logger.ts";
 import type { SchedulerSnapshot } from "./scheduler-decision.ts";
+import type { AdmissionPolicyFaultCategory } from "./scheduler-admission-decision.ts";
+import type { SchedulerPerformanceDiagnosticsInput } from "./measurement/diagnostics.ts";
+import {
+  compilePreparedAdmissionGraph,
+  createAdmissionCoreFromSchedulerSnapshot,
+  createInitialAdmissionCoreState,
+  type AdmissionCoreEffect,
+  type AdmissionCoreState
+} from "./admission-core/core.ts";
 
 export type TaskSettlement<TResult> = Readonly<
   | { readonly kind: "completed"; readonly value: TResult }
+  | { readonly kind: "prerequisite-unsatisfied"; readonly value: TResult }
   | { readonly kind: "failed"; readonly error: unknown }
   | { readonly kind: "blocked"; readonly dependencyIds: readonly string[] }
   | { readonly kind: "cancelled-before-start" }
@@ -18,21 +36,51 @@ export interface TaskExecutionContext {
   readonly signal: AbortSignal | undefined;
 }
 
+export interface PreAdmissionTaskResult<TResult> {
+  readonly taskId: string;
+  readonly value: TResult;
+}
+
+/** Product-private effect hook used to prove that the real shell replays the shared core. */
+export interface SchedulerAdmissionCoreEffect {
+  readonly effect: AdmissionCoreEffect;
+  readonly state: AdmissionCoreState;
+}
+
 export interface TaskGraphRun<TResult> {
+  readonly admissionPolicyFault: AdmissionPolicyFaultCategory | undefined;
   readonly cancelled: boolean;
   /** One entry per static graph Task, in static graph order. */
   readonly settlements: readonly SettledTask<TResult>[];
+  /** Product-private terminal facts retained after terminal Hooks have been drained. */
+  readonly terminalMeasurement?: SchedulerMeasurementContext;
 }
 
 export interface RunTaskGraphOptions<TResult> {
+  /** Product-private policy handoff; package consumers cannot author this through the public API. */
+  readonly admissionPolicy?: AdmissionSelectionPolicy;
   readonly diagnosticLogger?: DiagnosticLogger;
+  /** Explicit enabled-only handoff; no Scheduler behavior is inferred from a logger shape. */
+  readonly performanceDiagnostics?: SchedulerPerformanceDiagnosticsInput;
+  /** Runtime-only terminal consumers; their context is formed after Scheduler drain. */
+  readonly terminalEffects?: readonly SchedulerTerminalEffect[];
+  readonly onTerminalEffectFailure?: () => void;
+  readonly onTerminalEffectsSettled?: () => void;
+  /** Product-private test observer; no package consumer can supply this through `run`. */
+  readonly onAdmissionCoreEffect?: (effect: SchedulerAdmissionCoreEffect) => void;
   readonly graph: TaskGraph;
+  /** Product-private Task results formed without Scheduler admission in the current Run. */
+  readonly preAdmissionTaskResults?: readonly PreAdmissionTaskResult<TResult>[];
   readonly maxParallel: number;
   readonly signal?: AbortSignal;
   readonly execute: (
     task: PlannedTask,
     context: TaskExecutionContext
   ) => TResult | Promise<TResult>;
+  /** Maps a completed Task's opaque product value to prerequisite satisfaction. */
+  readonly isPrerequisiteSatisfied?: (value: TResult) => boolean;
+  /** Lets a product close a blocked Task before any terminal observer can be admitted. */
+  readonly onTaskBlocked?: (task: PlannedTask, dependencyIds: readonly string[]) => void;
 }
 
 export type RunningTaskCompletion<TResult> = Readonly<{
@@ -52,24 +100,34 @@ export interface RuntimeScope {
 }
 
 export interface SchedulerState<TResult> {
+  /** The shared immutable legality/transition state; Task and Promise ownership remains below. */
+  admissionCore: AdmissionCoreState;
+  readonly admissionPolicy: AdmissionSelectionPolicy;
   readonly diagnosticLogger: DiagnosticLogger | undefined;
   readonly graph: PlannedTaskGraph;
+  readonly isPrerequisiteSatisfied: RunTaskGraphOptions<TResult>["isPrerequisiteSatisfied"];
   readonly maxParallel: number;
   readonly signal: AbortSignal | undefined;
   readonly execute: RunTaskGraphOptions<TResult>["execute"];
+  readonly onTaskBlocked: RunTaskGraphOptions<TResult>["onTaskBlocked"];
+  readonly onAdmissionCoreEffect: RunTaskGraphOptions<TResult>["onAdmissionCoreEffect"];
   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;
+  admissionPolicyFault: AdmissionPolicyFaultCategory | undefined;
 }
 
 export function createSchedulerState<TResult>(
   graph: PlannedTaskGraph,
   options: RunTaskGraphOptions<TResult>
 ): SchedulerState<TResult> {
+  const admissionPolicy = options.admissionPolicy ?? staticAdmissionSelectionPolicy;
+  if (!Object.isFrozen(admissionPolicy) || typeof admissionPolicy.decide !== "function") {
+    throw new TypeError("task engine admission policy must be a frozen policy value");
+  }
   const scopesById = new Map<string, RuntimeScope>();
   for (const scope of graph.scopes) {
     scopesById.set(scope.id, {
@@ -78,10 +136,16 @@ export function createSchedulerState<TResult>(
       isActive: false
     });
   }
-  return {
+  const compiledAdmissionGraph = compilePreparedAdmissionGraph(graph, options.maxParallel);
+  const state: SchedulerState<TResult> = {
+    admissionCore: createInitialAdmissionCoreState(compiledAdmissionGraph),
+    admissionPolicy,
     diagnosticLogger: options.diagnosticLogger,
     graph,
+    isPrerequisiteSatisfied: options.isPrerequisiteSatisfied,
     maxParallel: options.maxParallel,
+    onTaskBlocked: options.onTaskBlocked,
+    onAdmissionCoreEffect: options.onAdmissionCoreEffect,
     signal: options.signal,
     execute: options.execute,
     pending: [...graph.tasks],
@@ -89,9 +153,38 @@ export function createSchedulerState<TResult>(
     runningMutexes: new Set(),
     settlementsByTaskId: new Map(),
     scopesById,
-    reservationTaskId: undefined,
-    isCancelled: false
+    isCancelled: false,
+    admissionPolicyFault: undefined
   };
+  recordPreAdmissionTaskResults(state, options.preAdmissionTaskResults ?? []);
+  state.admissionCore = createAdmissionCoreFromSchedulerSnapshot(
+    compiledAdmissionGraph,
+    snapshotSchedulerState(state)
+  );
+  return state;
+}
+
+function recordPreAdmissionTaskResults<TResult>(
+  state: SchedulerState<TResult>,
+  preAdmissionTaskResults: readonly PreAdmissionTaskResult<TResult>[]
+): void {
+  for (const result of preAdmissionTaskResults) {
+    const pendingIndex = state.pending.findIndex((task) => task.id === result.taskId);
+    if (pendingIndex < 0) {
+      throw new TypeError(
+        `pre-admission task result references unknown or duplicate task ${result.taskId}`
+      );
+    }
+    const [task] = state.pending.splice(pendingIndex, 1);
+    if (task === undefined) {
+      throw new Error(`pre-admission task ${result.taskId} disappeared before settlement`);
+    }
+    const settlement: TaskSettlement<TResult> =
+      state.isPrerequisiteSatisfied?.(result.value) === false
+        ? { kind: "prerequisite-unsatisfied", value: result.value }
+        : { kind: "completed", value: result.value };
+    recordSettlement(state, task, Object.freeze(settlement));
+  }
 }
 
 /** Projects mutable execution state into the pure scheduler-decision input. */
@@ -107,7 +200,6 @@ export function snapshotSchedulerState<TResult>(state: SchedulerState<TResult>):
     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(
@@ -127,7 +219,6 @@ export function scopeForTask<TResult>(
 
 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) {

package/src/project-run/task-scheduler/forced-block-effect-replay.ts

@@ -0,0 +1,68 @@
+import {
+  schedulerInspectionForCore,
+  type AdmissionCoreEffect,
+  type AdmissionCoreState
+} from "./admission-core/core.ts";
+import { decisionContext } from "./scheduler-decision-inspection.ts";
+import { freezeDecision } from "./scheduler-decision-model.ts";
+import type { SchedulerTrigger } from "./scheduler-decision.ts";
+import type { SchedulerState } from "./execution-state.ts";
+import { observeSchedulerDecision, performanceState } from "./scheduler-observation.ts";
+import type { SchedulerPerformanceDiagnostics } from "./measurement/diagnostics.ts";
+import { applyForcedBlockedSettlement } from "./scheduler-task-lifecycle.ts";
+
+/**
+ * Adapts only canonical forced blocked effects to the real Scheduler shell.
+ * Direct admission, running settlement, and cancellation remain in the root shell.
+ */
+export function replayCoreForcedBlocks<TResult>(
+  state: SchedulerState<TResult>,
+  effects: readonly AdmissionCoreEffect[],
+  effectStates: readonly AdmissionCoreState[],
+  diagnostics: SchedulerPerformanceDiagnostics | undefined,
+  trigger: SchedulerTrigger
+): void {
+  if (effects.length !== effectStates.length) {
+    throw new Error("shared admission core effect replay has no matching immutable post-state");
+  }
+  for (const [index, effect] of effects.entries()) {
+    if (effect.kind !== "settled" || effect.settlementKind !== "blocked") {
+      throw new Error("shared admission core forced-block replay received a non-blocked effect");
+    }
+    const effectState = effectStates[index];
+    if (effectState === undefined) {
+      throw new Error("shared admission core forced block has no immutable post-state");
+    }
+    diagnostics?.beforePendingSettlement([effect.taskId]);
+    state.admissionCore = effectState;
+    applyForcedBlockedSettlement(state, effect.taskId, effect.dependencyIds ?? []);
+    diagnostics?.captureState(performanceState(state));
+    diagnostics?.recordEffect(
+      Object.freeze({ kind: "settled", settlementKind: "blocked", taskId: effect.taskId })
+    );
+    if (diagnostics !== undefined || state.diagnosticLogger !== undefined) {
+      const inspection = schedulerInspectionForCore(state.admissionCore);
+      observeSchedulerDecision(
+        state,
+        freezeDecision({
+          ...decisionContext(
+            Object.freeze({
+              ...inspection,
+              isAbortRequested: state.signal?.aborted === true,
+              isCancelled: state.isCancelled
+            }),
+            state.admissionCore.compiled.graph.schedulerGraphSnapshot
+          ),
+          dependencyIds: effect.dependencyIds ?? [],
+          kind: "settle-blocked",
+          taskId: effect.taskId,
+          trigger
+        }),
+        diagnostics
+      );
+    }
+    if (state.onAdmissionCoreEffect !== undefined) {
+      state.onAdmissionCoreEffect(Object.freeze({ effect, state: state.admissionCore }));
+    }
+  }
+}

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

@@ -1,6 +1,7 @@
-import type { PlannedTask, PlannedTaskScope } from "./graph.ts";
+import type { NamedResourceUnits, PlannedTask, PlannedTaskScope } from "./graph.ts";
 
 interface PreparedTaskGraphValidationInput {
+  readonly resourceCapacities: readonly NamedResourceUnits[];
   readonly rootMaxParallel: number | undefined;
   readonly scopeById: ReadonlyMap<string, PlannedTaskScope>;
   readonly scopes: readonly PlannedTaskScope[];
@@ -8,39 +9,78 @@ interface PreparedTaskGraphValidationInput {
   readonly tasks: readonly PlannedTask[];
 }
 
-interface DependencyPathQuery {
-  readonly requiredDependencyId: string;
+type TaskRelationField = "dependsOn" | "observes";
+
+interface TaskRelationPathQuery {
+  readonly requiredRelatedTaskId: string;
   readonly taskById: ReadonlyMap<string, PlannedTask>;
   readonly taskId: string;
 }
 
-interface DependencyTraversal {
+interface TaskRelationTraversal {
   readonly pending: string[];
-  readonly query: DependencyPathQuery;
+  readonly query: TaskRelationPathQuery;
   readonly visited: Set<string>;
 }
 
-/** Validates dependency and scope relations after graph-shaped input is normalized. */
+/** Validates direct relations and scope structure after graph-shaped input is normalized. */
 export function validatePreparedTaskGraph(input: PreparedTaskGraphValidationInput): void {
-  validateDependencies(input.tasks, input.taskById);
-  validateDependencyCycles(input.tasks, input.taskById);
+  validateResourceClaims(input.resourceCapacities, input.tasks);
+  validateTaskRelations(input.tasks, input.taskById);
+  validateTaskRelationCycles(input.tasks, input.taskById);
   validateScopes(input);
 }
 
-function validateDependencies(
+function validateResourceClaims(
+  capacities: readonly NamedResourceUnits[],
+  tasks: readonly PlannedTask[]
+): void {
+  const capacityByResourceId = new Map(
+    capacities.map(({ resourceId, units }) => [resourceId, units] as const)
+  );
+  for (const task of tasks) {
+    for (const claim of task.resourceClaims) {
+      const capacity = capacityByResourceId.get(claim.resourceId);
+      if (capacity === undefined) {
+        throw new Error(`task ${task.id} claims unknown resource ${claim.resourceId}`);
+      }
+      if (claim.units > capacity) {
+        throw new Error(`task ${task.id} claim exceeds resource capacity: ${claim.resourceId}`);
+      }
+    }
+  }
+}
+
+function validateTaskRelations(
   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}`);
+    validateRelatedTaskIds(task, "dependsOn", task.dependsOn, taskById);
+    validateRelatedTaskIds(task, "observes", task.observes, taskById);
+    for (const dependencyId of task.dependsOn) {
+      if (task.observes.includes(dependencyId)) {
+        throw new Error(`task ${task.id} cannot both depend on and observe task ${dependencyId}`);
       }
     }
   }
 }
 
-function validateDependencyCycles(
+function validateRelatedTaskIds(
+  task: PlannedTask,
+  relation: TaskRelationField,
+  relationTargetIds: readonly string[],
+  taskById: ReadonlyMap<string, PlannedTask>
+): void {
+  const action = relation === "dependsOn" ? "depends on" : "observes";
+  for (const relatedTaskId of relationTargetIds) {
+    if (!taskById.has(relatedTaskId)) {
+      throw new Error(`task ${task.id} ${action} unknown task ${relatedTaskId}`);
+    }
+  }
+}
+
+function validateTaskRelationCycles(
   tasks: readonly PlannedTask[],
   taskById: ReadonlyMap<string, PlannedTask>
 ): void {
@@ -54,12 +94,12 @@ function validateDependencyCycles(
     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}`);
+    for (const relatedTaskId of relatedTaskIds(task)) {
+      const relatedTask = taskById.get(relatedTaskId);
+      if (relatedTask === undefined) {
+        throw new Error(`task ${task.id} relates to unknown task ${relatedTaskId}`);
       }
-      visit(dependencyTask);
+      visit(relatedTask);
     }
     visiting.delete(task.id);
     visited.add(task.id);
@@ -141,36 +181,42 @@ function validateScopeTerminalReachability(
 ): 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}`);
+    if (
+      !isRelatedToTask({ requiredRelatedTaskId: task.id, taskById, taskId: scope.terminalTaskId })
+    ) {
+      throw new Error(`task scope ${scope.id} terminal task must relate to scoped task ${task.id}`);
     }
   }
 }
 
-function dependsOnTask(query: DependencyPathQuery): boolean {
-  return traverseDependencies({
-    pending: [...taskDependencies(query.taskById, query.taskId)],
+function isRelatedToTask(query: TaskRelationPathQuery): boolean {
+  return traverseTaskRelations({
+    pending: [...relatedTaskIdsFor(query.taskById, query.taskId)],
     query,
     visited: new Set()
   });
 }
 
-function traverseDependencies(traversal: DependencyTraversal): boolean {
+function traverseTaskRelations(traversal: TaskRelationTraversal): 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;
+    const relatedTaskId = traversal.pending.pop();
+    if (relatedTaskId === undefined || traversal.visited.has(relatedTaskId)) continue;
+    if (relatedTaskId === traversal.query.requiredRelatedTaskId) return true;
 
-    traversal.visited.add(dependencyId);
-    traversal.pending.push(...taskDependencies(traversal.query.taskById, dependencyId));
+    traversal.visited.add(relatedTaskId);
+    traversal.pending.push(...relatedTaskIdsFor(traversal.query.taskById, relatedTaskId));
   }
   return false;
 }
 
-function taskDependencies(
+function relatedTaskIdsFor(
   taskById: ReadonlyMap<string, PlannedTask>,
   taskId: string
 ): readonly string[] {
   const task = taskById.get(taskId);
-  return task === undefined ? [] : task.dependsOn;
+  return task === undefined ? [] : relatedTaskIds(task);
+}
+
+function relatedTaskIds(task: PlannedTask): readonly string[] {
+  return [...task.dependsOn, ...task.observes];
 }