@zxyycom/vibe-check 0.0.1 → 0.0.3

package/src/package-tools/learned-critical-path/duration-model/prediction.ts

@@ -0,0 +1,184 @@
+import { createHash } from "node:crypto";
+
+import {
+  canonicalJsonBytes,
+  type CanonicalJsonValue
+} from "../../../data-boundary/canonical-data.ts";
+import {
+  SCHEDULER_HISTORY_MODEL_VERSION,
+  schedulerHistorySeries,
+  type SchedulerHistoryModel
+} from "./bounded-history.ts";
+
+export type SchedulerPredictionSource = "learned" | "project-prior" | "cold-start";
+
+export interface SchedulerPredictionInput {
+  readonly authoredOptions: CanonicalJsonValue;
+  readonly checkId: string;
+  readonly flags: CanonicalJsonValue;
+  readonly taskId: string;
+}
+
+export interface SchedulerTaskPrediction {
+  readonly estimatedDurationMs: number;
+  readonly identityDigest: string;
+  readonly meanDurationMs: number | null;
+  readonly p90DurationMs: number | null;
+  readonly sampleCount: number;
+  readonly source: SchedulerPredictionSource;
+  readonly taskId: string;
+}
+
+/** Frozen before Scheduler admission; it does not retain authored options or flag values. */
+export interface SchedulerPredictionSnapshot {
+  readonly digest: string;
+  readonly modelVersion: string;
+  readonly predictions: readonly SchedulerTaskPrediction[];
+}
+
+export function createSchedulerHistoryIdentity(input: {
+  readonly authoredOptions: CanonicalJsonValue;
+  readonly checkId: string;
+  readonly flags: CanonicalJsonValue;
+}): string {
+  const authoredOptionsDigest = digestCanonicalValue(input.authoredOptions);
+  const flagsDigest = digestCanonicalValue(input.flags);
+  return digestCanonicalValue({
+    authoredOptionsDigest,
+    checkId: input.checkId,
+    flagsDigest,
+    modelVersion: SCHEDULER_HISTORY_MODEL_VERSION
+  });
+}
+
+/** Forms learned means first, then one project median prior, without invoking preparation. */
+export function createSchedulerPredictionSnapshot(
+  history: SchedulerHistoryModel,
+  inputs: readonly SchedulerPredictionInput[],
+  coldStartDurationMs = 1
+): SchedulerPredictionSnapshot {
+  const learned = inputs.map((input) => learnedPrediction(history, input));
+  const projectPrior = median(
+    learned.flatMap((prediction) =>
+      prediction.source === "learned" ? [prediction.estimatedDurationMs] : []
+    )
+  );
+  const predictions = learned.map((prediction) => {
+    if (prediction.source === "learned") return prediction;
+    if (projectPrior === undefined) return coldStartPrediction(prediction, coldStartDurationMs);
+    return projectPriorPrediction(prediction, projectPrior);
+  });
+  const digest = digestCanonicalValue({
+    modelVersion: SCHEDULER_HISTORY_MODEL_VERSION,
+    predictions: [...predictions]
+      .sort((left, right) => compareText(left.taskId, right.taskId))
+      .map((prediction) => ({
+        estimatedDurationMs: prediction.estimatedDurationMs,
+        identityDigest: prediction.identityDigest,
+        meanDurationMs: prediction.meanDurationMs,
+        p90DurationMs: prediction.p90DurationMs,
+        sampleCount: prediction.sampleCount,
+        source: prediction.source,
+        taskId: prediction.taskId
+      }))
+  });
+  return Object.freeze({
+    digest,
+    modelVersion: SCHEDULER_HISTORY_MODEL_VERSION,
+    predictions: Object.freeze(predictions.map(freezePrediction))
+  });
+}
+
+export function predictionForTask(
+  snapshot: SchedulerPredictionSnapshot,
+  taskId: string
+): SchedulerTaskPrediction | undefined {
+  return snapshot.predictions.find((prediction) => prediction.taskId === taskId);
+}
+
+function learnedPrediction(
+  history: SchedulerHistoryModel,
+  input: SchedulerPredictionInput
+): SchedulerTaskPrediction {
+  const identityDigest = createSchedulerHistoryIdentity(input);
+  const samples = schedulerHistorySeries(history, identityDigest)?.samples ?? [];
+  if (samples.length === 0) {
+    return Object.freeze({
+      estimatedDurationMs: 0,
+      identityDigest,
+      meanDurationMs: null,
+      p90DurationMs: null,
+      sampleCount: 0,
+      source: "cold-start",
+      taskId: input.taskId
+    });
+  }
+  const meanDurationMs = arithmeticMean(samples.map((sample) => sample.durationMs));
+  return Object.freeze({
+    estimatedDurationMs: meanDurationMs,
+    identityDigest,
+    meanDurationMs,
+    p90DurationMs: p90(samples.map((sample) => sample.durationMs)),
+    sampleCount: samples.length,
+    source: "learned",
+    taskId: input.taskId
+  });
+}
+
+function projectPriorPrediction(
+  prediction: SchedulerTaskPrediction,
+  projectPrior: number
+): SchedulerTaskPrediction {
+  return Object.freeze({
+    ...prediction,
+    estimatedDurationMs: projectPrior,
+    source: "project-prior"
+  });
+}
+
+function coldStartPrediction(
+  prediction: SchedulerTaskPrediction,
+  coldStartDurationMs: number
+): SchedulerTaskPrediction {
+  return Object.freeze({
+    ...prediction,
+    estimatedDurationMs: coldStartDurationMs,
+    source: "cold-start"
+  });
+}
+
+function freezePrediction(prediction: SchedulerTaskPrediction): SchedulerTaskPrediction {
+  return Object.freeze({ ...prediction });
+}
+
+function digestCanonicalValue(value: CanonicalJsonValue): string {
+  return `sha256:${createHash("sha256").update(canonicalJsonBytes(value)).digest("hex")}`;
+}
+
+function arithmeticMean(values: readonly number[]): number {
+  return values.reduce((total, value) => total + value, 0) / values.length;
+}
+
+/** The p90 is the nearest-rank element from an ascending finite duration window. */
+function p90(values: readonly number[]): number {
+  const ordered = [...values].sort((left, right) => left - right);
+  const index = Math.ceil(ordered.length * 0.9) - 1;
+  return ordered[index] ?? 0;
+}
+
+function median(values: readonly number[]): number | undefined {
+  if (values.length === 0) return undefined;
+  const ordered = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(ordered.length / 2);
+  const upper = ordered[middle];
+  if (upper === undefined) return undefined;
+  if (ordered.length % 2 === 1) return upper;
+  const lower = ordered[middle - 1];
+  return lower === undefined ? undefined : (lower + upper) / 2;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}

