Skip to content

Write HTML. Render video. Built for agents.

18.1 KB
Raw Blame
/**
 * Build the `RenderPerfSummary` that lands on `job.perfSummary` and
 * the `perf-summary.json` debug artifact.
 */

import { arch, cpus, platform, totalmem } from "node:os";
import { fpsToNumber, type HfVfxCapture } from "@hyperframes/core";
import type {
  CapturePerfSummary,
  StaticVerificationOutcome,
  SubTimelineWaitOutcome,
  WorkerSizing,
} from "@hyperframes/engine";
import type { CaptureCalibrationSample, CaptureCostEstimate } from "./captureCost.js";
import type {
  CaptureAttemptSummary,
  HdrDiagnostics,
  RenderJob,
  RenderPerfSummary,
} from "../renderOrchestrator.js";
import { type HdrPerfCollector, finalizeHdrPerf } from "./hdrPerf.js";
import type { RenderObservabilitySummary } from "./observability.js";

/**
 * Worst sub-composition timeline wait outcome across sessions: script_failure
 * > timeout > ready. Shared by the success-path perf summary and the error
 * path (a fail-fast can still be followed by an unrelated downstream
 * failure, e.g. in `pollVideosReady` or encode — that render fires
 * `render_error`, not `render_complete`, and should carry this too).
 */
export function worstSubTimelineWaitOutcome(
  perfs: CapturePerfSummary[],
): SubTimelineWaitOutcome | undefined {
  const outcomes = perfs
    .map((p) => p.subTimelineWaitOutcome)
    .filter((o): o is SubTimelineWaitOutcome => !!o);
  if (outcomes.length === 0) return undefined;
  if (outcomes.includes("script_failure")) return "script_failure";
  if (outcomes.includes("timeout")) return "timeout";
  return "ready";
}

/**
 * Append each parallel worker's static-dedup perf into the render-level sink
 * (skipping workers that reported none). Shared by the disk + streaming parallel
 * paths so the collection contract lives in one place.
 */
export function pushWorkerDedupPerfs(
  results: ReadonlyArray<{ perf?: CapturePerfSummary }>,
  sink: CapturePerfSummary[],
): void {
  for (const r of results) {
    if (r.perf) sink.push(r.perf);
  }
}

/**
 * Collapse per-session/per-worker static-dedup perf into one render-level
 * outcome. enabled/armed = OR across workers (they run the same gates on the
 * same composition); predicted/reused = SUM (each worker dedups its own frame
 * range); skipReason = the distinct reasons (sorted, `|`-joined) when not armed.
 */
/**
 * Collapse per-session capture perf + producer-side decisions into the
 * render-level drawElement outcome. mode/gateReason |-join distinct values
 * across workers (bounded cardinality); counters SUM.
 */
/**
 * Round a dB value to 1 decimal and clamp at 999 (an `Infinity` PSNR — a
 * bit-exact frame match — must not ship literally to telemetry). Single
 * source of truth for every dB field crossing into `RenderPerfSummary` or
 * `RenderCaptureObservability` — both must agree byte-for-byte so PostHog
 * consumers joining `render_complete` against the crash-survival
 * `render_error` mirror never see the same underlying score reported at two
 * different precisions (review finding).
 */
export function roundDb(value: number | undefined): number | undefined {
  return value === undefined ? undefined : Math.round(Math.min(value, 999) * 10) / 10;
}

/** Orchestrator-supplied render-level drawElement outcome (one shape, used by
 * both the aggregate function and buildRenderPerfSummary's input). */
