@hraness/slopcamera 3.2.4

package/apps/desktop/application/operations/iteration/shared.ts

@@ -0,0 +1,250 @@
+import type { z } from "zod";
+
+import {
+  canonicalJson,
+  createNodeBundleFileSystem,
+  saveImmutableText,
+  sha256Hex,
+  type BundleFileSystem,
+} from "../../../core";
+import type { ApplicationContext } from "../../context";
+import {
+  CreativeCandidateReferenceV1Schema,
+  CreativeCandidateV1Schema,
+  CreativeImmutableArtifactSchema,
+  creativeCandidateReferenceV1,
+  variantMatrixReferenceV1,
+  VariantMatrixReferenceV1Schema,
+  VariantMatrixV1Schema,
+  variantSelectionReferenceV1,
+  VariantSelectionReferenceV1Schema,
+  VariantSelectionV1Schema,
+  type CreativeCandidateReferenceV1,
+  type CreativeCandidateV1,
+  type VariantMatrixReferenceV1,
+  type VariantMatrixV1,
+  type VariantSelectionReferenceV1,
+  type VariantSelectionV1,
+} from "../../creative-iteration";
+import { ApplicationError } from "../../errors";
+import {
+  ProjectEditRevisionDocumentSchema,
+  ProjectRenderReceiptV2Schema,
+  type ProjectEditRevisionDocument,
+} from "../../receipts";
+import { exactProjectDirectory } from "../render/project-plan";
+
+type CreativeImmutableArtifact = z.infer<
+  typeof CreativeImmutableArtifactSchema
+>;
+
+function parseJson(text: string, label: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new ApplicationError(
+      "invalid-data",
+      `${label} is not valid JSON.`,
+    );
+  }
+}
+
+export async function creativeProjectFileSystem(
+  application: ApplicationContext,
+  projectId: string,
+): Promise<BundleFileSystem> {
+  return createNodeBundleFileSystem(await exactProjectDirectory(
+    application,
+    projectId,
+  ));
+}
+
+export async function publishCreativeDocument<Document>(input: {
+  readonly document: Document;
+  readonly fileSystem: BundleFileSystem;
+  readonly path: string;
+  readonly schema: z.ZodType<Document>;
+}): Promise<CreativeImmutableArtifact> {
+  const document = input.schema.parse(input.document);
+  const contents = `${canonicalJson(document)}\n`;
+  const artifact = CreativeImmutableArtifactSchema.parse({
+    bytes: new TextEncoder().encode(contents).byteLength,
+    path: input.path,
+    sha256: sha256Hex(contents),
+  });
+  await saveImmutableText(
+    input.fileSystem,
+    artifact.path,
+    contents,
+    artifact.sha256,
+  );
+  return artifact;
+}
+
+export async function loadCreativeDocument<Document>(input: {
+  readonly artifact: CreativeImmutableArtifact;
+  readonly fileSystem: BundleFileSystem;
+  readonly label: string;
+  readonly schema: z.ZodType<Document>;
+}): Promise<Document> {
+  const artifact = CreativeImmutableArtifactSchema.parse(input.artifact);
+  const contents = await input.fileSystem.readText(artifact.path);
+  const bytes = new TextEncoder().encode(contents).byteLength;
+  if (bytes !== artifact.bytes || sha256Hex(contents) !== artifact.sha256) {
+    throw new ApplicationError(
+      "conflict",
+      `${input.label} physical artifact hash or byte count changed.`,
+    );
+  }
+  const document = input.schema.parse(parseJson(contents, input.label));
+  if (contents !== `${canonicalJson(document)}\n`) {
+    throw new ApplicationError(
+      "invalid-data",
+      `${input.label} is not canonical immutable JSON.`,
+    );
+  }
+  return document;
+}
+
+export async function loadCreativeCandidate(input: {
+  readonly fileSystem: BundleFileSystem;
+  readonly reference: CreativeCandidateReferenceV1;
+}): Promise<CreativeCandidateV1> {
+  const reference = CreativeCandidateReferenceV1Schema.parse(input.reference);
+  const candidate = await loadCreativeDocument({
+    artifact: reference.artifact,
+    fileSystem: input.fileSystem,
+    label: "Creative candidate",
+    schema: CreativeCandidateV1Schema,
+  });
+  const expected = creativeCandidateReferenceV1({
+    artifact: reference.artifact,
+    candidate,
+  });
+  if (canonicalJson(expected) !== canonicalJson(reference)) {
+    throw new ApplicationError(
+      "conflict",
+      "Creative candidate document does not match its reference.",
+    );
+  }
+  return candidate;
+}
+
+export async function loadVariantMatrix(input: {
+  readonly fileSystem: BundleFileSystem;
+  readonly reference: VariantMatrixReferenceV1;
+}): Promise<VariantMatrixV1> {
+  const reference = VariantMatrixReferenceV1Schema.parse(input.reference);
+  const matrix = await loadCreativeDocument({
+    artifact: reference.artifact,
+    fileSystem: input.fileSystem,
+    label: "Variant matrix",
+    schema: VariantMatrixV1Schema,
+  });
+  const expected = variantMatrixReferenceV1({
+    artifact: reference.artifact,
+    matrix,
+  });
+  if (canonicalJson(expected) !== canonicalJson(reference)) {
+    throw new ApplicationError(
+      "conflict",
+      "Variant matrix document does not match its reference.",
+    );
+  }
+  return matrix;
+}
+
+export async function loadVariantSelection(input: {
+  readonly fileSystem: BundleFileSystem;
+  readonly reference: VariantSelectionReferenceV1;
+}): Promise<VariantSelectionV1> {
+  const reference = VariantSelectionReferenceV1Schema.parse(input.reference);
+  const selection = await loadCreativeDocument({
+    artifact: reference.artifact,
+    fileSystem: input.fileSystem,
+    label: "Variant selection",
+    schema: VariantSelectionV1Schema,
+  });
+  const expected = variantSelectionReferenceV1({
+    artifact: reference.artifact,
+    selection,
+  });
+  if (canonicalJson(expected) !== canonicalJson(reference)) {
+    throw new ApplicationError(
+      "conflict",
+      "Variant selection document does not match its reference.",
+    );
+  }
+  return selection;
+}
+
+export async function loadCandidateRevision(input: {
+  readonly candidate: CreativeCandidateV1;
+  readonly fileSystem: BundleFileSystem;
+}): Promise<ProjectEditRevisionDocument> {
+  const candidate = CreativeCandidateV1Schema.parse(input.candidate);
+  const revision = await loadCreativeDocument({
+    artifact: candidate.revision.artifact,
+    fileSystem: input.fileSystem,
+    label: "Creative candidate revision",
+    schema: ProjectEditRevisionDocumentSchema,
+  });
+  if (
+    revision.revisionSha256 !== candidate.revision.revisionSha256
+    || revision.projectSha256 !== candidate.revision.projectSha256
+    || revision.projectEditPlanSha256
+      !== candidate.revision.projectEditPlanSha256
+    || revision.projectSha256 !== candidate.base.generation.projectSha256
+  ) {
+    throw new ApplicationError(
+      "conflict",
+      "Creative candidate revision document does not match its candidate.",
+    );
+  }
+  return revision;
+}
+
+export async function verifyCandidateRender(input: {
+  readonly candidate: CreativeCandidateV1;
+  readonly fileSystem: BundleFileSystem;
+  readonly render: CreativeCandidateV1["renders"][number];
+}): Promise<void> {
+  const receipt = await loadCreativeDocument({
+    artifact: {
+      bytes: input.render.receipt.bytes,
+      path: input.render.receipt.path,
+      sha256: input.render.receipt.sha256,
+    },
+    fileSystem: input.fileSystem,
+    label: `Creative candidate render receipt ${input.render.name}`,
+    schema: ProjectRenderReceiptV2Schema,
+  });
+  if (
+    receipt.receiptSha256 !== input.render.receipt.receiptSha256
+    || receipt.run.nodePlanSha256 !== input.render.receipt.nodePlanSha256
+    || receipt.output.sha256 !== input.render.output.sha256
+    || canonicalJson(receipt.output) !== canonicalJson(input.render.output)
+    || receipt.output.revisionSha256 !== input.candidate.revision.revisionSha256
+  ) {
+    throw new ApplicationError(
+      "conflict",
+      `Creative candidate render ${input.render.name} is not bound to its verified receipt.`,
+    );
+  }
+  if (input.fileSystem.inspectFile === undefined) {
+    throw new ApplicationError(
+      "internal",
+      "Project storage does not support immutable render verification.",
+    );
+  }
+  const integrity = await input.fileSystem.inspectFile(input.render.output.path);
+  if (
+    integrity.bytes !== input.render.output.bytes
+    || integrity.sha256 !== input.render.output.sha256
+  ) {
+    throw new ApplicationError(
+      "conflict",
+      `Creative candidate render ${input.render.name} bytes changed after verification.`,
+    );
+  }
+}

