@zxyycom/vibe-check 0.0.1 → 0.0.2

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];
 }

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

@@ -1,9 +1,19 @@
 import { validatePreparedTaskGraph } from "./graph-validation.ts";
+import type { SchedulerGraphSnapshot } from "../../project-definition/project-definition.ts";
+import { snapshotClosedRecord } from "../../data-boundary/closed-values.ts";
+
+export interface NamedResourceUnits {
+  readonly resourceId: string;
+  readonly units: number;
+}
 
 export interface TaskNode {
+  readonly admissionPriority?: number;
   readonly id: string;
   readonly dependsOn?: readonly string[];
   readonly mutex?: readonly string[];
+  readonly observes?: readonly string[];
+  readonly resourceClaims?: Readonly<Record<string, number>>;
   readonly scopeId?: string;
 }
 
@@ -20,14 +30,18 @@ export interface TaskScope {
 }
 
 export interface TaskGraph {
+  readonly resourceCapacities?: Readonly<Record<string, number>>;
   readonly tasks: readonly TaskNode[];
   readonly scopes?: readonly TaskScope[];
 }
 
 export interface PlannedTask {
+  readonly admissionPriority: number;
   readonly id: string;
   readonly dependsOn: readonly string[];
   readonly mutex: readonly string[];
+  readonly observes: readonly string[];
+  readonly resourceClaims: readonly NamedResourceUnits[];
   readonly scopeId: string | undefined;
 }
 
@@ -39,12 +53,23 @@ export interface PlannedTaskScope {
 }
 
 export interface PlannedTaskGraph {
+  readonly resourceCapacities: readonly NamedResourceUnits[];
+  /** Immutable public projection shared by every decision and terminal measurement in one run. */
+  readonly schedulerGraphSnapshot: SchedulerGraphSnapshot;
   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_GRAPH_KEYS = ["resourceCapacities", "tasks", "scopes"] as const;
+const TASK_NODE_KEYS = [
+  "admissionPriority",
+  "id",
+  "dependsOn",
+  "mutex",
+  "observes",
+  "resourceClaims",
+  "scopeId"
+] as const;
 const TASK_SCOPE_KEYS = ["id", "maxParallel", "activationTaskIds", "terminalTaskId"] as const;
 
 /** Validates untrusted graph-shaped input without admitting it to scheduler execution. */
@@ -54,19 +79,65 @@ export function validateTaskGraph(graph: unknown): void {
 
 export function prepareTaskGraph(graph: unknown, rootMaxParallel?: number): PlannedTaskGraph {
   const data = record(graph, "task graph", TASK_GRAPH_KEYS);
+  const resourceCapacities = resourceMapping(
+    data.resourceCapacities,
+    "task graph resourceCapacities"
+  );
   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 });
+  validatePreparedTaskGraph({
+    resourceCapacities,
+    rootMaxParallel,
+    scopeById,
+    scopes,
+    taskById,
+    tasks
+  });
 
   return Object.freeze({
+    resourceCapacities,
+    schedulerGraphSnapshot: schedulerGraphSnapshot(tasks, scopes, resourceCapacities),
     tasks: Object.freeze(tasks),
     scopes: Object.freeze(scopes)
   });
 }
 