export interface DrawElementPerfInput {
  compileGate?: string;
  clampReason?: string;
  /** Engine init-time gate the pre-capture probe hit; its session may be closed before capture. */
  probeGateReason?: string;
  workerInversion?: "inverted" | "reverted";
  /** Auto-resolved worker count before the inversion pinned it to 1 (set only when the inversion fired). */
  preInversionWorkers?: number;
  /** Rough compiled-composition element count — gate variable for the short-comp inversion band. */
  compositionElementCount?: number;
  /** Provenance of the element count: "live" (probe DOM, trusted to gate) | "static" (source scan, not). */
  compositionElementCountSource?: "live" | "static";
  /** Per-tag breakdown of the same static scan behind compositionElementCount; only set when the source above is "static". */
  compositionElementTags?: Readonly<Record<string, number>>;
  /** `<video data-aroll="true">` count from the same static scan; only set when compositionElementCountSource is "static". */
  arollVideoCount?: number;
  /** `<video data-media-source="heygen">` count from the same static scan; only set when compositionElementCountSource is "static". */
  heygenVideoCount?: number;
  /** Runtime adapters exercised (live+static union); always set (possibly empty). */
  adaptersUsed?: readonly string[];
  /** Audio/image/sub-comp/color-grading counts, same static scan; only set when the source above is "static". */
  audioCount?: number;
  imageCount?: number;
  subCompositionCount?: number;
  audioGroupCount?: number;
  colorGradingCount?: number;
  hasLut?: boolean;
  /** Authored root data-width/height vs. the scaffold's html/body CSS size; absent when either is undetectable. */
  rootBodyMismatch?: boolean;
  rootBodyDeltaPxBucket?: "0" | "1-10" | "11-50" | "51+";
  /** `data-vfx-chain` host count from the same static scan. Only set when the source above is "static". */
  vfxHostCount?: number;
  /** Strongest enabled node's capture across every host (`chainCapture`, max: backdrop > self > none). Undefined when vfxHostCount is 0. */
  vfxCapture?: HfVfxCapture;
  /** Sorted unique def ids across every enabled node in every chain, comma-joined ("" when vfxHostCount is 0). */
  vfxTypes?: string;
  /** Short-comp band decision when the band was DECISIVE: "applied" (inverts once HF_DE_SHORT_BAND_ROUTE is on; counterfactual in the baseline release) | "skipped_elements" (element ceiling was the only blocker); unset when the band could not have affected this render. */
  shortBand?: "applied" | "skipped_elements" | "unmeasured";
  parallelRouter?: "routed" | "reverted";
  /** Auto-resolved worker count before the router pinned it to 3 (set only when the router fired). */
  preRouterWorkers?: number;
  selfVerifyFallback: boolean;
  fallbackReason?: string;
  /** The failing PSNR (dB) when `fallbackReason === "psnr"`; undefined for blank/oom/capture_error. */
  fallbackFailedDb?: number;
  /** Frame index the verification failure was detected at; set for both "psnr" and "blank". */
  fallbackFrameIndex?: number;
  /** The HF_DE_VERIFY_MIN_DB threshold the failing dB breached; only set alongside fallbackFailedDb. */
  fallbackThresholdDb?: number;
  drainStats?: {
    verifyChecked: number;
    verifyMinDb?: number;
    blankSuspects: number;
    blankDeterministicAccepts: number;
    blankRecaptures: number;
  };
}