package/apps/desktop/application/operations/media/audio-effects.ts

@@ -0,0 +1,376 @@
+import { Effect } from "effect";
+
+import { z } from "zod";
+
+import {
+  AudioEffectsTransformV1Schema,
+  type AudioEffectsTransformV1,
+} from "../../../contracts";
+import {
+  type ExpectedLocalMediaInput,
+  type LocalMediaTransformResult,
+} from "../../../cli/media-effects-service";
+import {
+  type ProbedMedia,
+} from "../../../cli/media-ingest";
+import type {
+  ApplicationContext,
+  ApplicationProcessRunner,
+} from "../../context";
+import { ApplicationError } from "../../errors";
+import type { OperationDefinition, OperationExecutionContext } from "../../operation";
+import { operationResource, operationValidation, runStandaloneOperation, type OperationEffectFailure } from "../../operation-effects";
+import { createMediaTransformPlatform, MediaTransformPlatform } from "./transform-platform";
+import {
+  MediaCapabilityBindingsSchema,
+  bindExpectedMediaCapabilities,
+  mediaCapabilityCommand,
+  mediaCapabilityVersion,
+} from "./capabilities";
+import {
+  MAXIMUM_MEDIA_EFFECT_INPUT_BYTES,
+  MediaArtifactReferenceSchema,
+  MediaArtifactRequestSchema,
+  bindRepositoryMedia,
+} from "./shared";
+
+const MAXIMUM_EFFECT_DURATION_US = 24 * 60 * 60 * 1_000_000;
+
+export const MediaAudioEffectsReceiptSchema = z.strictObject({
+  createdAt: z.string().datetime({ offset: true }),
+  ffmpegVersion: z.string().min(1).max(256),
+  ffprobeVersion: z.string().min(1).max(256),
+  filterGraph: z.string().min(1).max(256 * 1024),
+  input: MediaArtifactReferenceSchema,
+  kind: z.union([
+    z.literal("slopcamera.local-media-transform-receipt"),
+    z.literal("studio.local-media-transform-receipt"),
+  ]),
+  operation: z.literal("audio-effects"),
+  output: MediaArtifactReferenceSchema.extend({
+    durationUs: z.number().int().safe().positive(),
+  }).strict(),
+  schemaVersion: z.literal(1),
+  sourceDurationUs: z.number().int().safe().positive(),
+  transform: AudioEffectsTransformV1Schema,
+});
+
+export const MediaAudioEffectsInputSchema = z.strictObject({
+  capabilityBindings: MediaCapabilityBindingsSchema.optional(),
+  input: MediaArtifactRequestSchema,
+  transform: AudioEffectsTransformV1Schema,
+});
+
+export const BoundMediaAudioEffectsInputSchema =
+  MediaAudioEffectsInputSchema.extend({
+    input: MediaArtifactReferenceSchema,
+  }).strict();
+
+export const MediaAudioEffectsOutputSchema = z.strictObject({
+  artifact: MediaArtifactReferenceSchema,
+  created: z.boolean(),
+  durationUs: z.number().int().safe().positive(),
+  filterGraph: z.string().min(1).max(256 * 1024),
+  receipt: MediaArtifactReferenceSchema,
+  transform: AudioEffectsTransformV1Schema,
+});
+
+export type MediaAudioEffectsInput = z.infer<typeof MediaAudioEffectsInputSchema>;
+export type BoundMediaAudioEffectsInput =
+  z.infer<typeof BoundMediaAudioEffectsInputSchema>;
+export type MediaAudioEffectsOutput =
+  z.infer<typeof MediaAudioEffectsOutputSchema>;
+
+export interface AudioEffectsExecutionOptions {
+  readonly expectedInput: ExpectedLocalMediaInput;
+  readonly ffmpeg: string;
+  readonly inputPath: string;
+  readonly outputPath: string;
+  readonly runner: ApplicationProcessRunner;
+  readonly transform: AudioEffectsTransformV1;
+}
+
+type AudioEffectsExecutor = (
+  options: AudioEffectsExecutionOptions,
+) => Promise<LocalMediaTransformResult<AudioEffectsTransformV1>>;
+
+type MediaProbeExecutor = (
+  ffprobe: string,
+  runner: ApplicationProcessRunner,
+  path: string,
+) => Promise<ProbedMedia>;
+
+export interface MediaAudioEffectsOperationDependencies {
+  readonly probe?: MediaProbeExecutor;
+  readonly render?: AudioEffectsExecutor;
+}
+
+export async function bindMediaAudioEffectsInput(
+  application: ApplicationContext,
+  input: unknown,
+  signal: AbortSignal,
+): Promise<BoundMediaAudioEffectsInput> {
+  const parsed = MediaAudioEffectsInputSchema.parse(input);
+  const [bound, capabilityBindings] = await Promise.all([
+    bindRepositoryMedia(
+      application,
+      parsed.input,
+      signal,
+      MAXIMUM_MEDIA_EFFECT_INPUT_BYTES,
+    ),
+    bindExpectedMediaCapabilities(
+      application,
+      ["ffmpeg", "ffprobe"],
+      parsed.capabilityBindings,
+    ),
+  ]);
+  return BoundMediaAudioEffectsInputSchema.parse({
+    ...parsed,
+    capabilityBindings,
+    input: bound.artifact,
+  });
+}
+
+function audioOutputExtension(transform: AudioEffectsTransformV1): string {
+  if (transform.output.kind === "preserve-video") {
+    return transform.output.profile === "aac" ? ".mp4" : ".mkv";
+  }
+  switch (transform.output.profile) {
+    case "wav-pcm-s16le": return ".wav";
+    case "flac": return ".flac";
+    case "mp3": return ".mp3";
+    case "aac": return ".m4a";
+    case "opus": return ".opus";
+  }
+}
+
+function assertProbeEnvelope(probe: ProbedMedia): void {
+  if (
+    probe.durationUs <= 0
+    || probe.durationUs > MAXIMUM_EFFECT_DURATION_US
+    || probe.streams.length > 64
+  ) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Media exceeds the local-effects duration or stream-count limit.",
+    );
+  }
+}
+
+function selectedAudioDuration(
+  probe: ProbedMedia,
+  transform: AudioEffectsTransformV1,
+): number {
+  assertProbeEnvelope(probe);
+  const audioStreams = probe.streams.filter(
+    stream => stream.codec_type === "audio",
+  );
+  const selected = audioStreams[transform.audioStreamIndex];
+  if (selected === undefined) {
+    throw new ApplicationError(
+      "usage",
+      `Audio stream ${String(transform.audioStreamIndex)} is out of range.`,
+    );
+  }
+  if (transform.output.kind === "preserve-video") {
+    const preserveVideo = transform.output;
+    const videoStreams = probe.streams.filter(
+      stream => stream.codec_type === "video",
+    );
+    const selectedVideo = preserveVideo.inputVideoStreamIndex === undefined
+      ? videoStreams[preserveVideo.videoStreamIndex]
+      : videoStreams.find(
+          stream => stream.index === preserveVideo.inputVideoStreamIndex,
+        );
+    if (selectedVideo === undefined) {
+      throw new ApplicationError(
+        "usage",
+        "The selected preserve-video stream is out of range.",
+      );
+    }
+  }
+  return selected.assetRange.endUs - selected.assetRange.startUs;
+}
+
+function verifiedAudioDuration(
+  probe: ProbedMedia,
+  sourceDurationUs: number,
+  preserveVideo: boolean,
+): number {
+  assertProbeEnvelope(probe);
+  const audio = probe.streams.find(stream => stream.codec_type === "audio");
+  if (audio === undefined) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Derived audio-effects media contains no audio stream.",
+    );
+  }
+  if (
+    preserveVideo
+    && !probe.streams.some(stream => stream.codec_type === "video")
+  ) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Derived preserve-video media contains no video stream.",
+    );
+  }
+  const durationUs = audio.assetRange.endUs - audio.assetRange.startUs;
+  if (durationUs + 250_000 < sourceDurationUs) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Derived audio coverage is shorter than the selected source stream.",
+    );
+  }
+  if (durationUs > sourceDurationUs + 31_000_000) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Derived audio exceeds the bounded delay/reverb tail.",
+    );
+  }
+  return durationUs;
+}
+
+/** Native transform owner; foreign work settles before workspace release. */
+export function mediaAudioEffectsProgram(input: MediaAudioEffectsInput): Effect.Effect<
+  MediaAudioEffectsOutput, OperationEffectFailure, MediaTransformPlatform
+> {
+  return Effect.gen(function*() {
+    const platform = yield* MediaTransformPlatform;
+    yield* platform.checkAbort();
+    const parsed = yield* operationValidation("input", () => MediaAudioEffectsInputSchema.parse(input));
+    const boundMedia = yield* platform.bindInput(parsed.input);
+    const boundInput = yield* operationValidation("input", () => BoundMediaAudioEffectsInputSchema.parse({
+      ...parsed, input: boundMedia.artifact,
+    }));
+    yield* platform.assertCapabilities(parsed.capabilityBindings);
+    const capabilityBindings = parsed.capabilityBindings ?? (yield* platform.bindCapabilities());
+    const { ffmpeg, ffprobe } = yield* operationValidation("capability", () => ({
+      ffmpeg: mediaCapabilityCommand(capabilityBindings, "ffmpeg"),
+      ffprobe: mediaCapabilityCommand(capabilityBindings, "ffprobe"),
+    }));
+    const runner = yield* platform.runner(capabilityBindings);
+    const sourceProbe = yield* platform.probe(ffprobe, runner, boundMedia.absolutePath);
+    const sourceDurationUs = yield* operationValidation("media", () => selectedAudioDuration(sourceProbe, boundInput.transform));
+    return yield* operationResource(
+      platform.workspace(),
+      workspace => Effect.gen(function*() {
+        const extension = yield* operationValidation("input", () => audioOutputExtension(boundInput.transform));
+        const stagedPath = yield* platform.stagedPath(workspace, "audio", extension);
+        const rendered = yield* platform.renderAudio({
+          expectedInput: boundMedia.expectedInput,
+          ffmpeg,
+          inputPath: boundMedia.absolutePath,
+          outputPath: stagedPath,
+          runner,
+          transform: boundInput.transform,
+        });
+        yield* platform.checkAbort();
+        const outputProbe = yield* platform.probe(ffprobe, runner, stagedPath);
+        const durationUs = yield* operationValidation("media", () => verifiedAudioDuration(
+          outputProbe, sourceDurationUs, boundInput.transform.output.kind === "preserve-video",
+        ));
+        // Existing native publication fences still inspect the AbortSignal.
+        // Once entered, retain the whole output/receipt/checkpoint continuation.
+        return yield* Effect.uninterruptible(Effect.gen(function*() {
+          const published = yield* platform.publishMedia(stagedPath, extension);
+          yield* operationValidation("publication", () => {
+            if (published.artifact.bytes !== rendered.bytes || published.artifact.sha256 !== rendered.sha256) {
+              throw new ApplicationError("conflict", "Audio-effects service result disagrees with the published bytes.");
+            }
+          });
+          const createdAt = yield* platform.now();
+          const receiptBody = yield* operationValidation("output", () => MediaAudioEffectsReceiptSchema.parse({
+            createdAt,
+            ffmpegVersion: mediaCapabilityVersion(capabilityBindings, "ffmpeg"),
+            ffprobeVersion: mediaCapabilityVersion(capabilityBindings, "ffprobe"),
+            filterGraph: rendered.filterGraph,
+            input: boundInput.input,
+            kind: "slopcamera.local-media-transform-receipt",
+            operation: "audio-effects",
+            output: { ...published.artifact, durationUs },
+            schemaVersion: 1,
+            sourceDurationUs,
+            transform: rendered.transform,
+          }));
+          const receipt = yield* platform.publishReceipt(receiptBody, workspace);
+          const output = yield* operationValidation("output", () => MediaAudioEffectsOutputSchema.parse({
+            artifact: published.artifact,
+            created: published.created,
+            durationUs,
+            filterGraph: rendered.filterGraph,
+            receipt,
+            transform: rendered.transform,
+          }));
+          yield* platform.checkpoint({
+            inputSchemaId: "slopcamera.operation.media.audio-effects.input/v1",
+            kind: "media.audio-effects",
+            outputSchemaId: "slopcamera.operation.media.audio-effects.output/v1",
+            version: 1,
+          }, output);
+          return output;
+        }));
+      }),
+      workspace => platform.dispose(workspace),
+    );
+  });
+}
+
+export function createMediaAudioEffectsOperationDefinition(
+  dependencies: MediaAudioEffectsOperationDependencies = {},
+): OperationDefinition<
+  "media.audio-effects",
+  MediaAudioEffectsInput,
+  MediaAudioEffectsOutput
+> {
+  const executeEffect = (context: OperationExecutionContext, input: MediaAudioEffectsInput) =>
+    mediaAudioEffectsProgram(input).pipe(Effect.provideService(MediaTransformPlatform, createMediaTransformPlatform(context, {
+      ...(dependencies.probe === undefined ? {} : { probe: dependencies.probe }),
+      ...(dependencies.render === undefined ? {} : { renderAudio: dependencies.render }),
+    })));
+  return {
+    inputSchema: MediaAudioEffectsInputSchema,
+    inputSchemaId: "slopcamera.operation.media.audio-effects.input/v1",
+    kind: "media.audio-effects",
+    lifecycle: {
+      kind: "local-artifact",
+      execute: async (context, input) => await runStandaloneOperation(executeEffect(context, input)),
+      executeEffect,
+    },
+    outputSchema: MediaAudioEffectsOutputSchema,
+    outputSchemaId: "slopcamera.operation.media.audio-effects.output/v1",
+    policy: {
+      cache: "exact-run",
+      cancellable: true,
+      effect: "local-derived-write",
+      maxDurationMs: 12 * 60 * 60_000,
+      maxFanOut: 0,
+      maxInputBytes: 512 * 1024,
+      maxOutputBytes: 512 * 1024,
+      preparation: ["local-media"],
+      resources: [
+        { amount: 1, resource: "cpu" },
+        { amount: 1, resource: "ffmpeg" },
+        { amount: 1, resource: "local-io" },
+        { amount: 1, resource: "output-publication" },
+      ],
+      resume: "verified-receipt",
+    },
+    receiptReference: output => output.receipt.path,
+    summarize: output => ({
+      fields: {
+        bytes: output.artifact.bytes,
+        created: output.created,
+        durationUs: output.durationUs,
+        effects: output.transform.effects.length,
+        path: output.artifact.path,
+        receipt: output.receipt.path,
+        sha256: output.artifact.sha256,
+      },
+      kind: "media.audio-effects",
+    }),
+    version: 1,
+  };
+}
+
+export const mediaAudioEffectsOperationDefinition =
+  createMediaAudioEffectsOperationDefinition();

