@zxyycom/vibe-check 0.0.1 → 0.0.3

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

@@ -0,0 +1,105 @@
+import type {
+  AdmissionPolicyMeasurement,
+  SchedulerDecisionMeasurementCumulative,
+  SchedulerMeasurementActionObservation,
+  SchedulerMeasurementEffect,
+  SchedulerMeasurementIntervalContribution,
+  SchedulerMeasurementTiming
+} from "../../../project-definition/project-definition.ts";
+
+type AcceptedPolicyAction =
+  | Readonly<{ readonly kind: "select"; readonly taskId: string }>
+  | Readonly<{ readonly kind: "wait"; readonly taskId: null }>;
+
+type PendingPolicyAction = AcceptedPolicyAction & {
+  readonly baseline: SchedulerMeasurementIntervalContribution;
+  readonly effects: SchedulerMeasurementEffect[];
+  readonly sequence: number;
+};
+
+/** Owns the immutable prefix of observations formed after accepted custom-policy actions. */
+export class SchedulerPolicyMeasurement {
+  #pendingAction: PendingPolicyAction | undefined;
+  #actionSequence = 0;
+  readonly #actionObservations: SchedulerMeasurementActionObservation[] = [];
+
+  public beginSelected(taskId: string, baseline: SchedulerMeasurementIntervalContribution): void {
+    this.#begin(Object.freeze({ kind: "select", taskId }), baseline);
+  }
+
+  public beginWait(baseline: SchedulerMeasurementIntervalContribution): void {
+    this.#begin(Object.freeze({ kind: "wait", taskId: null }), baseline);
+  }
+
+  public recordEffect(effect: SchedulerMeasurementEffect): void {
+    this.#pendingAction?.effects.push(Object.freeze({ ...effect }));
+  }
+
+  public complete(
+    totals: SchedulerMeasurementIntervalContribution,
+    timing: SchedulerMeasurementTiming
+  ): void {
+    const action = this.#pendingAction;
+    if (action === undefined) return;
+    this.#pendingAction = undefined;
+    const interval =
+      timing.availability === "available"
+        ? Object.freeze({
+            availability: "available" as const,
+            contribution: subtractIntervalContribution(totals, action.baseline)
+          })
+        : Object.freeze({ availability: "unavailable" as const, reason: timing.reason });
+    this.#actionObservations.push(completedObservation(action, interval));
+  }
+
+  public snapshot(cumulative: SchedulerDecisionMeasurementCumulative): AdmissionPolicyMeasurement {
+    const endCount = this.#actionObservations.length;
+    const measurementAt = Object.freeze((index: number) => this.#measurementAt(index, endCount));
+    return Object.freeze({ cumulative, measurementAt, measurementCount: endCount });
+  }
+
+  #begin(action: AcceptedPolicyAction, baseline: SchedulerMeasurementIntervalContribution): void {
+    if (this.#pendingAction !== undefined) {
+      throw new Error("previous policy action was not observed before the next action");
+    }
+    const sequence = ++this.#actionSequence;
+    this.#pendingAction = Object.assign({ baseline, effects: [], sequence }, action);
+  }
+
+  #measurementAt(
+    index: number,
+    endCount: number
+  ): SchedulerMeasurementActionObservation | undefined {
+    if (!Number.isSafeInteger(index) || index < 0 || index >= endCount) return undefined;
+    return this.#actionObservations[index];
+  }
+}
+
+function completedObservation(
+  action: PendingPolicyAction,
+  interval: SchedulerMeasurementActionObservation["interval"]
+): SchedulerMeasurementActionObservation {
+  const facts = {
+    effects: Object.freeze([...action.effects]),
+    interval,
+    sequence: action.sequence
+  };
+  return action.kind === "select"
+    ? Object.freeze({ ...facts, kind: "select", taskId: action.taskId })
+    : Object.freeze({ ...facts, kind: "wait", taskId: null });
+}
+
+function subtractIntervalContribution(
+  current: SchedulerMeasurementIntervalContribution,
+  prior: SchedulerMeasurementIntervalContribution
+): SchedulerMeasurementIntervalContribution {
+  return Object.freeze({
+    admissiblePendingTaskMs: current.admissiblePendingTaskMs - prior.admissiblePendingTaskMs,
+    acceptedWaitMs: current.acceptedWaitMs - prior.acceptedWaitMs,
+    capacityBlockedTaskMs: current.capacityBlockedTaskMs - prior.capacityBlockedTaskMs,
+    effectiveCapacitySlotMs: current.effectiveCapacitySlotMs - prior.effectiveCapacitySlotMs,
+    mutexBlockedTaskMs: current.mutexBlockedTaskMs - prior.mutexBlockedTaskMs,
+    rootCapacitySlotMs: current.rootCapacitySlotMs - prior.rootCapacitySlotMs,
+    taskSlotMs: current.taskSlotMs - prior.taskSlotMs
+  });
+}

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

