@hypit/hypit 0.0.1 → 0.1.1

package/packages/media-execution/src/index.ts

@@ -0,0 +1,16 @@
+export {
+  executeInspectMedia,
+  executeExtractAudio,
+  executeExtractFrame,
+  executeMuxProgramMedia,
+  executeNormalizeMedia,
+  executeProjectSpeechEvidenceAudio,
+  executeRenderTimelineAudio,
+  executeRenderStillVideo,
+  executeTransformMedia,
+} from "./execute.js";
+export { parseMediaInspection } from "./probe.js";
+export { verifyCompositableSurfaceBytes } from "./surface.js";
+export { probeMediaToolchain } from "./toolchain.js";
+export type { MediaToolchainState } from "./toolchain.js";
+export type * from "./execute.js";

package/packages/media-execution/src/probe.ts

@@ -0,0 +1,315 @@
+import { sealMediaInspection } from "@hypit/media";
+import type { MediaAudioStream, MediaInspection, MediaOtherStream, MediaRational, MediaStream, MediaTimestamp, MediaVideoStream } from "@hypit/media";
+import type { BlobRef } from "@hypit/protocol";
+
+type JsonObject = Record<string, unknown>;
+
+type FfprobeStream = {
+  readonly index?: unknown;
+  readonly codec_type?: unknown;
+  readonly codec_name?: unknown;
+  readonly width?: unknown;
+  readonly height?: unknown;
+  readonly sample_aspect_ratio?: unknown;
+  readonly time_base?: unknown;
+  readonly avg_frame_rate?: unknown;
+  readonly r_frame_rate?: unknown;
+  readonly sample_rate?: unknown;
+  readonly channels?: unknown;
+  readonly channel_layout?: unknown;
+  readonly disposition?: { readonly default?: unknown; readonly attached_pic?: unknown };
+  readonly tags?: { readonly rotate?: unknown };
+  readonly side_data_list?: readonly unknown[];
+};
+
+type FfprobeFrame = {
+  readonly media_type?: unknown;
+  readonly stream_index?: unknown;
+  readonly pts?: unknown;
+  readonly best_effort_timestamp?: unknown;
+  readonly duration?: unknown;
+  readonly pkt_duration?: unknown;
+  readonly nb_samples?: unknown;
+};
+
+type Unit = { pts: bigint; duration: bigint | undefined; samples: number };
+
+function object(value: unknown): JsonObject | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonObject
+    : undefined;
+}
+
+function integer(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isSafeInteger(value)) return value;
+  if (typeof value === "string" && /^-?\d+$/u.test(value)) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+  const parsed = integer(value);
+  return parsed !== undefined && parsed > 0 ? parsed : undefined;
+}
+
+function bigintValue(value: unknown): bigint | undefined {
+  if (typeof value === "string" && /^-?\d+$/u.test(value)) return BigInt(value);
+  if (typeof value === "number" && Number.isSafeInteger(value)) return BigInt(value);
+  return undefined;
+}
+
+function rational(value: unknown, allowZero = false): MediaRational | undefined {
+  if (typeof value !== "string") return undefined;
+  const match = value.match(/^(-?\d+)\/(\d+)$/u);
+  if (match === null) return undefined;
+  const numerator = Number(match[1]);
+  const denominator = Number(match[2]);
+  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator) || denominator < 1) return undefined;
+  if (allowZero ? numerator < 0 : numerator < 1) return undefined;
+  return { numerator, denominator };
+}
+
+function divisor(left: number, right: number): number {
+  let a = Math.abs(left);
+  let b = Math.abs(right);
+  while (b !== 0) [a, b] = [b, a % b];
+  return a;
+}
+
+function sampleAspectRatio(value: unknown): MediaRational {
+  if (typeof value !== "string") return { numerator: 1, denominator: 1 };
+  const match = value.match(/^(\d+):(\d+)$/u);
+  if (match === null) return { numerator: 1, denominator: 1 };
+  const numerator = Number(match[1]);
+  const denominator = Number(match[2]);
+  if (!Number.isSafeInteger(numerator) || !Number.isSafeInteger(denominator)
+    || numerator <= 0 || denominator <= 0) return { numerator: 1, denominator: 1 };
+  const factor = divisor(numerator, denominator);
+  return { numerator: numerator / factor, denominator: denominator / factor };
+}
+
+function numeric(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim() && Number.isFinite(Number(value))) return Number(value);
+  return undefined;
+}
+
+function displayRotation(stream: FfprobeStream, index: number): 0 | 90 | 180 | 270 {
+  const sideData = stream.side_data_list?.map(object).find((item) => item?.side_data_type === "Display Matrix");
+  const raw = numeric(sideData?.rotation) ?? numeric(stream.tags?.rotate) ?? 0;
+  const normalized = ((raw % 360) + 360) % 360;
+  for (const quarter of [0, 90, 180, 270] as const) {
+    if (Math.abs(normalized - quarter) < 1e-6) return quarter;
+  }
+  throw new Error(`video stream ${index} uses unsupported non-quarter display rotation ${raw}`);
+}
+
+function timestamp(ticks: bigint, timeBase: MediaRational): MediaTimestamp {
+  return { ticks: ticks.toString(), timeBase };
+}
+
+function median(values: readonly bigint[]): bigint {
+  const ordered = [...values].sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+  return ordered[Math.floor((ordered.length - 1) / 2)]!;
+}
+
+function sampleDurationTicks(
+  samples: number,
+  stream: FfprobeStream,
+  timeBase: MediaRational,
+): bigint | undefined {
+  const sampleRate = positiveInteger(stream.sample_rate);
+  if (samples <= 0 || sampleRate === undefined) return undefined;
+  const numerator = BigInt(samples) * BigInt(timeBase.denominator);
+  const denominator = BigInt(sampleRate) * BigInt(timeBase.numerator);
+  if (denominator <= 0n) return undefined;
+  return (numerator + denominator / 2n) / denominator;
+}
+
+function timing(
+  frames: readonly FfprobeFrame[],
+  stream: FfprobeStream,
+  kind: "video" | "audio" | "other",
+  index: number,
+  timeBase: MediaRational | undefined,
+): {
+  readonly timingStatus: MediaStream["timingStatus"];
+  readonly startPts?: MediaTimestamp;
+  readonly endPts?: MediaTimestamp;
+  readonly decodedUnitCount: number;
+  readonly decodedSampleFrames: number;
+} {
+  if (timeBase === undefined) return { timingStatus: "missing", decodedUnitCount: 0, decodedSampleFrames: 0 };
+  const selected = frames.filter((frame) => integer(frame.stream_index) === index
+    && (kind === "other" || frame.media_type === kind));
+  const units: Unit[] = [];
+  for (const frame of selected) {
+    const pts = bigintValue(frame.pts) ?? bigintValue(frame.best_effort_timestamp);
+    if (pts === undefined) return { timingStatus: "missing", decodedUnitCount: selected.length, decodedSampleFrames: 0 };
+    const samples = positiveInteger(frame.nb_samples) ?? 0;
+    units.push({
+      pts,
+      duration: bigintValue(frame.duration) ?? bigintValue(frame.pkt_duration)
+        ?? (kind === "audio" ? sampleDurationTicks(samples, stream, timeBase) : undefined),
+      samples,
+    });
+  }
+  if (units.length === 0) return { timingStatus: "missing", decodedUnitCount: 0, decodedSampleFrames: 0 };
+  const deltas: bigint[] = [];
+  for (let offset = 1; offset < units.length; offset += 1) {
+    const delta = units[offset]!.pts - units[offset - 1]!.pts;
+    if (delta <= 0n) {
+      return {
+        timingStatus: "non-monotonic",
+        decodedUnitCount: units.length,
+        decodedSampleFrames: units.reduce((sum, unit) => sum + unit.samples, 0),
+      };
+    }
+    deltas.push(delta);
+  }
+  for (let offset = 0; offset < units.length - 1; offset += 1) {
+    if (units[offset]!.duration === undefined || units[offset]!.duration! <= 0n) {
+      units[offset]!.duration = units[offset + 1]!.pts - units[offset]!.pts;
+    }
+  }
+  const last = units.at(-1)!;
+  if (last.duration === undefined || last.duration <= 0n) {
+    last.duration = deltas.at(-1);
+  }
+  if (last.duration === undefined || last.duration <= 0n) {
+    return {
+      timingStatus: "missing",
+      decodedUnitCount: units.length,
+      decodedSampleFrames: units.reduce((sum, unit) => sum + unit.samples, 0),
+    };
+  }
+  if (kind === "audio") {
+    for (let offset = 0; offset < units.length - 1; offset += 1) {
+      const gap = units[offset + 1]!.pts - (units[offset]!.pts + units[offset]!.duration!);
+      if (gap > 2n || gap < -2n) {
+        return {
+          timingStatus: gap > 0n ? "discontinuous" : "non-monotonic",
+          decodedUnitCount: units.length,
+          decodedSampleFrames: units.reduce((sum, unit) => sum + unit.samples, 0),
+        };
+      }
+    }
+  } else if (kind === "video" && deltas.length >= 2) {
+    const cadence = median(deltas);
+    const halfSecondTicks = (BigInt(timeBase.denominator) + 2n * BigInt(timeBase.numerator) - 1n)
+      / (2n * BigInt(timeBase.numerator));
+    const threshold = cadence * 4n > halfSecondTicks ? cadence * 4n : halfSecondTicks;
+    if (deltas.some((delta) => delta > threshold)) {
+      return {
+        timingStatus: "discontinuous",
+        decodedUnitCount: units.length,
+        decodedSampleFrames: 0,
+      };
+    }
+  }
+  return {
+    timingStatus: "admissible",
+    startPts: timestamp(units[0]!.pts, timeBase),
+    endPts: timestamp(last.pts + last.duration, timeBase),
+    decodedUnitCount: units.length,
+    decodedSampleFrames: units.reduce((sum, unit) => sum + unit.samples, 0),
+  };
+}
+
+export function parseMediaInspection(args: {
+  readonly source: BlobRef;
+  readonly ffprobeVersion: string;
+  readonly value: unknown;
+}): MediaInspection {
+  const root = object(args.value);
+  if (root === undefined) throw new Error("ffprobe output must be an object");
+  const rawStreams = Array.isArray(root.streams) ? root.streams.map(object).filter((item): item is JsonObject => item !== undefined) : [];
+  const streams = rawStreams as FfprobeStream[];
+  const rawFrames = Array.isArray(root.frames) ? root.frames.map(object).filter((item): item is JsonObject => item !== undefined) : [];
+  const frames = rawFrames as FfprobeFrame[];
+  const parsed: MediaStream[] = streams.map((stream): MediaStream => {
+    const index = integer(stream.index);
+    if (index === undefined || index < 0) throw new Error("ffprobe stream index is invalid");
+    const codecType = typeof stream.codec_type === "string" && stream.codec_type.length > 0 ? stream.codec_type : "unknown";
+    const codecName = typeof stream.codec_name === "string" && stream.codec_name.length > 0 ? stream.codec_name : "unknown";
+    const timeBase = rational(stream.time_base);
+    const disposition = {
+      default: integer(stream.disposition?.default) === 1,
+      attachedPicture: integer(stream.disposition?.attached_pic) === 1,
+    };
+    if (codecType === "video") {
+      const measured = timing(frames, stream, "video", index, timeBase);
+      const width = positiveInteger(stream.width);
+      const height = positiveInteger(stream.height);
+      if (width === undefined || height === undefined) throw new Error(`video stream ${index} dimensions are invalid`);
+      const role: MediaVideoStream["role"] = disposition.attachedPicture
+        ? "attached-picture"
+        : measured.decodedUnitCount >= 2 ? "moving" : "still";
+      return {
+        kind: "video",
+        index,
+        codecType: "video",
+        codecName,
+        disposition,
+        timingStatus: measured.timingStatus,
+        ...(timeBase === undefined ? {} : { timeBase }),
+        ...(measured.startPts === undefined ? {} : { startPts: measured.startPts, endPts: measured.endPts! }),
+        decodedUnitCount: measured.decodedUnitCount,
+        role,
+        width,
+        height,
+        sampleAspectRatio: sampleAspectRatio(stream.sample_aspect_ratio),
+        rotationDegrees: displayRotation(stream, index),
+        ...(rational(stream.avg_frame_rate, true) === undefined ? {} : { averageFrameRate: rational(stream.avg_frame_rate, true)! }),
+        ...(rational(stream.r_frame_rate, true) === undefined ? {} : { nominalFrameRate: rational(stream.r_frame_rate, true)! }),
+      };
+    }
+    if (codecType === "audio") {
+      const measured = timing(frames, stream, "audio", index, timeBase);
+      const sampleRate = positiveInteger(stream.sample_rate);
+      const channels = positiveInteger(stream.channels);
+      if (sampleRate === undefined || channels === undefined) throw new Error(`audio stream ${index} shape is invalid`);
+      const result: MediaAudioStream = {
+        kind: "audio",
+        index,
+        codecType: "audio",
+        codecName,
+        disposition,
+        timingStatus: measured.timingStatus,
+        ...(timeBase === undefined ? {} : { timeBase }),
+        ...(measured.startPts === undefined ? {} : { startPts: measured.startPts, endPts: measured.endPts! }),
+        decodedUnitCount: measured.decodedUnitCount,
+        sampleRate,
+        channels,
+        ...(typeof stream.channel_layout === "string" && stream.channel_layout.length > 0
+          ? { channelLayout: stream.channel_layout }
+          : {}),
+        decodedSampleFrames: measured.decodedSampleFrames,
+      };
+      return result;
+    }
+    const measured = timing(frames, stream, "other", index, timeBase);
+    const result: MediaOtherStream = {
+      kind: "other",
+      index,
+      codecType,
+      codecName,
+      disposition,
+      timingStatus: measured.timingStatus,
+      ...(timeBase === undefined ? {} : { timeBase }),
+      ...(measured.startPts === undefined ? {} : { startPts: measured.startPts, endPts: measured.endPts! }),
+      decodedUnitCount: measured.decodedUnitCount,
+    };
+    return result;
+  });
+  const format = object(root.format);
+  const formatNames = typeof format?.format_name === "string"
+    ? [...new Set(format.format_name.split(",").map((item) => item.trim()).filter(Boolean))].sort()
+    : ["unknown"];
+  return sealMediaInspection({
+    container: { formatNames: formatNames.length === 0 ? ["unknown"] : formatNames },
+    streams: parsed.sort((left, right) => left.index - right.index),
+  });
+}