package/apps/desktop/application/operations/media/binding.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+import type { ApplicationContext } from "../../context";
+import {
+  MediaAudioEffectsInputSchema,
+  bindMediaAudioEffectsInput,
+} from "./audio-effects";
+import {
+  MediaColorGradeInputSchema,
+  bindMediaColorGradeInput,
+} from "./color-grade";
+import {
+  MediaIngestInputSchema,
+  bindMediaIngestInput,
+} from "./ingest";
+import {
+  HtmlOverlayInputSchema,
+  bindHtmlOverlayInput,
+} from "./html-overlay";
+import {
+  MediaOverlayInputSchema,
+  bindMediaOverlayInput,
+} from "./overlay";
+
+export const MEDIA_OPERATION_KINDS = [
+  "media.ingest",
+  "media.html-overlay",
+  "media.overlay",
+  "media.audio-effects",
+  "media.color-grade",
+] as const;
+
+export const MediaOperationKindSchema = z.enum(MEDIA_OPERATION_KINDS);
+export type MediaOperationKind = z.infer<typeof MediaOperationKindSchema>;
+
+/**
+ * Resolve a progressive path-only request into the exact byte identity that a
+ * workflow node plan hashes. Execution binds the same input again immediately
+ * before use, so planning does not substitute for the descriptor-pinned read.
+ */
+export async function bindMediaOperationInput(
+  application: ApplicationContext,
+  kind: MediaOperationKind,
+  input: unknown,
+  signal: AbortSignal = new AbortController().signal,
+): Promise<unknown> {
+  switch (kind) {
+    case "media.ingest":
+      return await bindMediaIngestInput(
+        application,
+        MediaIngestInputSchema.parse(input),
+        signal,
+      );
+    case "media.overlay":
+      return await bindMediaOverlayInput(
+        application,
+        MediaOverlayInputSchema.parse(input),
+        signal,
+      );
+    case "media.html-overlay":
+      return await bindHtmlOverlayInput(
+        application,
+        HtmlOverlayInputSchema.parse(input),
+        signal,
+      );
+    case "media.audio-effects":
+      return await bindMediaAudioEffectsInput(
+        application,
+        MediaAudioEffectsInputSchema.parse(input),
+        signal,
+      );
+    case "media.color-grade":
+      return await bindMediaColorGradeInput(
+        application,
+        MediaColorGradeInputSchema.parse(input),
+        signal,
+      );
+  }
+}