// Flat field mapping — branches are ?? fallbacks, not logic.
// fallow-ignore-next-line complexity
function aggregateDrawElement(
  perfs: CapturePerfSummary[],
  de: DrawElementPerfInput,
): RenderPerfSummary["drawElement"] {
  if (perfs.length === 0) return undefined;
  const modes = [...new Set(perfs.map((p) => p.captureMode).filter(Boolean))].sort();
  const gateReasons = [
    ...new Set(
      [de.probeGateReason, ...perfs.map((p) => p.deGateReason)].filter((r): r is string => !!r),
    ),
  ].sort();
  const gpuRenderers = [
    ...new Set(perfs.map((p) => p.gpuRenderer).filter((r): r is string => !!r)),
  ].sort();
  const drain = de.drainStats;
  return {
    mode: modes.join("|") || "unknown",
    compileGate: de.compileGate,
    clampReason: de.clampReason,
    workerInversion: de.workerInversion ?? "none",
    preInversionWorkers: de.preInversionWorkers,
    compositionElementCount: de.compositionElementCount,
    compositionElementCountSource: de.compositionElementCountSource,
    compositionElementTags: de.compositionElementTags,
    arollVideoCount: de.arollVideoCount,
    heygenVideoCount: de.heygenVideoCount,
    adaptersUsed: de.adaptersUsed,
    audioCount: de.audioCount,
    imageCount: de.imageCount,
    subCompositionCount: de.subCompositionCount,
    audioGroupCount: de.audioGroupCount,
    colorGradingCount: de.colorGradingCount,
    hasLut: de.hasLut,
    rootBodyMismatch: de.rootBodyMismatch,
    rootBodyDeltaPxBucket: de.rootBodyDeltaPxBucket,
    vfxHostCount: de.vfxHostCount,
    vfxCapture: de.vfxCapture,
    vfxTypes: de.vfxTypes,
    shortBand: de.shortBand,
    parallelRouter: de.parallelRouter ?? "none",
    preRouterWorkers: de.preRouterWorkers,
    gateReason: gateReasons.length > 0 ? gateReasons.join("|") : undefined,
    gpuRenderer: gpuRenderers.length > 0 ? gpuRenderers.join("|") : undefined,
    workerEncode: perfs.some((p) => p.deWorkerEncode),
    verifyArmed: perfs.reduce((sum, p) => sum + (p.deVerifyArmed ?? 0), 0),
    verifyChecked: drain?.verifyChecked ?? 0,
    verifyMinDb: roundDb(drain?.verifyMinDb),
    verifyInitMs: perfs.reduce((sum, p) => sum + (p.deVerifyInitMs ?? 0), 0),
    selfVerifyFallback: de.selfVerifyFallback,
    fallbackReason: de.fallbackReason,
    fallbackFailedDb: roundDb(de.fallbackFailedDb),
    fallbackFrameIndex: de.fallbackFrameIndex,
    fallbackThresholdDb: roundDb(de.fallbackThresholdDb),
    blankSuspects: drain?.blankSuspects ?? 0,
    blankDeterministicAccepts: drain?.blankDeterministicAccepts ?? 0,
    blankRecaptures: drain?.blankRecaptures ?? 0,
    boundaryFrames: perfs.reduce((sum, p) => sum + (p.deBoundaryFrames ?? 0), 0),
    ncprFallbacks: perfs.reduce((sum, p) => sum + (p.deNcprFallbacks ?? 0), 0),
    frameTimeouts: perfs.reduce((sum, p) => sum + (p.deFrameTimeouts ?? 0), 0),
  };
}

function maxDefined(values: Array<number | undefined>): number | undefined {
  const present = values.filter((v): v is number => typeof v === "number");
  return present.length > 0 ? Math.max(...present) : undefined;
}

/**
 * Chrome memory across capture sessions: max of per-session peaks, sum of the
 * last samples. Sessions that never produced a reading are excluded so
 * `samples: 0` cannot be published alongside another worker's real peaks.
 */
function aggregateChromeMemory(perfs: CapturePerfSummary[]): RenderPerfSummary["chromeMemory"] {
  const sampled = perfs.filter((p) => (p.chromeMemorySamples ?? 0) > 0);
  if (sampled.length === 0) return undefined;
  return {
    browserRssPeakMb: maxDefined(sampled.map((p) => p.chromeBrowserRssPeakMb)),
    rendererRssPeakMb: maxDefined(sampled.map((p) => p.chromeRendererRssPeakMb)),
    // Last samples are per session; summing approximates the whole fleet's
    // footprint at the end of capture (workers run concurrently).
    rssLastMb: sampled.reduce((sum, p) => sum + (p.chromeRssLastMb ?? 0), 0),
    gpuProcessSeenLastSample: sampled.some((p) => p.chromeGpuProcessSeenLastSample === true),
    samples: sampled.reduce((sum, p) => sum + (p.chromeMemorySamples ?? 0), 0),
  };
}