+function schedulerGraphSnapshot(
+  tasks: readonly PlannedTask[],
+  scopes: readonly PlannedTaskScope[],
+  resourceCapacities: readonly NamedResourceUnits[]
+): SchedulerGraphSnapshot {
+  return Object.freeze({
+    resourceCapacities,
+    scopes: Object.freeze(
+      scopes.map((scope) =>
+        Object.freeze({
+          activationTaskIds: Object.freeze([...scope.activationTaskIds]),
+          id: scope.id,
+          maxParallel: scope.maxParallel,
+          terminalTaskId: scope.terminalTaskId
+        })
+      )
+    ),
+    tasks: Object.freeze(
+      tasks.map((task) =>
+        Object.freeze({
+          admissionPriority: task.admissionPriority,
+          dependsOn: Object.freeze([...task.dependsOn]),
+          mutex: Object.freeze([...task.mutex]),
+          observes: Object.freeze([...task.observes]),
+          resourceClaims: task.resourceClaims,
+          scopeId: task.scopeId ?? null,
+          taskId: task.id
+        })
+      )
+    )
+  });
+}
+
 function normalizeTasks(value: unknown): PlannedTask[] {
   if (!Array.isArray(value)) {
     throw new TypeError("task graph tasks must be an array");
@@ -81,12 +152,16 @@ function normalizeTasks(value: unknown): PlannedTask[] {
       throw new TypeError(`duplicate task id: ${id}`);
     }
     ids.add(id);
+    const admissionPriority = admissionPriorityOrDefault(data.admissionPriority, id);
     const scopeId = optionalNonEmptyString(data.scopeId, `task ${id}.scopeId`);
     tasks.push(
       Object.freeze({
+        admissionPriority,
         id,
         dependsOn: Object.freeze(stringList(data.dependsOn, `task ${id}.dependsOn`)),
         mutex: Object.freeze(stringList(data.mutex, `task ${id}.mutex`)),
+        observes: Object.freeze(stringList(data.observes, `task ${id}.observes`)),
+        resourceClaims: resourceMapping(data.resourceClaims, `task ${id}.resourceClaims`),
         scopeId
       })
     );
@@ -177,9 +252,42 @@ function requiredStringList(value: unknown, fieldName: string): string[] {
   return stringList(value, fieldName);
 }
 
+function resourceMapping(value: unknown, fieldName: string): readonly NamedResourceUnits[] {
+  if (value === undefined) return Object.freeze([]);
+  const data = snapshotClosedRecord(value);
+  if (data === undefined) throw new TypeError(`${fieldName} must be a closed object`);
+  const entries: NamedResourceUnits[] = [];
+  for (const resourceId of Object.keys(data).sort(compareText)) {
+    if (resourceId.trim().length === 0) {
+      throw new TypeError(`${fieldName} resource ids must be non-empty strings`);
+    }
+    entries.push(
+      Object.freeze({
+        resourceId,
+        units: positiveSafeInteger(data[resourceId], `${fieldName}.${resourceId}`)
+      })
+    );
+  }
+  return Object.freeze(entries);
+}
+
 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;
 }
+
+function admissionPriorityOrDefault(value: unknown, taskId: string): number {
+  if (value === undefined) return 0;
+  if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+    throw new TypeError(`task ${taskId}.admissionPriority must be a safe integer`);
+  }
+  return value;
+}
+
+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/measurement/diagnostics.ts