package/src/package-tools/learned-critical-path/duration-model/preparation.ts

@@ -0,0 +1,79 @@
+import type { SchedulerMeasurementContext } from "../../../project-definition/project-definition.ts";
+import { recordSchedulerHistory, type SchedulerHistoryRecordingObservation } from "./recording.ts";
+import {
+  createSchedulerPredictionSnapshot,
+  type SchedulerPredictionInput,
+  type SchedulerPredictionSnapshot
+} from "./prediction.ts";
+import { loadSchedulerHistory, writeSchedulerHistory } from "./storage.ts";
+
+export type SchedulerDurationModelPreparation =
+  | Readonly<{
+      readonly kind: "ready";
+      readonly prediction: SchedulerPredictionSnapshot;
+      readonly readObservation: Awaited<ReturnType<typeof loadSchedulerHistory>>["observation"];
+      readonly retainedSeriesCount: number;
+      readonly record: (
+        terminalMeasurement: SchedulerMeasurementContext
+      ) => Promise<SchedulerDurationModelRecordObservation>;
+    }>
+  | Readonly<{ readonly kind: "static-fallback" }>;
+
+export type SchedulerDurationModelRecordObservation =
+  | Readonly<{
+      readonly kind: "recorded";
+      readonly recording: SchedulerHistoryRecordingObservation;
+      readonly writeObservation: Awaited<ReturnType<typeof writeSchedulerHistory>>;
+    }>
+  | Readonly<{ readonly kind: "failed" }>;
+
+/** Prepares one immutable duration prediction and its terminal record capability outside Scheduler. */
+export async function prepareSchedulerDurationModel(input: {
+  readonly predictionInputs: readonly SchedulerPredictionInput[];
+  readonly stateDirectory: string;
+  readonly coldStartDurationMs?: number;
+  readonly maxSamplesPerSeries?: number;
+  readonly maxSeries?: number;
+}): Promise<SchedulerDurationModelPreparation> {
+  try {
+    const loaded = await loadSchedulerHistory(input.stateDirectory);
+    const prediction = createSchedulerPredictionSnapshot(
+      loaded.history,
+      input.predictionInputs,
+      input.coldStartDurationMs
+    );
+    return Object.freeze({
+      kind: "ready",
+      prediction,
+      readObservation: loaded.observation,
+      retainedSeriesCount: loaded.history.series.length,
+      record: async (terminalMeasurement) => {
+        try {
+          const recorded = recordSchedulerHistory({
+            history: loaded.history,
+            prediction,
+            rawMeasurement: terminalMeasurement.rawMeasurement,
+            settledTasks: terminalMeasurement.execution.settledTasks,
+            ...(input.maxSamplesPerSeries === undefined
+              ? {}
+              : { maxSamplesPerSeries: input.maxSamplesPerSeries }),
+            ...(input.maxSeries === undefined ? {} : { maxSeries: input.maxSeries })
+          });
+          const writeObservation = await writeSchedulerHistory(
+            input.stateDirectory,
+            recorded.history
+          );
+          return Object.freeze({
+            kind: "recorded",
+            recording: recorded.observation,
+            writeObservation
+          });
+        } catch {
+          return Object.freeze({ kind: "failed" });
+        }
+      }
+    });
+  } catch {
+    return Object.freeze({ kind: "static-fallback" });
+  }
+}