function aggregateDedup(perfs: CapturePerfSummary[]): RenderPerfSummary["staticDedup"] {
  if (perfs.length === 0) return undefined;
  const armed = perfs.some((p) => p.staticDedupArmed);
  // When unarmed, report every DISTINCT skip reason across workers (sorted, joined)
  // rather than just the first — workers can diverge (e.g. one `ineligible`, one
  // `capture_mode`), and dropping the rest hides why dedup didn't engage. Cardinality
  // stays bounded (a handful of codes, small combinations).
  const skipReasons = armed
    ? []
    : [
        ...new Set(perfs.map((p) => p.staticDedupSkipReason).filter((r): r is string => !!r)),
      ].sort();
  const verificationPerfs = perfs.filter((perf) => perf.staticDedupVerificationOutcome);
  const verificationOutcomes = [
    ...new Set(
      verificationPerfs
        .map((perf) => perf.staticDedupVerificationOutcome)
        .filter((outcome): outcome is StaticVerificationOutcome => outcome != null),
    ),
  ].sort();
  return {
    enabled: perfs.some((p) => p.staticDedupEnabled),
    armed,
    predictedFrames: perfs.reduce((sum, p) => sum + (p.staticDedupPredicted ?? 0), 0),
    reusedFrames: perfs.reduce((sum, p) => sum + (p.staticDedupReused ?? 0), 0),
    skipReason: skipReasons.length > 0 ? skipReasons.join("|") : undefined,
    ...(verificationPerfs.length === 0
      ? {}
      : {
          verifiedFrames: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerified ?? 0),
            0,
          ),
          verificationOutcomes,
          plannedRuns: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerificationPlannedRuns ?? 0),
            0,
          ),
          completedRuns: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerificationCompletedRuns ?? 0),
            0,
          ),
          screenshots: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerificationScreenshots ?? 0),
            0,
          ),
          seeks: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerificationSeeks ?? 0),
            0,
          ),
          comparisons: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerificationComparisons ?? 0),
            0,
          ),
          verificationElapsedMs: verificationPerfs.reduce(
            (sum, perf) => sum + (perf.staticDedupVerificationElapsedMs ?? 0),
            0,
          ),
        }),
  };
}

/**
 * Collapse per-session/per-worker BeginFrame damage counters into one
 * render-level reuse outcome (SUM across workers — each worker ticks its own
 * frame range). Both zero ⟺ no beginframe session ran (screenshot/drawElement
 * sessions never increment these) → undefined, mirroring staticDedup's
 * "undefined when it never engaged" contract. Also inherits `dedupPerfs`'
 * retry semantics: a partial-capture retry resets the sink, so the sums cover
 * only the final attempt's recaptured ranges (may be < totalFrames).
 */
function aggregateBeginFrameReuse(
  perfs: CapturePerfSummary[],
): RenderPerfSummary["beginFrameReuse"] {
  const noDamageFrames = perfs.reduce((sum, p) => sum + (p.beginFrameNoDamage ?? 0), 0);
  const hasDamageFrames = perfs.reduce((sum, p) => sum + (p.beginFrameHasDamage ?? 0), 0);
  if (noDamageFrames + hasDamageFrames === 0) return undefined;
  return { noDamageFrames, hasDamageFrames };
}