package/packages/media-execution/src/surface.ts

@@ -0,0 +1,286 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { assertCompositableSurfaceRef } from "@hypit/media";
+import type { CompositableSurfaceRef } from "@hypit/media";
+
+type JsonObject = Record<string, unknown>;
+
+type ProbeStream = {
+  readonly codec_type?: unknown;
+  readonly codec_name?: unknown;
+  readonly width?: unknown;
+  readonly height?: unknown;
+  readonly pix_fmt?: unknown;
+  readonly sample_aspect_ratio?: unknown;
+  readonly avg_frame_rate?: unknown;
+  readonly r_frame_rate?: unknown;
+  readonly nb_read_frames?: unknown;
+  readonly nb_frames?: unknown;
+  readonly color_range?: unknown;
+  readonly color_space?: unknown;
+  readonly color_transfer?: unknown;
+  readonly color_primaries?: unknown;
+  readonly field_order?: unknown;
+  readonly disposition?: { readonly attached_pic?: unknown };
+  readonly tags?: { readonly rotate?: unknown; readonly alpha_mode?: unknown };
+  readonly side_data_list?: readonly unknown[];
+};
+
+type PixelFormat = {
+  readonly name?: unknown;
+  readonly flags?: { readonly alpha?: unknown };
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function object(value: unknown): JsonObject | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as JsonObject
+    : undefined;
+}
+
+async function runProcess(args: {
+  readonly executable: string;
+  readonly argv: readonly string[];
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+  readonly signal?: AbortSignal;
+}): Promise<Uint8Array> {
+  args.signal?.throwIfAborted();
+  return await new Promise((resolve, reject) => {
+    const child = spawn(args.executable, [...args.argv], {
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { PATH: process.env.PATH ?? "" },
+    });
+    const stdout: Buffer[] = [];
+    let bytes = 0;
+    let stderr = "";
+    let settled = false;
+    let failure: Error | undefined;
+    const stop = (error: Error) => {
+      failure ??= error;
+      child.kill("SIGKILL");
+    };
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      args.signal?.removeEventListener("abort", abort);
+      if (error === undefined) resolve(Buffer.concat(stdout));
+      else reject(error);
+    };
+    const abort = () => stop(args.signal?.reason ?? new Error("Process aborted"));
+    args.signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => {
+      stop(new Error(`${args.executable} timed out`));
+    }, args.timeoutMs);
+    child.stdout.on("data", (chunk: Buffer) => {
+      bytes += chunk.byteLength;
+      if (bytes > args.maxOutputBytes) {
+        stop(new Error(`${args.executable} output exceeded the configured limit`));
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      bytes += chunk.byteLength;
+      stderr = `${stderr}${chunk.toString()}`.slice(-8_000);
+      if (bytes > args.maxOutputBytes) {
+        stop(new Error(`${args.executable} output exceeded the configured limit`));
+      }
+    });
+    child.on("error", (error) => finish(error));
+    if (args.signal?.aborted) abort();
+    child.on("close", (code) => {
+      if (failure !== undefined) finish(failure);
+      else if (code === 0) finish();
+      else finish(new Error(`${args.executable} exited ${String(code)}: ${stderr}`));
+    });
+  });
+}
+
+function json(bytes: Uint8Array, subject: string): JsonObject {
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(bytes).toString("utf8"));
+  } catch {
+    throw new Error(`${subject} returned invalid JSON`);
+  }
+  const result = object(value);
+  assert(result !== undefined, `${subject} returned an invalid object`);
+  return result;
+}
+
+function positiveInteger(value: unknown, subject: string): number {
+  const parsed = typeof value === "number"
+    ? value
+    : typeof value === "string" && /^\d+$/u.test(value) ? Number(value) : NaN;
+  assert(Number.isSafeInteger(parsed) && parsed > 0, `${subject} is not a positive integer`);
+  return parsed;
+}
+
+function rational(value: unknown, subject: string): { readonly numerator: number; readonly denominator: number } {
+  assert(typeof value === "string" && /^\d+\/\d+$/u.test(value), `${subject} is not a rational`);
+  const [rawNumerator, rawDenominator] = value.split("/");
+  const numerator = Number(rawNumerator);
+  const denominator = Number(rawDenominator);
+  assert(Number.isSafeInteger(numerator) && numerator > 0
+    && Number.isSafeInteger(denominator) && denominator > 0, `${subject} is invalid`);
+  return { numerator, denominator };
+}
+
+function sameRational(
+  left: { readonly numerator: number; readonly denominator: number },
+  right: { readonly numerator: number; readonly denominator: number },
+): boolean {
+  return BigInt(left.numerator) * BigInt(right.denominator)
+    === BigInt(right.numerator) * BigInt(left.denominator);
+}
+
+function rotation(stream: ProbeStream): number {
+  const side = stream.side_data_list?.map(object).find((item) => item?.side_data_type === "Display Matrix");
+  const value = side?.rotation ?? stream.tags?.rotate ?? 0;
+  const parsed = typeof value === "number" ? value : Number(value);
+  assert(Number.isFinite(parsed), "Surface rotation metadata is invalid");
+  return ((parsed % 360) + 360) % 360;
+}
+
+function assertSrgb(stream: ProbeStream): void {
+  const allowed = {
+    color_space: new Set([undefined, "unknown", "gbr", "rgb", "bt709"]),
+    color_transfer: new Set([undefined, "unknown", "iec61966-2-1", "bt709"]),
+    color_primaries: new Set([undefined, "unknown", "bt709"]),
+    color_range: new Set([undefined, "unknown", "pc", "tv"]),
+  } as const;
+  for (const [name, values] of Object.entries(allowed)) {
+    const value = stream[name as keyof typeof allowed];
+    assert(typeof value === "string" || value === undefined, `Surface ${name} metadata is invalid`);
+    assert(values.has(value), `Surface ${name} ${String(value)} is not SDR sRGB-compatible`);
+  }
+}
+
+const pixelFormats = new Map<string, Map<string, boolean>>();
+
+async function pixelFormatAlpha(
+  ffprobePath: string,
+  timeoutMs: number,
+  maxOutputBytes: number,
+  signal: AbortSignal,
+): Promise<Map<string, boolean>> {
+  signal.throwIfAborted();
+  const cached = pixelFormats.get(ffprobePath);
+  if (cached !== undefined) return cached;
+  const root = json(await runProcess({ executable: ffprobePath,
+    argv: ["-v", "error", "-print_format", "json", "-show_pixel_formats"],
+    timeoutMs, maxOutputBytes, signal,
+  }), "ffprobe pixel-format query");
+  assert(Array.isArray(root.pixel_formats), "ffprobe returned no pixel-format table");
+  const result = new Map<string, boolean>();
+  for (const raw of root.pixel_formats) {
+    const format = object(raw) as PixelFormat | undefined;
+    if (typeof format?.name === "string") result.set(format.name, format.flags?.alpha === 1);
+  }
+  // Cache completed facts only; cancelling one caller cannot cancel another's probe.
+  pixelFormats.set(ffprobePath, result);
+  return result;
+}
+
+function suffix(mediaType: string): string {
+  if (mediaType === "image/png") return ".png";
+  if (mediaType === "image/webp") return ".webp";
+  if (mediaType === "video/webm") return ".webm";
+  if (mediaType === "video/mp4") return ".mp4";
+  throw new Error(`Surface media type ${mediaType} is unsupported`);
+}
+
+/**
+ * Decode and verify one typed Surface before its bytes enter a renderer.
+ *
+ * This is an admission gate, not a second media Product. Success returns no
+ * side-channel facts; anything a later graph step needs must be an explicit output.
+ */
+export async function verifyCompositableSurfaceBytes(options: {
+  readonly surface: CompositableSurfaceRef;
+  readonly bytes: Uint8Array;
+  readonly ffprobePath?: string;
+  readonly processTimeoutMs?: number;
+  readonly maxProbeOutputBytes?: number;
+  readonly signal?: AbortSignal;
+}): Promise<void> {
+  const controller = new AbortController();
+  const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
+  signal.throwIfAborted();
+  assertCompositableSurfaceRef(options.surface);
+  assert(options.bytes.byteLength === options.surface.artifact.size,
+    `Surface ${options.surface.artifact.resource} byte size differs`);
+  const ffprobePath = options.ffprobePath ?? "ffprobe";
+  const timeoutMs = options.processTimeoutMs ?? 120_000;
+  const maxOutputBytes = options.maxProbeOutputBytes ?? 8 * 1024 * 1024;
+  const directory = await mkdtemp(join(tmpdir(), "hypit-surface-verify-"));
+  try {
+    const path = join(directory, `surface${suffix(options.surface.artifact.mediaType)}`);
+    await writeFile(path, options.bytes, { signal });
+    const pending = [
+      runProcess({
+        executable: ffprobePath,
+        argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", path],
+        timeoutMs,
+        maxOutputBytes, signal,
+      }),
+      pixelFormatAlpha(ffprobePath, timeoutMs, maxOutputBytes, signal),
+    ] as const;
+    await Promise.allSettled(pending.map(async (job) => {
+      try { return await job; } catch (error) { controller.abort(error); throw error; }
+    }));
+    signal.throwIfAborted();
+    const [probe, formats] = await Promise.all(pending);
+    const root = json(probe, "ffprobe Surface query");
+    assert(Array.isArray(root.streams) && root.streams.length === 1,
+      "Surface must contain exactly one visual stream and no audio or auxiliary streams");
+    const stream = root.streams[0] as ProbeStream;
+    assert(stream.codec_type === "video", "Surface stream is not visual");
+    assert(stream.disposition?.attached_pic !== 1, "Surface cannot be an attached-picture stream");
+    const width = positiveInteger(stream.width, "Surface width");
+    const height = positiveInteger(stream.height, "Surface height");
+    assert(width === options.surface.width && height === options.surface.height,
+      "Surface decoded dimensions differ from its declaration");
+    assert(stream.sample_aspect_ratio === undefined || stream.sample_aspect_ratio === "1:1",
+      "Surface must use square pixels");
+    assert(rotation(stream) === 0, "Surface must not depend on display rotation metadata");
+    assert(stream.field_order === undefined || stream.field_order === "progressive" || stream.field_order === "unknown",
+      "Surface must be progressive");
+    assertSrgb(stream);
+
+    assert(typeof stream.pix_fmt === "string" && stream.pix_fmt.length > 0,
+      "Surface pixel format is absent");
+    const pixelAlpha = formats.get(stream.pix_fmt);
+    assert(pixelAlpha !== undefined, `Surface pixel format ${stream.pix_fmt} is unknown to ffprobe`);
+    const taggedAlpha = stream.tags?.alpha_mode === "1" || stream.tags?.alpha_mode === "straight";
+    const hasAlpha = pixelAlpha || taggedAlpha;
+    if (options.surface.alphaMode === "straight") {
+      assert(hasAlpha, "Surface declares straight alpha but its bytes carry no alpha channel");
+    } else {
+      assert(!hasAlpha, "Surface declares opaque pixels but its encoded format carries alpha");
+    }
+
+    const frameCount = positiveInteger(stream.nb_read_frames ?? stream.nb_frames, "Surface frame count");
+    if (options.surface.timing.kind === "still") {
+      assert(frameCount === 1, "Still Surface must decode to exactly one frame");
+    } else {
+      assert(frameCount === options.surface.timing.frameCount,
+        "Surface decoded frame count differs from its declaration");
+      const rate = rational(stream.avg_frame_rate ?? stream.r_frame_rate, "Surface frame rate");
+      assert(sameRational(rate, options.surface.timing.frameRate),
+        "Surface decoded frame rate differs from its declaration");
+    }
+  } finally {
+    await rm(directory, { recursive: true, force: true }).catch(() => {});
+  }
+}