@@ -0,0 +1,261 @@
+import type {
+  AdmissionPolicyMeasurement,
+  SchedulerDecisionMeasurementCumulative,
+  SchedulerMeasurementAdmission,
+  SchedulerMeasurementEffect,
+  SchedulerMeasurementHook,
+  SchedulerRawMeasurement
+} from "../../../project-definition/project-definition.ts";
+import { diagnosticTags, type DiagnosticLogger } from "../../diagnostic-logging/logger.ts";
+import type { AdmissionDelayBreakdown } from "./integrals.ts";
+import { summaryFromSchedulerMeasurement } from "./summary.ts";
+import { SchedulerPerformanceTiming } from "./timing.ts";
+import { SchedulerPolicyMeasurement } from "./policy.ts";
+
+/** Explicit, enabled-only private handoff; the Scheduler never infers this from logger behavior. */
+export type SchedulerPerformanceDiagnosticsInput = Readonly<{
+  readonly clock: Readonly<{ now(): number }>;
+  readonly declarativeFingerprint: string;
+  readonly logger?: DiagnosticLogger;
+}>;
+
+type AdmissionChronology = {
+  readonly admissionDelay: AdmissionDelayBreakdown;
+  readonly admittedAt: number;
+  settledAt: number | undefined;
+};
+
+export type AdmissionViablePendingTask = Readonly<{
+  readonly kind: "admissible-pending" | "capacity-blocked" | "mutex-blocked";
+  readonly taskId: string;
+}>;
+
+export type SchedulerPerformanceState = Readonly<{
+  readonly admissionViablePendingTasks: readonly AdmissionViablePendingTask[];
+  readonly effectiveMaxParallel: number;
+  readonly rootMaxParallel: number;
+  readonly running: number;
+}>;
+
+/**
+ * Scheduler-owned, invocation-local lifecycle projection. Clock boundaries and
+ * numeric interval accumulation remain private collaborators of this owner.
+ */
+export class SchedulerPerformanceDiagnostics {
+  readonly #declarativeFingerprint: string;
+  readonly #logger: DiagnosticLogger | undefined;
+  readonly #timing: SchedulerPerformanceTiming;
+  #lastSettledTaskId: string | undefined;
+  #completionTailActiveTaskIds: readonly string[] = Object.freeze([]);
+  readonly #admittedTaskIds = new Set<string>();
+  readonly #chronologyByTaskId = new Map<string, AdmissionChronology>();
+  readonly #policyMeasurement = new SchedulerPolicyMeasurement();
+
+  public constructor(
+    input: SchedulerPerformanceDiagnosticsInput,
+    initial: SchedulerPerformanceState
+  ) {
+    this.#declarativeFingerprint = input.declarativeFingerprint;
+    this.#logger = input.logger;
+    this.#timing = new SchedulerPerformanceTiming(input.clock, initial);
+  }
+
+  public measureControlPath<T>(operation: () => T): T {
+    return this.#timing.measureControlPath(operation);
+  }
+
+  public observeDecision(observation: () => void): void {
+    this.#timing.observeDecision(observation);
+  }
+
+  /** Flushes the old state before admission changes the real Scheduler state. */
+  public beforeAdmission(taskId: string, runningTaskIds: readonly string[]): void {
+    this.#admittedTaskIds.add(taskId);
+    this.#completionTailActiveTaskIds = Object.freeze([...runningTaskIds, taskId]);
+    const boundary = this.#timing.boundary();
+    if (boundary === undefined) return;
+    const admissionDelay = this.#timing.takeAdmissionDelay(taskId);
+    if (admissionDelay === undefined) return this.#timing.invalidate("integral-invalid");
+    this.#chronologyByTaskId.set(taskId, {
+      admissionDelay,
+      admittedAt: boundary,
+      settledAt: undefined
+    });
+  }
+
+  /** Flushes the old state before blocked/cancelled changes the real Scheduler state. */
+  public beforePendingSettlement(taskIds: readonly string[] = []): void {
+    const lastTaskId = taskIds.at(-1);
+    if (lastTaskId !== undefined) this.#lastSettledTaskId = lastTaskId;
+    this.#timing.boundary();
+  }
+
+  /** Flushes the old running interval before removing the actual running Task. */
+  public beforeRunningSettlement(taskId: string): void {
+    this.#lastSettledTaskId = taskId;
+    const boundary = this.#timing.boundary();
+    if (boundary === undefined) return;
+    this.#timing.closeAcceptedWait(boundary);
+    const chronology = this.#chronologyByTaskId.get(taskId);
+    if (chronology === undefined) return this.#timing.invalidate("integral-invalid");
+    chronology.settledAt = boundary;
+  }
+
+  public beforeAcceptedWait(): void {
+    this.#timing.beginAcceptedWait();
+  }
+
+  public captureState(state: SchedulerPerformanceState): void {
+    this.#timing.captureState(state);
+  }
+
+  public rawMeasurement(): SchedulerRawMeasurement {
+    return this.#measurement(true);
+  }
+
+  public beginSelectedPolicyAction(taskId: string): void {
+    this.#policyMeasurement.beginSelected(taskId, this.#timing.snapshot().totals);
+  }
+
+  public beginWaitPolicyAction(): void {
+    this.#policyMeasurement.beginWait(this.#timing.snapshot().totals);
+  }
+
+  public recordEffect(effect: SchedulerMeasurementEffect): void {
+    this.#policyMeasurement.recordEffect(effect);
+  }
+
+  public policyMeasurement(): AdmissionPolicyMeasurement {
+    this.#timing.boundary();
+    this.#completePolicyAction();
+    return this.#policyMeasurement.snapshot(this.#cumulativeMeasurement());
+  }
+
+  public completePendingActionObservation(): void {
+    this.#timing.boundary();
+    this.#completePolicyAction();
+  }
+
+  public admittedTaskIds(): readonly string[] {
+    return Object.freeze([...this.#admittedTaskIds]);
+  }
+
+  /** Internal default terminal hook; it contains writer failure without runner special-casing. */
+  public defaultSummaryHook(): SchedulerMeasurementHook | undefined {
+    if (this.#logger === undefined) return undefined;
+    const logger = this.#logger;
+    return (context) => {
+      try {
+        logger.observe({
+          event: "scheduler.summary",
+          tags: diagnosticTags("SUMMARY"),
+          details: summaryFromSchedulerMeasurement(context.rawMeasurement)
+        });
+      } catch {
+        // Summary writer failure is contained by this hook, not the shared runner.
+      }
+    };
+  }
+
+  #completePolicyAction(): void {
+    const timing = this.#timing.snapshot();
+    this.#policyMeasurement.complete(timing.totals, timing.timing);
+  }
+
+  #cumulativeMeasurement(): SchedulerDecisionMeasurementCumulative {
+    const snapshot = this.#timing.snapshot();
+    const facts = Object.freeze({
+      declarativeFingerprint: this.#declarativeFingerprint,
+      discrete: Object.freeze({
+        acceptedWaitCount: snapshot.acceptedWaitCount,
+        admittedCount: this.#admittedTaskIds.size,
+        maxRunning: snapshot.maxRunning
+      }),
+      peaks: snapshot.peaks
+    });
+    if (snapshot.timing.availability === "unavailable") {
+      return Object.freeze({ ...facts, timing: snapshot.timing });
+    }
+    return Object.freeze({
+      ...facts,
+      timing: snapshot.timing,
+      timingFacts: Object.freeze({
+        acceptedWaitMs: snapshot.acceptedWaitMs,
+        effectiveCapacitySlotMs: snapshot.totals.effectiveCapacitySlotMs,
+        rootCapacitySlotMs: snapshot.totals.rootCapacitySlotMs,
+        taskSlotMs: snapshot.totals.taskSlotMs
+      })
+    });
+  }
+
+  #measurement(terminal: boolean): SchedulerRawMeasurement {
+    const endedAt = this.#timing.boundary();
+    if (terminal && endedAt !== undefined) this.#timing.closeAcceptedWait(endedAt);
+    const snapshot = this.#timing.snapshot();
+    const facts = Object.freeze({
+      declarativeFingerprint: this.#declarativeFingerprint,
+      discrete: Object.freeze({
+        acceptedWaitCount: snapshot.acceptedWaitCount,
+        admittedCount: this.#admittedTaskIds.size,
+        completionTailActiveTaskIds: Object.freeze([...this.#completionTailActiveTaskIds]),
+        lastSettledTaskId: this.#lastSettledTaskId ?? null,
+        maxRunning: snapshot.maxRunning
+      }),
+      peaks: snapshot.peaks
+    });
+    if (snapshot.timing.availability === "unavailable") {
+      return Object.freeze({ ...facts, timing: snapshot.timing });
+    }
+    if (endedAt === undefined)
+      throw new Error("available Scheduler timing has no terminal boundary");
+    return Object.freeze({
+      ...facts,
+      timing: snapshot.timing,
+      timingFacts: Object.freeze({
+        acceptedWaitMs: snapshot.acceptedWaitMs,
+        admissions: Object.freeze(this.#admissionMeasurements()),
+        effectiveCapacitySlotMs: snapshot.totals.effectiveCapacitySlotMs,
+        endedAtMonotonicMs: endedAt,
+        rootCapacitySlotMs: snapshot.totals.rootCapacitySlotMs,
+        schedulerControlPathMs: snapshot.schedulerControlPathMs,
+        schedulerDecisionObservationMs: snapshot.decisionObservationMs,
+        startedAtMonotonicMs: snapshot.startedAtMonotonicMs ?? endedAt,
+        taskSlotMs: snapshot.totals.taskSlotMs
+      })
+    });
+  }
+
+  #admissionMeasurements(): SchedulerMeasurementAdmission[] {
+    const pendingByTaskId = new Map(
+      this.#timing
+        .pendingAdmissionDelays()
+        .map(({ admissionDelay, taskId }) => [taskId, admissionDelay])
+    );
+    const taskIds = new Set([...pendingByTaskId.keys(), ...this.#chronologyByTaskId.keys()]);
+    return [...taskIds]
+      .map((taskId) => this.#admissionMeasurement(taskId, pendingByTaskId))
+      .sort((left, right) => compareText(left.taskId, right.taskId));
+  }
+
+  #admissionMeasurement(
+    taskId: string,
+    pendingByTaskId: ReadonlyMap<string, AdmissionDelayBreakdown>
+  ): SchedulerMeasurementAdmission {
+    const chronology = this.#chronologyByTaskId.get(taskId);
+    const admissionDelay = chronology?.admissionDelay ?? pendingByTaskId.get(taskId);
+    if (admissionDelay === undefined)
+      throw new Error(`missing admission measurement for ${taskId}`);
+    return Object.freeze({
+      admissionDelay,
+      admittedAtMonotonicMs: chronology?.admittedAt ?? null,
+      settledAtMonotonicMs: chronology?.settledAt ?? null,
+      taskId
+    });
+  }
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}