export function buildRenderPerfSummary(input: {
  job: RenderJob;
  workerCount: number;
  /** Auto-sizing provenance; undefined when a pin (htmlInCanvas / low-memory) short-circuited sizing. */
  workerSizing?: WorkerSizing;
  enableChunkedEncode: boolean;
  chunkedEncodeSize: number;
  compositionDurationSeconds: number;
  totalFrames: number;
  outputWidth: number;
  outputHeight: number;
  videoCount: number;
  audioCount: number;
  totalElapsedMs: number;
  perfStages: Record<string, number>;
  videoExtractBreakdown: RenderPerfSummary["videoExtractBreakdown"];
  tmpPeakBytes: number;
  captureCalibration?: {
    estimate: CaptureCostEstimate;
    samples: CaptureCalibrationSample[];
  };
  captureAttempts: CaptureAttemptSummary[];
  hdrDiagnostics: HdrDiagnostics;
  hdrPerf?: HdrPerfCollector;
  observability?: RenderObservabilitySummary;
  peakRssBytes: number;
  peakHeapUsedBytes: number;
  /** Per-session/per-worker static-dedup perf; aggregated into `staticDedup`. */
  dedupPerfs: CapturePerfSummary[];
  drawElement?: DrawElementPerfInput;
  /** `cfg.disableGpu` — the hard `--disable-gpu` flag, for the `host` GPU picture. */
  gpuDisabled: boolean;
}): RenderPerfSummary {
  return {
    renderId: input.job.id,
    totalElapsedMs: input.totalElapsedMs,
    // RenderPerfSummary surfaces fps as a decimal because it lands in JSON
    // payloads (CLI telemetry, regression-harness reports) where a single
    // number is friendlier than `{num,den}`. Callers needing the rational
    // back can read `job.config.fps`.
    fps: fpsToNumber(input.job.config.fps),
    quality: input.job.config.quality,
    workers: input.workerCount,
    workerSizing: input.workerSizing,
    chunkedEncode: input.enableChunkedEncode,
    chunkSizeFrames: input.enableChunkedEncode ? input.chunkedEncodeSize : null,
    compositionDurationSeconds: input.compositionDurationSeconds,
    totalFrames: input.totalFrames,
    resolution: { width: input.outputWidth, height: input.outputHeight },
    videoCount: input.videoCount,
    audioCount: input.audioCount,
    stages: input.perfStages,
    videoExtractBreakdown: input.videoExtractBreakdown,
    tmpPeakBytes: input.tmpPeakBytes,
    captureCalibration: input.captureCalibration
      ? {
          sampledFrames: input.captureCalibration.samples.map((sample) => sample.frameIndex),
          p95Ms: input.captureCalibration.estimate.p95Ms,
          multiplier: input.captureCalibration.estimate.multiplier,
          reasons: input.captureCalibration.estimate.reasons,
        }
      : undefined,
    captureAttempts: input.captureAttempts.length > 0 ? input.captureAttempts : undefined,
    hdrDiagnostics:
      input.hdrDiagnostics.videoExtractionFailures > 0 ||
      input.hdrDiagnostics.imageDecodeFailures > 0
        ? { ...input.hdrDiagnostics }
        : undefined,
    hdrPerf: input.hdrPerf ? finalizeHdrPerf(input.hdrPerf) : undefined,
    observability: input.observability,
    captureAvgMs:
      input.totalFrames > 0
        ? Math.round(
            (input.perfStages.captureFrameMs ?? input.perfStages.captureMs ?? 0) /
              input.totalFrames,
          )
        : undefined,
    subTimelineWait: worstSubTimelineWaitOutcome(input.dedupPerfs),
    captureP50Ms: (() => {
      // Per-frame median from the engine's samples; when parallel workers
      // report separately, take the busiest session's median.
      const withSamples = input.dedupPerfs.filter((p) => (p.p50TotalMs ?? 0) > 0);
      if (withSamples.length === 0) return undefined;
      return withSamples.reduce((a, b) => (b.frames > a.frames ? b : a)).p50TotalMs;
    })(),
    peakRssMb: Math.round(input.peakRssBytes / (1024 * 1024)),
    peakHeapUsedMb: Math.round(input.peakHeapUsedBytes / (1024 * 1024)),
    staticDedup: aggregateDedup(input.dedupPerfs),
    chromeMemory: aggregateChromeMemory(input.dedupPerfs),
    beginFrameReuse: aggregateBeginFrameReuse(input.dedupPerfs),
    drawElement: aggregateDrawElement(
      input.dedupPerfs,
      input.drawElement ?? { selfVerifyFallback: false },
    ),
    host: {
      platform: platform(),
      arch: arch(),
      cpuCount: cpus().length,
      totalMemMb: Math.round(totalmem() / (1024 * 1024)),
      nodeVersion: process.version,
      gpuDisabled: input.gpuDisabled,
    },
  };
}