@@ -0,0 +1,175 @@
+import type {
+  SchedulerMeasurementAdmission,
+  SchedulerMeasurementTimingFacts,
+  SchedulerRawMeasurement
+} from "../../../project-definition/project-definition.ts";
+
+const TOP_TASK_LIMIT = 3;
+
+type AdmissionDelaySummary = Readonly<{
+  readonly admissiblePendingMs: number;
+  readonly admissionDelayMs: number;
+  readonly capacityBlockedMs: number;
+  readonly mutexBlockedMs: number;
+  readonly taskActiveMs: number;
+  readonly taskId: string;
+}>;
+
+/** Projects raw Scheduler measurement into the bounded diagnostic summary. */
+export function summaryFromSchedulerMeasurement(
+  raw: SchedulerRawMeasurement
+): Readonly<Record<string, unknown>> {
+  const alwaysAvailable = alwaysAvailableSummary(raw);
+  if (!hasTimingFacts(raw)) return Object.freeze({ ...alwaysAvailable, timing: raw.timing });
+
+  const timingFacts = raw.timingFacts;
+  const delayTotals = admissionDelayTotals(timingFacts.admissions);
+  const lastAdmissionAt = latestAdmissionAt(timingFacts.admissions);
+  return Object.freeze({
+    ...alwaysAvailable,
+    timing: raw.timing,
+    schedulerControlPathMs: timingFacts.schedulerControlPathMs,
+    schedulerDecisionObservationMs: timingFacts.schedulerDecisionObservationMs,
+    schedulerSpanMs: timingFacts.endedAtMonotonicMs - timingFacts.startedAtMonotonicMs,
+    taskSlotMs: timingFacts.taskSlotMs,
+    rootCapacitySlotMs: timingFacts.rootCapacitySlotMs,
+    effectiveCapacitySlotMs: timingFacts.effectiveCapacitySlotMs,
+    rootSlotUtilization: ratio(timingFacts.taskSlotMs, timingFacts.rootCapacitySlotMs),
+    effectiveSlotUtilization: ratio(timingFacts.taskSlotMs, timingFacts.effectiveCapacitySlotMs),
+    acceptedWaitMs: timingFacts.acceptedWaitMs,
+    ...delayTotals,
+    topAdmissionDelays: topAdmissionDelays(timingFacts.admissions),
+    completionTailMs:
+      lastAdmissionAt === null ? null : timingFacts.endedAtMonotonicMs - lastAdmissionAt,
+    topCompletionTailContributors: topCompletionTailContributors(
+      raw.discrete.completionTailActiveTaskIds,
+      timingFacts.admissions,
+      lastAdmissionAt
+    )
+  });
+}
+
+function alwaysAvailableSummary(raw: SchedulerRawMeasurement): Readonly<Record<string, unknown>> {
+  return Object.freeze({
+    declarativeFingerprint: raw.declarativeFingerprint,
+    discrete: Object.freeze({
+      acceptedWaitCount: raw.discrete.acceptedWaitCount,
+      admittedCount: raw.discrete.admittedCount,
+      completionTailActiveTaskCount: raw.discrete.completionTailActiveTaskIds.length,
+      lastSettledTaskId: raw.discrete.lastSettledTaskId,
+      maxRunning: raw.discrete.maxRunning
+    }),
+    peakAdmissionViablePendingTaskCount: raw.peaks.admissionViablePendingTaskCount,
+    peakMutexBlockedTaskCount: raw.peaks.mutexBlockedTaskCount,
+    peakCapacityBlockedTaskCount: raw.peaks.capacityBlockedTaskCount,
+    peakAdmissiblePendingTaskCount: raw.peaks.admissiblePendingTaskCount
+  });
+}
+
+function admissionDelayTotals(admissions: readonly SchedulerMeasurementAdmission[]): Readonly<{
+  readonly admissiblePendingTaskMs: number;
+  readonly admissionViablePendingTaskMs: number;
+  readonly capacityBlockedTaskMs: number;
+  readonly mutexBlockedTaskMs: number;
+}> {
+  let admissiblePendingTaskMs = 0;
+  let capacityBlockedTaskMs = 0;
+  let mutexBlockedTaskMs = 0;
+  for (const admission of admissions) {
+    admissiblePendingTaskMs += admission.admissionDelay.admissiblePendingMs;
+    capacityBlockedTaskMs += admission.admissionDelay.capacityBlockedMs;
+    mutexBlockedTaskMs += admission.admissionDelay.mutexBlockedMs;
+  }
+  return Object.freeze({
+    admissiblePendingTaskMs,
+    admissionViablePendingTaskMs:
+      admissiblePendingTaskMs + capacityBlockedTaskMs + mutexBlockedTaskMs,
+    capacityBlockedTaskMs,
+    mutexBlockedTaskMs
+  });
+}
+
+function topAdmissionDelays(
+  admissions: readonly SchedulerMeasurementAdmission[]
+): readonly AdmissionDelaySummary[] {
+  return Object.freeze(
+    admissions
+      .flatMap((admission) => {
+        if (admission.admittedAtMonotonicMs === null || admission.settledAtMonotonicMs === null) {
+          return [];
+        }
+        return [
+          Object.freeze({
+            admissiblePendingMs: admission.admissionDelay.admissiblePendingMs,
+            admissionDelayMs: admissionDelayMsFor(admission.admissionDelay),
+            capacityBlockedMs: admission.admissionDelay.capacityBlockedMs,
+            mutexBlockedMs: admission.admissionDelay.mutexBlockedMs,
+            taskActiveMs: admission.settledAtMonotonicMs - admission.admittedAtMonotonicMs,
+            taskId: admission.taskId
+          })
+        ];
+      })
+      .sort(
+        (left, right) =>
+          right.admissionDelayMs - left.admissionDelayMs || compareText(left.taskId, right.taskId)
+      )
+      .slice(0, TOP_TASK_LIMIT)
+  );
+}
+
+function latestAdmissionAt(admissions: readonly SchedulerMeasurementAdmission[]): number | null {
+  let latest: number | null = null;
+  for (const admission of admissions) {
+    if (admission.admittedAtMonotonicMs === null) continue;
+    latest = Math.max(latest ?? admission.admittedAtMonotonicMs, admission.admittedAtMonotonicMs);
+  }
+  return latest;
+}
+
+function topCompletionTailContributors(
+  activeTaskIds: readonly string[],
+  admissions: readonly SchedulerMeasurementAdmission[],
+  lastAdmissionAt: number | null
+): readonly Readonly<{ readonly settledAfterLastAdmissionMs: number; readonly taskId: string }>[] {
+  if (lastAdmissionAt === null) return Object.freeze([]);
+  const admittedByTaskId = new Map(admissions.map((admission) => [admission.taskId, admission]));
+  return Object.freeze(
+    activeTaskIds
+      .flatMap((taskId) => {
+        const settledAt = admittedByTaskId.get(taskId)?.settledAtMonotonicMs;
+        return settledAt === undefined || settledAt === null
+          ? []
+          : [Object.freeze({ settledAfterLastAdmissionMs: settledAt - lastAdmissionAt, taskId })];
+      })
+      .sort(
+        (left, right) =>
+          right.settledAfterLastAdmissionMs - left.settledAfterLastAdmissionMs ||
+          compareText(left.taskId, right.taskId)
+      )
+      .slice(0, TOP_TASK_LIMIT)
+  );
+}
+
+function hasTimingFacts(raw: SchedulerRawMeasurement): raw is SchedulerRawMeasurement &
+  Readonly<{
+    readonly timing: Readonly<{ readonly availability: "available" }>;
+    readonly timingFacts: SchedulerMeasurementTimingFacts;
+  }> {
+  return raw.timing.availability === "available";
+}
+
+function ratio(numerator: number, denominator: number): number | null {
+  if (denominator === 0) return null;
+  const value = numerator / denominator;
+  return Number.isFinite(value) && value >= 0 && value <= 1 ? value : null;
+}
+
+function admissionDelayMsFor(breakdown: SchedulerMeasurementAdmission["admissionDelay"]): number {
+  return breakdown.mutexBlockedMs + breakdown.capacityBlockedMs + breakdown.admissiblePendingMs;
+}
+
+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/timing.ts