package/src/package-tools/learned-critical-path/duration-model/recording.ts

@@ -0,0 +1,209 @@
+import type { SchedulerRawMeasurement } from "../../../project-definition/project-definition.ts";
+import {
+  freezeSchedulerHistoryModel,
+  isBoundedDurationMs,
+  MAX_SCHEDULER_HISTORY_SAMPLES_PER_SERIES,
+  MAX_SCHEDULER_HISTORY_SERIES,
+  type SchedulerDurationSettlementKind,
+  type SchedulerHistoryModel,
+  type SchedulerHistorySeries
+} from "./bounded-history.ts";
+import { predictionForTask, type SchedulerPredictionSnapshot } from "./prediction.ts";
+
+type SchedulerMeasurementAdmission = NonNullable<
+  SchedulerRawMeasurement["timingFacts"]
+>["admissions"][number];
+
+export type SchedulerHistoryRecordingObservation =
+  | Readonly<{
+      readonly acceptedSampleCount: number;
+      readonly retainedSeriesCount: number;
+      readonly status: "recorded";
+    }>
+  | Readonly<{
+      readonly acceptedSampleCount: 0;
+      readonly retainedSeriesCount: number;
+      readonly status: "timing-unavailable";
+    }>;
+
+export interface SchedulerHistoryRecording {
+  readonly history: SchedulerHistoryModel;
+  readonly observation: SchedulerHistoryRecordingObservation;
+}
+
+/** Merges only trusted terminal Scheduler occupancy intervals; unavailable timing creates no samples. */
+export function recordSchedulerHistory(input: {
+  readonly history: SchedulerHistoryModel;
+  readonly prediction: SchedulerPredictionSnapshot;
+  readonly rawMeasurement: SchedulerRawMeasurement;
+  readonly settledTasks: readonly Readonly<{
+    readonly kind: SchedulerDurationSettlementKind;
+    readonly taskId: string;
+  }>[];
+  readonly maxSamplesPerSeries?: number;
+  readonly maxSeries?: number;
+}): SchedulerHistoryRecording {
+  const rawMeasurement = input.rawMeasurement;
+  const timingFacts = rawMeasurement.timingFacts;
+  if (rawMeasurement.timing.availability !== "available" || timingFacts === undefined) {
+    return Object.freeze({
+      history: input.history,
+      observation: Object.freeze({
+        acceptedSampleCount: 0,
+        retainedSeriesCount: input.history.series.length,
+        status: "timing-unavailable"
+      })
+    });
+  }
+
+  return recordedHistory(input, timingFacts.admissions);
+}
+
+function recordedHistory(
+  input: Parameters<typeof recordSchedulerHistory>[0],
+  admissions: readonly SchedulerMeasurementAdmission[]
+): SchedulerHistoryRecording {
+  const merged = mergeVerifiedAdmissionSamples({
+    admissions,
+    history: input.history,
+    prediction: input.prediction,
+    settledByTaskId: new Map(input.settledTasks.map((settled) => [settled.taskId, settled.kind])),
+    maxSamplesPerSeries: input.maxSamplesPerSeries ?? MAX_SCHEDULER_HISTORY_SAMPLES_PER_SERIES
+  });
+  const retained = retainRecentSeries(
+    merged.seriesByIdentity.values(),
+    input.maxSeries ?? MAX_SCHEDULER_HISTORY_SERIES
+  );
+  const history = freezeSchedulerHistoryModel({
+    latestObservationSequence: merged.latestObservationSequence,
+    series: retained
+  });
+  return Object.freeze({
+    history,
+    observation: Object.freeze({
+      acceptedSampleCount: merged.acceptedSampleCount,
+      retainedSeriesCount: history.series.length,
+      status: "recorded"
+    })
+  });
+}
+
+type VerifiedAdmissionMerge = Readonly<{
+  readonly acceptedSampleCount: number;
+  readonly latestObservationSequence: number;
+  readonly seriesByIdentity: ReadonlyMap<string, SchedulerHistorySeries>;
+}>;
+
+/** Applies valid admissions in Scheduler order and returns the updated identity histories. */
+function mergeVerifiedAdmissionSamples(input: {
+  readonly admissions: readonly SchedulerMeasurementAdmission[];
+  readonly history: SchedulerHistoryModel;
+  readonly prediction: SchedulerPredictionSnapshot;
+  readonly settledByTaskId: ReadonlyMap<string, SchedulerDurationSettlementKind>;
+  readonly maxSamplesPerSeries: number;
+}): VerifiedAdmissionMerge {
+  const seriesByIdentity = new Map(
+    input.history.series.map((series) => [series.identityDigest, series] as const)
+  );
+  let latestObservationSequence = input.history.latestObservationSequence;
+  let acceptedSampleCount = 0;
+  for (const admission of input.admissions) {
+    const sample = sampleForAdmission(admission, input.prediction, input.settledByTaskId);
+    if (sample === undefined || latestObservationSequence === Number.MAX_SAFE_INTEGER) continue;
+    latestObservationSequence += 1;
+    appendSampleToIdentityHistory(
+      seriesByIdentity,
+      sample,
+      latestObservationSequence,
+      input.maxSamplesPerSeries
+    );
+    acceptedSampleCount += 1;
+  }
+  return Object.freeze({ acceptedSampleCount, latestObservationSequence, seriesByIdentity });
+}
+
+function appendSampleToIdentityHistory(
+  seriesByIdentity: Map<string, SchedulerHistorySeries>,
+  sample: AdmissionSample,
+  observationSequence: number,
+  maxSamplesPerSeries: number
+): void {
+  const existing = seriesByIdentity.get(sample.identityDigest);
+  const samples = [
+    ...(existing?.samples ?? []),
+    {
+      durationMs: sample.durationMs,
+      observationSequence,
+      settlementKind: sample.settlementKind
+    }
+  ].slice(-maxSamplesPerSeries);
+  seriesByIdentity.set(
+    sample.identityDigest,
+    Object.freeze({
+      identityDigest: sample.identityDigest,
+      latestObservationSequence: observationSequence,
+      samples: Object.freeze(samples)
+    })
+  );
+}
+
+type AdmissionSample = Readonly<{
+  readonly durationMs: number;
+  readonly identityDigest: string;
+  readonly settlementKind: SchedulerDurationSettlementKind;
+}>;
+
+function sampleForAdmission(
+  admission: Readonly<{
+    readonly admittedAtMonotonicMs: number | null;
+    readonly settledAtMonotonicMs: number | null;
+    readonly taskId: string;
+  }>,
+  prediction: SchedulerPredictionSnapshot,
+  settledByTaskId: ReadonlyMap<string, SchedulerDurationSettlementKind>
+): AdmissionSample | undefined {
+  if (
+    admission.admittedAtMonotonicMs === null ||
+    admission.settledAtMonotonicMs === null ||
+    !isFiniteMonotonicTimestamp(admission.admittedAtMonotonicMs) ||
+    !isFiniteMonotonicTimestamp(admission.settledAtMonotonicMs) ||
+    admission.settledAtMonotonicMs < admission.admittedAtMonotonicMs
+  ) {
+    return undefined;
+  }
+  const durationMs = admission.settledAtMonotonicMs - admission.admittedAtMonotonicMs;
+  if (!isBoundedDurationMs(durationMs)) return undefined;
+  const taskPrediction = predictionForTask(prediction, admission.taskId);
+  const settlementKind = settledByTaskId.get(admission.taskId);
+  if (taskPrediction === undefined || settlementKind === undefined) return undefined;
+  return Object.freeze({
+    durationMs,
+    identityDigest: taskPrediction.identityDigest,
+    settlementKind
+  });
+}
+
+function retainRecentSeries(
+  series: Iterable<SchedulerHistorySeries>,
+  maxSeries: number
+): readonly SchedulerHistorySeries[] {
+  return Object.freeze(
+    [...series]
+      .sort(
+        (left, right) =>
+          right.latestObservationSequence - left.latestObservationSequence ||
+          compareText(left.identityDigest, right.identityDigest)
+      )
+      .slice(0, maxSeries)
+  );
+}
+
+function isFiniteMonotonicTimestamp(value: number): boolean {
+  return Number.isFinite(value) && value >= 0 && value <= Number.MAX_SAFE_INTEGER;
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}