@zxyycom/vibe-check 0.0.1 → 0.0.2

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

@@ -1,6 +1,12 @@
 import type { PlannedTaskGraph } from "./graph.ts";
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
 
-export type SchedulerSettlementKind = "completed" | "failed" | "blocked" | "cancelled-before-start";
+export type SchedulerSettlementKind =
+  | "completed"
+  | "prerequisite-unsatisfied"
+  | "failed"
+  | "blocked"
+  | "cancelled-before-start";
 
 export type SchedulerTrigger =
   | Readonly<{ readonly kind: "execution-started" }>
@@ -19,7 +25,6 @@ export interface SchedulerSnapshot {
   readonly isAbortRequested: boolean;
   readonly isCancelled: boolean;
   readonly pendingTaskIds: readonly string[];
-  readonly reservationTaskId: string | undefined;
   readonly runningMutexes: readonly string[];
   readonly runningTaskIds: readonly string[];
   readonly settledTasks: readonly Readonly<{
@@ -39,46 +44,48 @@ export interface SchedulerCapacity {
 export interface SchedulerBlockerSummary {
   readonly dependency: number;
   readonly mutex: number;
+  readonly resourceCapacity: number;
   readonly rootCapacity: boolean;
   readonly scopeCapacity: boolean;
 }
 
-export interface SchedulerReservationContext {
-  readonly taskId: string | null;
+/** The sole public Scheduler graph DTO; task identity is always `taskId`. */
+export type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+
+export interface SchedulerAdmissionCandidateFact {
+  readonly canAdmit: boolean;
+  readonly taskId: string;
 }
 
+export type SchedulerAdmissionProposal =
+  | Readonly<{ readonly kind: "select"; readonly taskId: string }>
+  | Readonly<{ readonly kind: "wait" }>;
+
+export type SchedulerAdmissionHardGuard =
+  | Readonly<{
+      readonly canAdmit: true;
+      readonly isCandidate: true;
+      readonly kind: "select";
+      readonly lifecycleOpen: true;
+      readonly taskId: string;
+    }>
+  | Readonly<{ readonly kind: "wait"; readonly runningCanDrain: true }>;
+
 export interface SchedulerDecisionContext {
   readonly blockers: SchedulerBlockerSummary;
   readonly capacity: SchedulerCapacity;
-  readonly reservation: SchedulerReservationContext;
+  readonly graphIdentity: SchedulerGraphSnapshot;
 }
 
-export type ReservationUpdate =
-  | Readonly<{ readonly kind: "unchanged" }>
-  | Readonly<{ readonly kind: "set"; readonly taskId: string }>
-  | Readonly<{ readonly kind: "clear" }>;
-
-export type SchedulerAdmissionReason =
-  | "reservation"
-  | "tightening-scope"
-  | "constrained-continuation"
-  | "canonical-order";
-
-export type SchedulerAwaitReason =
-  | "cancellation-drain"
-  | "dependency-or-mutex"
-  | "running-drain"
-  | "root-capacity"
-  | "active-scope-capacity"
-  | "reserved-tightening-scope";
-
 export type SchedulerDecision = SchedulerDecisionContext &
   (
     | Readonly<{
+        readonly admissionPriority: number;
+        readonly candidates: readonly SchedulerAdmissionCandidateFact[];
         readonly eligibleCount: number;
+        readonly hardGuard: Extract<SchedulerAdmissionHardGuard, { readonly kind: "select" }>;
         readonly kind: "admit";
-        readonly reason: SchedulerAdmissionReason;
-        readonly reservationUpdate: ReservationUpdate;
+        readonly proposal: Extract<SchedulerAdmissionProposal, { readonly kind: "select" }>;
         readonly scopeToActivate: string | null;
         readonly taskId: string;
         readonly trigger: SchedulerTrigger;
@@ -90,10 +97,11 @@ export type SchedulerDecision = SchedulerDecisionContext &
         readonly trigger: SchedulerTrigger;
       }>
     | Readonly<{
+        readonly candidates: readonly SchedulerAdmissionCandidateFact[];
         readonly eligibleCount: number;
+        readonly hardGuard: Extract<SchedulerAdmissionHardGuard, { readonly kind: "wait" }>;
         readonly kind: "await-running";
-        readonly reason: SchedulerAwaitReason;
-        readonly reservationUpdate: ReservationUpdate;
+        readonly proposal: SchedulerAdmissionProposal | null;
         readonly trigger: SchedulerTrigger;
       }>
     | Readonly<{
@@ -108,18 +116,6 @@ export type SchedulerDecision = SchedulerDecisionContext &
       }>
   );
 
-export function reservationUnchanged(): ReservationUpdate {
-  return Object.freeze({ kind: "unchanged" });
-}
-
-export function reservationSet(taskId: string): ReservationUpdate {
-  return Object.freeze({ kind: "set", taskId });
-}
-
-export function reservationClear(): ReservationUpdate {
-  return Object.freeze({ kind: "clear" });
-}
-
 export function freezeDecision(decision: SchedulerDecision): SchedulerDecision {
   const trigger = freezeTrigger(decision.trigger);
   switch (decision.kind) {

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

@@ -1,15 +1,21 @@
+import type { AdmissionSelectionPolicy } from "./admission-selection-policy.ts";
+import type { AdmissionPolicyContext } from "../../project-definition/project-definition.ts";
+import { staticAdmissionSelectionPolicy } from "./admission-selection-policy.ts";
 import { decideAdmission, type SchedulerDecisionCycle } from "./scheduler-admission-decision.ts";
-import {
-  decisionContext,
-  inspectSnapshot,
-  selectBlockedTask
-} from "./scheduler-decision-inspection.ts";
-import { freezeDecision, reservationUnchanged } from "./scheduler-decision-model.ts";
+import { decisionContext } from "./scheduler-decision-inspection.ts";
+import { freezeDecision } from "./scheduler-decision-model.ts";
 import type {
   SchedulerDecision,
   SchedulerSnapshot,
   SchedulerTrigger
 } from "./scheduler-decision-model.ts";
+import {
+  compilePreparedAdmissionGraph,
+  createAdmissionCoreFromSchedulerSnapshot,
+  reconcileAdmissionCore,
+  schedulerInspectionForCore,
+  type AdmissionCoreState
+} from "./admission-core/core.ts";
 
 export type {
   SchedulerDecision,
@@ -25,28 +31,56 @@ export type {
  */
 export function decideScheduler(
   snapshot: SchedulerSnapshot,
-  trigger: SchedulerTrigger
+  trigger: SchedulerTrigger,
+  policy: AdmissionSelectionPolicy = staticAdmissionSelectionPolicy,
+  measurement?: () => AdmissionPolicyContext["measurement"],
+  admissionCore?: AdmissionCoreState
 ): SchedulerDecision {
-  const state = inspectSnapshot(snapshot);
+  const core =
+    admissionCore ??
+    createAdmissionCoreFromSchedulerSnapshot(
+      compilePreparedAdmissionGraph(snapshot.graph, snapshot.maxParallel),
+      snapshot
+    );
+  if (admissionCore === undefined) {
+    const reconciliation = reconcileAdmissionCore(core);
+    const forced = reconciliation.effects.find(
+      (effect) => effect.kind === "settled" && effect.settlementKind === "blocked"
+    );
+    if (forced?.kind === "settled" && forced.settlementKind === "blocked") {
+      return freezeDecision({
+        ...decisionContext(
+          Object.freeze({
+            ...schedulerInspectionForCore(core),
+            isAbortRequested: snapshot.isAbortRequested,
+            isCancelled: snapshot.isCancelled
+          }),
+          core.compiled.graph.schedulerGraphSnapshot
+        ),
+        dependencyIds: forced.dependencyIds ?? [],
+        kind: "settle-blocked",
+        taskId: forced.taskId,
+        trigger
+      });
+    }
+  }
+  const coreInspection = schedulerInspectionForCore(core);
+  const state = Object.freeze({
+    ...coreInspection,
+    isAbortRequested: snapshot.isAbortRequested,
+    isCancelled: snapshot.isCancelled
+  });
   const cycle: SchedulerDecisionCycle = Object.freeze({
-    context: decisionContext(state),
+    admissionCore: core,
+    context: decisionContext(state, state.graph.schedulerGraphSnapshot),
+    policy,
     state,
+    ...(measurement === undefined ? {} : { measurement }),
     trigger
   });
   const terminalDecision = decideTerminalSchedulerAction(cycle, snapshot);
   if (terminalDecision !== undefined) return terminalDecision;
 
-  const blocked = selectBlockedTask(state);
-  if (blocked !== undefined) {
-    return freezeDecision({
-      ...cycle.context,
-      dependencyIds: blocked.dependencyIds,
-      kind: "settle-blocked",
-      taskId: blocked.task.id,
-      trigger
-    });
-  }
-
   return decideAdmission(cycle);
 }
 
@@ -54,14 +88,6 @@ function decideTerminalSchedulerAction(
   cycle: SchedulerDecisionCycle,
   snapshot: SchedulerSnapshot
 ): SchedulerDecision | undefined {
-  if (cycle.state.pendingTasks.length === 0 && cycle.state.runningTaskIds.size === 0) {
-    return freezeDecision({
-      ...cycle.context,
-      cancelled: snapshot.isCancelled,
-      kind: "complete",
-      trigger: cycle.trigger
-    });
-  }
   if (snapshot.isAbortRequested && !snapshot.isCancelled) {
     return freezeDecision({
       ...cycle.context,
@@ -70,6 +96,14 @@ function decideTerminalSchedulerAction(
       trigger: Object.freeze({ kind: "cancellation-observed" })
     });
   }
+  if (cycle.state.pendingTasks.length === 0 && cycle.state.runningTaskIds.length === 0) {
+    return freezeDecision({
+      ...cycle.context,
+      cancelled: snapshot.isCancelled,
+      kind: "complete",
+      trigger: cycle.trigger
+    });
+  }
   if (snapshot.isCancelled) {
     if (cycle.state.pendingTasks.length > 0) {
       throw new Error("cancelled scheduler state retains pending tasks");
@@ -81,23 +115,21 @@ function decideTerminalSchedulerAction(
 }
 
 function cancellationDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {
-  return awaitDrainDecision(cycle, "cancellation-drain");
+  return awaitDrainDecision(cycle);
 }
 
 function runningDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {
-  return awaitDrainDecision(cycle, "running-drain");
+  return awaitDrainDecision(cycle);
 }
 
-function awaitDrainDecision(
-  cycle: SchedulerDecisionCycle,
-  reason: Extract<SchedulerDecision, { readonly kind: "await-running" }>["reason"]
-): SchedulerDecision {
+function awaitDrainDecision(cycle: SchedulerDecisionCycle): SchedulerDecision {
   return freezeDecision({
     ...cycle.context,
+    candidates: Object.freeze([]),
     eligibleCount: 0,
+    hardGuard: Object.freeze({ kind: "wait", runningCanDrain: true }),
     kind: "await-running",
-    reason,
-    reservationUpdate: reservationUnchanged(),
+    proposal: null,
     trigger: cycle.trigger
   });
 }

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

@@ -0,0 +1,124 @@
+import { createHash } from "node:crypto";
+
+import { diagnosticTags, type DiagnosticObservation } from "../diagnostic-logging/logger.ts";
+import type { SchedulerDecision } from "./scheduler-decision.ts";
+import type { SchedulerState } from "./execution-state.ts";
+import {
+  schedulerInspectionForCore,
+  validateAdmissionCoreSelection
+} from "./admission-core/core.ts";
+import type {
+  AdmissionViablePendingTask,
+  SchedulerPerformanceDiagnostics,
+  SchedulerPerformanceState
+} from "./measurement/diagnostics.ts";
+import type { AdmissionPolicyFault } from "./scheduler-admission-decision.ts";
+
+/** Fault logging is observational and therefore excluded from Scheduler control-path timing. */
+export function observeAdmissionPolicyFault<TResult>(
+  state: SchedulerState<TResult>,
+  fault: AdmissionPolicyFault
+): void {
+  observeSchedulerDiagnostic(state, {
+    event: "scheduler.admission-policy-failed",
+    tags: diagnosticTags("ADMISSION_POLICY_FAILED", fault.category.toUpperCase()),
+    details: Object.freeze({ category: fault.category })
+  });
+}
+
+export function observeSchedulerDecision<TResult>(
+  state: SchedulerState<TResult>,
+  decision: SchedulerDecision,
+  diagnostics: SchedulerPerformanceDiagnostics | undefined
+): void {
+  const observation: DiagnosticObservation = {
+    event: "scheduler.decision",
+    tags: schedulerDecisionTags(decision),
+    details: schedulerDecisionDetails(decision)
+  };
+  const observe = () => observeSchedulerDiagnostic(state, observation);
+  if (diagnostics === undefined) observe();
+  else diagnostics.observeDecision(observe);
+}
+
+/** One immutable graph record makes the enclosing scheduler channel the self-contained evidence unit. */
+export function observeSchedulerGraph<TResult>(state: SchedulerState<TResult>): void {
+  const graph = state.graph.schedulerGraphSnapshot;
+  observeSchedulerDiagnostic(state, {
+    event: "scheduler.graph",
+    tags: diagnosticTags("GRAPH"),
+    details: Object.freeze({ graph, graphFingerprint: schedulerGraphFingerprint(graph) })
+  });
+}
+
+export function schedulerGraphFingerprint(graph: unknown): string {
+  return createHash("sha256").update(JSON.stringify(graph)).digest("hex");
+}
+
+function schedulerDecisionDetails(decision: SchedulerDecision): Readonly<Record<string, unknown>> {
+  const { graphIdentity, ...dynamicFacts } = decision;
+  return Object.freeze({
+    ...dynamicFacts,
+    graphFingerprint: schedulerGraphFingerprint(graphIdentity)
+  });
+}
+
+/** Logger failures are observational and must not revise Scheduler lifecycle state. */
+export function observeSchedulerDiagnostic<TResult>(
+  state: SchedulerState<TResult>,
+  observation: DiagnosticObservation
+): void {
+  try {
+    state.diagnosticLogger?.observe(observation);
+  } catch {
+    // Invocation logging has its own containment; retain it for direct Scheduler seams as well.
+  }
+}
+
+export function performanceState<TResult>(
+  state: SchedulerState<TResult>
+): SchedulerPerformanceState {
+  const inspection = schedulerInspectionForCore(state.admissionCore);
+  const admissionViablePendingTasks: AdmissionViablePendingTask[] = [];
+  for (const task of inspection.pendingTasks) {
+    const validation = validateAdmissionCoreSelection(state.admissionCore, task.id);
+    if (validation.accepted) {
+      admissionViablePendingTasks.push(
+        Object.freeze({ kind: "admissible-pending", taskId: task.id })
+      );
+      continue;
+    }
+    switch (validation.reason.kind) {
+      case "mutex-held":
+        admissionViablePendingTasks.push(Object.freeze({ kind: "mutex-blocked", taskId: task.id }));
+        continue;
+      case "root-capacity-reached":
+      case "scope-capacity-reached":
+      case "resource-capacity-insufficient":
+        admissionViablePendingTasks.push(
+          Object.freeze({ kind: "capacity-blocked", taskId: task.id })
+        );
+        continue;
+      case "depends-on-pending":
+      case "observes-pending":
+        continue;
+      case "not-pending":
+      case "state-complete":
+      case "unknown-task":
+        throw new Error("shared admission core disagrees with Scheduler pending state");
+    }
+  }
+  return Object.freeze({
+    admissionViablePendingTasks: Object.freeze(admissionViablePendingTasks),
+    effectiveMaxParallel: inspection.effectiveMaxParallel,
+    rootMaxParallel: inspection.maxParallel,
+    running: inspection.runningTaskIds.length
+  });
+}
+
+function schedulerDecisionTags(decision: SchedulerDecision): readonly string[] {
+  return diagnosticTags(
+    decision.kind.toUpperCase(),
+    ...("taskId" in decision ? [`TASK:${decision.taskId}`] : [])
+  );
+}

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

@@ -0,0 +1,150 @@
+import type { PlannedTask } from "./graph.ts";
+import {
+  cancelPendingTasks,
+  recordSettlement,
+  type RunningTaskCompletion,
+  type RunTaskGraphOptions,
+  type SchedulerState,
+  type TaskGraphRun,
+  type TaskSettlement
+} from "./execution-state.ts";
+import type { SchedulerDecision } from "./scheduler-decision.ts";
+import type { AdmissionPolicyFault } from "./scheduler-admission-decision.ts";
+
+export function applyAdmissionPolicyFault<TResult>(
+  state: SchedulerState<TResult>,
+  fault: AdmissionPolicyFault
+): void {
+  if (state.admissionPolicyFault !== undefined) {
+    throw new Error("scheduler received more than one admission policy fault");
+  }
+  state.admissionPolicyFault = fault.category;
+  cancelPendingTasks(state);
+}
+
+export function applyAdmission<TResult>(
+  state: SchedulerState<TResult>,
+  decision: Extract<SchedulerDecision, { readonly kind: "admit" }>
+): void {
+  const task = takePendingTask(state, decision.taskId, "admission");
+  for (const mutex of task.mutex) state.runningMutexes.add(mutex);
+  activateScope(state, decision.scopeToActivate);
+
+  const completion = Promise.resolve()
+    .then(() => state.execute(task, Object.freeze({ signal: state.signal })))
+    .then((value) => completedTaskCompletion(task.id, value, state.isPrerequisiteSatisfied))
+    .catch((error: unknown) => failedTaskCompletion<TResult>(task.id, error));
+  state.runningById.set(task.id, { task, completion });
+}
+
+export function applyBlockedSettlement<TResult>(
+  state: SchedulerState<TResult>,
+  decision: Extract<SchedulerDecision, { readonly kind: "settle-blocked" }>
+): void {
+  applyForcedBlockedSettlement(state, decision.taskId, decision.dependencyIds);
+}
+
+/** Applies one canonical private forced-block effect after the shared reducer selected it. */
+export function applyForcedBlockedSettlement<TResult>(
+  state: SchedulerState<TResult>,
+  taskId: string,
+  dependencyIds: readonly string[]
+): void {
+  const task = takePendingTask(state, taskId, "blocked settlement");
+  recordSettlement(
+    state,
+    task,
+    Object.freeze({ kind: "blocked", dependencyIds: Object.freeze([...dependencyIds]) })
+  );
+  state.onTaskBlocked?.(task, dependencyIds);
+}
+
+export function applyCancellation<TResult>(
+  state: SchedulerState<TResult>,
+  decision: Extract<SchedulerDecision, { readonly kind: "cancel-pending" }>
+): void {
+  const pendingTaskIds = state.pending.map((task) => task.id);
+  if (!sameTaskIds(pendingTaskIds, decision.taskIds)) {
+    throw new Error("scheduler cancellation decision no longer matches pending tasks");
+  }
+  cancelPendingTasks(state);
+}
+
+export async function nextRunningSettlement<TResult>(
+  state: SchedulerState<TResult>
+): Promise<RunningTaskCompletion<TResult>> {
+  if (state.runningById.size === 0) {
+    throw new Error("scheduler cannot await a task when no task is running");
+  }
+  return Promise.race([...state.runningById.values()].map((running) => running.completion));
+}
+
+export function settleRunningTask<TResult>(
+  state: SchedulerState<TResult>,
+  result: RunningTaskCompletion<TResult>
+): void {
+  const running = state.runningById.get(result.taskId);
+  if (running === undefined) throw new Error(`task ${result.taskId} settled without admission`);
+  state.runningById.delete(result.taskId);
+  for (const mutex of running.task.mutex) state.runningMutexes.delete(mutex);
+  recordSettlement(state, running.task, result.settlement);
+}
+
+export function buildTaskGraphRun<TResult>(state: SchedulerState<TResult>): TaskGraphRun<TResult> {
+  return Object.freeze({
+    admissionPolicyFault: state.admissionPolicyFault,
+    cancelled: state.isCancelled,
+    settlements: Object.freeze(
+      state.graph.tasks.map((task) => {
+        const settlement = state.settlementsByTaskId.get(task.id);
+        if (settlement === undefined) throw new Error(`task ${task.id} was not settled`);
+        return Object.freeze({ task, settlement });
+      })
+    )
+  });
+}
+
+function activateScope<TResult>(state: SchedulerState<TResult>, scopeId: string | null): void {
+  if (scopeId === null) return;
+  const scope = state.scopesById.get(scopeId);
+  if (scope === undefined) {
+    throw new Error(`scheduler admission references unknown scope ${scopeId}`);
+  }
+  scope.isActive = true;
+}
+
+function takePendingTask<TResult>(
+  state: SchedulerState<TResult>,
+  taskId: string,
+  action: string
+): PlannedTask {
+  const index = state.pending.findIndex((task) => task.id === taskId);
+  if (index < 0) throw new Error(`task ${taskId} is not pending for ${action}`);
+  const [task] = state.pending.splice(index, 1);
+  if (task === undefined) throw new Error(`task ${taskId} disappeared during ${action}`);
+  return task;
+}
+
+function completedTaskCompletion<TResult>(
+  taskId: string,
+  value: TResult,
+  isPrerequisiteSatisfied: RunTaskGraphOptions<TResult>["isPrerequisiteSatisfied"]
+): RunningTaskCompletion<TResult> {
+  const settlement: TaskSettlement<TResult> =
+    isPrerequisiteSatisfied?.(value) === false
+      ? { kind: "prerequisite-unsatisfied", value }
+      : { kind: "completed", value };
+  return Object.freeze({ taskId, settlement: Object.freeze(settlement) });
+}
+
+function failedTaskCompletion<TResult>(
+  taskId: string,
+  error: unknown
+): RunningTaskCompletion<TResult> {
+  const settlement: TaskSettlement<TResult> = { kind: "failed", error };
+  return Object.freeze({ taskId, settlement: Object.freeze(settlement) });
+}
+
+function sameTaskIds(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((taskId, index) => taskId === right[index]);
+}

package/src/project-run/task-scheduler/scheduler-terminal-measurement.ts

@@ -0,0 +1,95 @@
+import type {
+  SchedulerMeasurementContext,
+  SchedulerMeasurementHook,
+  SchedulerRawMeasurement
+} from "../../project-definition/project-definition.ts";
+import { diagnosticTags } from "../diagnostic-logging/logger.ts";
+import type { RunTaskGraphOptions, SchedulerState } from "./execution-state.ts";
+import type { SchedulerPerformanceDiagnostics } from "./measurement/diagnostics.ts";
+import { observeSchedulerDiagnostic } from "./scheduler-observation.ts";
+
+/** Delivers the terminal measurement to the internal summary and caller hooks exactly once. */
+export async function observeTerminalMeasurement<TResult>(
+  input: Readonly<{
+    readonly diagnostics: SchedulerPerformanceDiagnostics;
+    readonly options: RunTaskGraphOptions<TResult>;
+    readonly state: SchedulerState<TResult>;
+  }>
+): Promise<SchedulerMeasurementContext> {
+  input.diagnostics.completePendingActionObservation();
+  const context = measurementContext(
+    input.state,
+    input.diagnostics.admittedTaskIds(),
+    input.diagnostics.rawMeasurement()
+  );
+  const callerHooks = input.options.measurementHooks ?? [];
+  let callerHookFailed = false;
+  const callerFailure = () => {
+    callerHookFailed = true;
+    observeSchedulerDiagnostic(input.state, {
+      event: "scheduler.measurement-hook-failed",
+      tags: diagnosticTags("MEASUREMENT_HOOK_FAILED"),
+      details: Object.freeze({})
+    });
+    try {
+      input.options.onMeasurementHookFailure?.();
+    } catch {
+      // A failure-reporting seam cannot revise terminal Scheduler facts either.
+    }
+  };
+  const defaultHook = input.diagnostics.defaultSummaryHook();
+  const deliveries: readonly TerminalMeasurementDelivery[] = Object.freeze([
+    ...(defaultHook === undefined
+      ? []
+      : [Object.freeze({ hook: defaultHook, onFailure: () => undefined })]),
+    ...callerHooks.map((hook) => Object.freeze({ hook, onFailure: callerFailure }))
+  ]);
+  await deliverTerminalMeasurementHooks(deliveries, context);
+  if (callerHooks.length > 0 && !callerHookFailed) {
+    try {
+      input.options.onMeasurementHooksSettled?.();
+    } catch {
+      // A success-reporting seam cannot revise terminal Scheduler facts either.
+    }
+  }
+  return context;
+}
+
+type TerminalMeasurementDelivery = Readonly<{
+  readonly hook: SchedulerMeasurementHook;
+  readonly onFailure: () => void;
+}>;
+
+async function deliverTerminalMeasurementHooks(
+  deliveries: readonly TerminalMeasurementDelivery[],
+  context: SchedulerMeasurementContext
+): Promise<void> {
+  for (const delivery of deliveries) {
+    try {
+      await delivery.hook(context);
+    } catch {
+      delivery.onFailure();
+    }
+  }
+}
+
+function measurementContext<TResult>(
+  state: SchedulerState<TResult>,
+  admittedTaskIds: readonly string[],
+  rawMeasurement: SchedulerRawMeasurement
+): SchedulerMeasurementContext {
+  return Object.freeze({
+    graph: state.graph.schedulerGraphSnapshot,
+    execution: Object.freeze({
+      admittedTaskIds: Object.freeze([...admittedTaskIds]),
+      settledTasks: Object.freeze(
+        state.graph.tasks.map((task) => {
+          const settlement = state.settlementsByTaskId.get(task.id);
+          if (settlement === undefined) throw new Error(`task ${task.id} was not settled`);
+          return Object.freeze({ kind: settlement.kind, taskId: task.id });
+        })
+      )
+    }),
+    rawMeasurement
+  });
+}