@@ -0,0 +1,198 @@
+import type {
+  SchedulerMeasurementIntervalContribution,
+  SchedulerMeasurementTiming,
+  SchedulerMeasurementTimingUnavailableReason
+} from "../../../project-definition/project-definition.ts";
+import type { SchedulerPerformanceState } from "./diagnostics.ts";
+import {
+  SchedulerPerformanceIntegrals,
+  type AdmissionDelayBreakdown,
+  type SchedulerPerformancePeaks
+} from "./integrals.ts";
+
+export type SchedulerPerformanceTimingSnapshot = Readonly<{
+  readonly acceptedWaitCount: number;
+  readonly acceptedWaitMs: number;
+  readonly decisionObservationMs: number;
+  readonly maxRunning: number;
+  readonly peaks: SchedulerPerformancePeaks;
+  readonly schedulerControlPathMs: number;
+  readonly startedAtMonotonicMs: number | undefined;
+  readonly timing: SchedulerMeasurementTiming;
+  readonly totals: SchedulerMeasurementIntervalContribution;
+}>;
+
+/** Owns monotonic clock boundaries and delegates numeric interval accumulation. */
+export class SchedulerPerformanceTiming {
+  readonly #clock: Readonly<{ now(): number }>;
+  readonly #integrals = new SchedulerPerformanceIntegrals();
+  #lastBoundaryAt: number | undefined;
+  readonly #startedAt: number | undefined;
+  #lastState: SchedulerPerformanceState;
+  #timing: SchedulerMeasurementTiming = Object.freeze({ availability: "available" });
+  #controlPathMs = 0;
+  #decisionObservationMs = 0;
+  #maxRunning: number;
+  #acceptedWaitStartedAt: number | undefined;
+  #acceptedWaitMs = 0;
+  #acceptedWaitCount = 0;
+
+  public constructor(clock: Readonly<{ now(): number }>, initial: SchedulerPerformanceState) {
+    this.#clock = clock;
+    this.#lastState = initial;
+    this.#maxRunning = initial.running;
+    this.#integrals.installPendingProjection(initial.admissionViablePendingTasks, true);
+    const boundary = this.#sample();
+    if (boundary !== undefined) {
+      this.#lastBoundaryAt = boundary;
+      this.#startedAt = boundary;
+    }
+  }
+
+  /** Accounts a synchronous shell operation, never an await or author callback. */
+  public measureControlPath<T>(operation: () => T): T {
+    const startedAt = this.#sample();
+    try {
+      return operation();
+    } finally {
+      this.#addTiming("control", startedAt, this.#sample());
+    }
+  }
+
+  /** Keeps decision writer work separate from the shell control-path projection. */
+  public observeDecision(observation: () => void): void {
+    const startedAt = this.#sample();
+    try {
+      observation();
+    } catch {
+      // Diagnostic writers are observational; a direct test seam must preserve that containment too.
+    }
+    this.#addTiming("decision-observation", startedAt, this.#sample());
+  }
+
+  public boundary(): number | undefined {
+    const now = this.#sample();
+    if (now === undefined) return undefined;
+    if (this.#lastBoundaryAt !== undefined) this.#addElapsed(now - this.#lastBoundaryAt);
+    this.#lastBoundaryAt = now;
+    return this.#timing.availability === "available" ? now : undefined;
+  }
+
+  public beginAcceptedWait(): void {
+    this.#acceptedWaitCount += 1;
+    const boundary = this.boundary();
+    if (boundary !== undefined && this.#acceptedWaitStartedAt === undefined) {
+      this.#acceptedWaitStartedAt = boundary;
+    }
+  }
+
+  public closeAcceptedWait(boundary: number): void {
+    if (this.#acceptedWaitStartedAt === undefined) return;
+    const elapsedMs = boundary - this.#acceptedWaitStartedAt;
+    if (!validElapsed(elapsedMs)) this.#markUnavailable("interval-invalid");
+    else this.#acceptedWaitMs += elapsedMs;
+    if (!Number.isFinite(this.#acceptedWaitMs)) this.#markUnavailable("integral-invalid");
+    this.#acceptedWaitStartedAt = undefined;
+  }
+
+  public captureState(state: SchedulerPerformanceState): void {
+    this.#lastState = state;
+    this.#maxRunning = Math.max(this.#maxRunning, state.running);
+    this.#integrals.installPendingProjection(
+      state.admissionViablePendingTasks,
+      this.#timing.availability === "available"
+    );
+  }
+
+  public takeAdmissionDelay(taskId: string): AdmissionDelayBreakdown | undefined {
+    return this.#integrals.takeAdmissionDelay(taskId);
+  }
+
+  public pendingAdmissionDelays(): ReturnType<
+    SchedulerPerformanceIntegrals["pendingAdmissionDelays"]
+  > {
+    return this.#integrals.pendingAdmissionDelays();
+  }
+
+  public snapshot(): SchedulerPerformanceTimingSnapshot {
+    const integralTotals = this.#integrals.totals();
+    return Object.freeze({
+      acceptedWaitCount: this.#acceptedWaitCount,
+      acceptedWaitMs: this.#acceptedWaitMs,
+      decisionObservationMs: this.#decisionObservationMs,
+      maxRunning: this.#maxRunning,
+      peaks: this.#integrals.peaks(),
+      schedulerControlPathMs: this.#controlPathMs,
+      startedAtMonotonicMs: this.#startedAt,
+      timing: this.#timing,
+      totals: Object.freeze({ ...integralTotals, acceptedWaitMs: this.#acceptedWaitMs })
+    });
+  }
+
+  public invalidate(reason: SchedulerMeasurementTimingUnavailableReason): void {
+    this.#markUnavailable(reason);
+  }
+
+  #sample(): number | undefined {
+    if (this.#timing.availability === "unavailable") return undefined;
+    try {
+      const now = this.#clock.now();
+      if (!Number.isFinite(now)) {
+        this.#unavailable("clock-non-finite");
+        return undefined;
+      }
+      if (this.#lastBoundaryAt !== undefined && now < this.#lastBoundaryAt) {
+        this.#unavailable("clock-backward");
+        return undefined;
+      }
+      return now;
+    } catch {
+      this.#unavailable("clock-threw");
+      return undefined;
+    }
+  }
+
+  #addTiming(
+    kind: "control" | "decision-observation",
+    startedAt: number | undefined,
+    endedAt: number | undefined
+  ): void {
+    if (startedAt === undefined || endedAt === undefined) return;
+    const elapsedMs = endedAt - startedAt;
+    if (!validElapsed(elapsedMs)) {
+      this.#markUnavailable("interval-invalid");
+      return;
+    }
+    if (kind === "control") this.#controlPathMs += elapsedMs;
+    else this.#decisionObservationMs += elapsedMs;
+    if (!Number.isFinite(this.#controlPathMs) || !Number.isFinite(this.#decisionObservationMs)) {
+      this.#markUnavailable("integral-invalid");
+    }
+  }
+
+  #addElapsed(elapsedMs: number): void {
+    if (!validElapsed(elapsedMs)) {
+      this.#markUnavailable(elapsedMs < 0 ? "clock-backward" : "interval-invalid");
+      return;
+    }
+    if (this.#timing.availability !== "available") return;
+    if (!this.#integrals.addInterval(elapsedMs, this.#lastState)) {
+      this.#markUnavailable("integral-invalid");
+    }
+  }
+
+  #unavailable(reason: SchedulerMeasurementTimingUnavailableReason): undefined {
+    this.#markUnavailable(reason);
+    return undefined;
+  }
+
+  #markUnavailable(reason: SchedulerMeasurementTimingUnavailableReason): void {
+    if (this.#timing.availability === "available") {
+      this.#timing = Object.freeze({ availability: "unavailable", reason });
+    }
+  }
+}
+
+function validElapsed(elapsedMs: number): boolean {
+  return Number.isFinite(elapsedMs) && elapsedMs >= 0;
+}