@hraness/slopcamera 3.2.4

package/apps/desktop/application/operations/render/bind-candidate-output.ts

@@ -0,0 +1,324 @@
+import { z } from "zod";
+
+import {
+  ProjectRenderEncoderRecipeSchema,
+  ProjectRenderOutputRequestSchema,
+  ProjectRenderSyncPolicySchema,
+  ProjectRenderTargetSchema,
+  ProjectRenderToolchainSchema,
+  resolveProjectRenderEncoderRecipe,
+  type ProjectRenderToolchain,
+} from "../../../contracts";
+import {
+  canonicalJson,
+  canonicalJsonSha256,
+} from "../../../core";
+import {
+  CreativeCandidateRevisionReferenceV1Schema,
+} from "../../creative-iteration";
+import { ApplicationError } from "../../errors";
+import type { OperationDefinition } from "../../operation";
+import {
+  ProjectRenderPlanReferenceSchema,
+  RenderableProjectEditRevisionReferenceSchema,
+} from "../../receipts";
+import { throwIfAborted } from "../shared";
+
+/**
+ * Increment this ABI whenever Slopcamera's project-render implementation can
+ * change encoded output without changing the render plan or encoder recipe.
+ */
+export const SLOPCAMERA_PROJECT_RENDERER_ABI =
+  "slopcamera-project-renderer-abi-v1" as const;
+
+export const CandidateProjectRendererAbiSchema = z.string()
+  .min(1)
+  .max(80)
+  .regex(/^slopcamera-project-renderer-abi-v[1-9][0-9]*$/u);
+
+const CandidateRenderDerivationBodyV1Schema = z.strictObject({
+  binding: ProjectRenderToolchainSchema,
+  candidateRevision: CreativeCandidateRevisionReferenceV1Schema,
+  encoderRecipe: ProjectRenderEncoderRecipeSchema,
+  kind: z.union([
+    z.literal("slopcamera.candidate-render-derivation"),
+  ]),
+  maximumBytes: ProjectRenderOutputRequestSchema.shape.maximumBytes,
+  plan: ProjectRenderPlanReferenceSchema,
+  rendererAbi: CandidateProjectRendererAbiSchema,
+  revision: RenderableProjectEditRevisionReferenceSchema,
+  schemaVersion: z.literal(1),
+  syncPolicy: ProjectRenderSyncPolicySchema,
+  target: ProjectRenderTargetSchema,
+});
+
+export const CandidateRenderDerivationV1Schema =
+  CandidateRenderDerivationBodyV1Schema.extend({
+    derivationSha256: z.string().regex(/^[a-f0-9]{64}$/u),
+  }).strict().superRefine((derivation, context) => {
+    const body = CandidateRenderDerivationBodyV1Schema.parse({
+      binding: derivation.binding,
+      candidateRevision: derivation.candidateRevision,
+      encoderRecipe: derivation.encoderRecipe,
+      kind: derivation.kind,
+      maximumBytes: derivation.maximumBytes,
+      plan: derivation.plan,
+      rendererAbi: derivation.rendererAbi,
+      revision: derivation.revision,
+      schemaVersion: derivation.schemaVersion,
+      syncPolicy: derivation.syncPolicy,
+      target: derivation.target,
+    });
+    if (candidateRenderDerivationSha256(body) !== derivation.derivationSha256) {
+      context.addIssue({
+        code: "custom",
+        message: "Candidate render derivation hash does not match its exact inputs.",
+        path: ["derivationSha256"],
+      });
+    }
+    if (!candidateRenderRelationshipsAgree(derivation)) {
+      context.addIssue({
+        code: "custom",
+        message: "Candidate revision, renderable revision, and render plan must describe one exact derivation.",
+      });
+    }
+    if (
+      canonicalJson(derivation.encoderRecipe)
+      !== canonicalJson(resolveProjectRenderEncoderRecipe(derivation.target.tier))
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Candidate render encoder recipe must match its exact target tier.",
+        path: ["encoderRecipe"],
+      });
+    }
+  });
+
+export const BindCandidateRenderOutputInputRequestSchema = z.strictObject({
+  binding: ProjectRenderToolchainSchema.optional(),
+  candidateRevision: CreativeCandidateRevisionReferenceV1Schema,
+  maximumBytes: ProjectRenderOutputRequestSchema.shape.maximumBytes,
+  plan: ProjectRenderPlanReferenceSchema,
+  rendererAbi: CandidateProjectRendererAbiSchema.optional(),
+  revision: RenderableProjectEditRevisionReferenceSchema,
+  syncPolicy: ProjectRenderSyncPolicySchema,
+  target: ProjectRenderTargetSchema,
+});
+
+export const BindCandidateRenderOutputInputSchema =
+  BindCandidateRenderOutputInputRequestSchema.extend({
+    binding: ProjectRenderToolchainSchema,
+    rendererAbi: CandidateProjectRendererAbiSchema,
+  }).strict();
+
+export const CandidateProjectRenderInputSchema = z.strictObject({
+  binding: ProjectRenderToolchainSchema,
+  derivation: CandidateRenderDerivationV1Schema,
+  output: ProjectRenderOutputRequestSchema,
+  plan: ProjectRenderPlanReferenceSchema,
+  syncPolicy: ProjectRenderSyncPolicySchema,
+  target: ProjectRenderTargetSchema,
+}).superRefine((input, context) => {
+  if (
+    input.output.maximumBytes !== input.derivation.maximumBytes
+    || canonicalJson(input.binding) !== canonicalJson(input.derivation.binding)
+    || canonicalJson(input.plan) !== canonicalJson(input.derivation.plan)
+    || input.syncPolicy !== input.derivation.syncPolicy
+    || canonicalJson(input.target) !== canonicalJson(input.derivation.target)
+  ) {
+    context.addIssue({
+      code: "custom",
+      message: "Candidate render request does not match its complete derivation.",
+    });
+  }
+  const expectedPath = candidateRenderOutputPath(input.derivation);
+  if (input.output.path !== expectedPath) {
+    context.addIssue({
+      code: "custom",
+      message: "Candidate render output path is not addressed by its complete derivation.",
+      path: ["output", "path"],
+    });
+  }
+});
+
+export type BindCandidateRenderOutputInput = z.infer<
+  typeof BindCandidateRenderOutputInputSchema
+>;
+export type BindCandidateRenderOutputInputRequest = z.infer<
+  typeof BindCandidateRenderOutputInputRequestSchema
+>;
+export type CandidateProjectRenderInput = z.infer<
+  typeof CandidateProjectRenderInputSchema
+>;
+export type CandidateRenderDerivationV1 = z.infer<
+  typeof CandidateRenderDerivationV1Schema
+>;
+
+function candidateRenderRelationshipsAgree(input: {
+  readonly candidateRevision: BindCandidateRenderOutputInput["candidateRevision"];
+  readonly plan: BindCandidateRenderOutputInput["plan"];
+  readonly revision: BindCandidateRenderOutputInput["revision"];
+}): boolean {
+  const candidate = input.candidateRevision;
+  const revision = input.revision;
+  const plan = input.plan;
+  return !(
+    candidate.projectId !== revision.projectId
+    || candidate.projectSha256 !== revision.projectSha256
+    || candidate.projectStructureSha256 !== revision.projectStructureSha256
+    || candidate.projectEditPlanSha256 !== revision.projectEditPlanSha256
+    || candidate.revisionSha256 !== revision.revisionSha256
+    || candidate.planId !== revision.planId
+    || canonicalJson(candidate.artifact) !== canonicalJson(revision.artifact)
+    || canonicalJson(candidate.base.generation) !== canonicalJson(revision.baseGeneration)
+    || plan.projectId !== revision.projectId
+    || plan.projectSha256 !== revision.projectSha256
+    || plan.projectEditPlanSha256 !== revision.projectEditPlanSha256
+    || plan.revisionSha256 !== revision.revisionSha256
+    || plan.outputGeometrySha256 !== revision.outputGeometrySha256
+  );
+}
+
+function validateCandidateRenderRelationships(
+  input: BindCandidateRenderOutputInput,
+): void {
+  if (!candidateRenderRelationshipsAgree(input)) {
+    throw new ApplicationError(
+      "conflict",
+      "Candidate revision, renderable revision, and render plan must describe one exact derivation.",
+    );
+  }
+}
+
+export function assertCurrentCandidateProjectRendererAbi(
+  rendererAbi: string,
+): void {
+  if (rendererAbi !== SLOPCAMERA_PROJECT_RENDERER_ABI) {
+    throw new ApplicationError(
+      "incompatible",
+      "Candidate renderer ABI differs from the current Slopcamera project renderer.",
+      {
+        currentRendererAbi: SLOPCAMERA_PROJECT_RENDERER_ABI,
+        rendererAbi,
+      },
+    );
+  }
+}
+
+export function candidateRenderDerivationSha256(
+  input: z.input<typeof CandidateRenderDerivationBodyV1Schema>,
+): string {
+  const body = CandidateRenderDerivationBodyV1Schema.parse(input);
+  return canonicalJsonSha256({
+    domain: "slopcamera.candidate-render-derivation/v1",
+    ...body,
+  });
+}
+
+export function createCandidateRenderDerivationV1(
+  input: BindCandidateRenderOutputInput,
+): CandidateRenderDerivationV1 {
+  const exact = BindCandidateRenderOutputInputSchema.parse(input);
+  assertCurrentCandidateProjectRendererAbi(exact.rendererAbi);
+  validateCandidateRenderRelationships(exact);
+  const encoderRecipe = resolveProjectRenderEncoderRecipe(exact.target.tier);
+  const body = CandidateRenderDerivationBodyV1Schema.parse({
+    ...exact,
+    encoderRecipe,
+    kind: "slopcamera.candidate-render-derivation",
+    schemaVersion: 1,
+  });
+  return CandidateRenderDerivationV1Schema.parse({
+    ...body,
+    derivationSha256: candidateRenderDerivationSha256(body),
+  });
+}
+
+export function candidateRenderOutputPath(
+  derivationInput: CandidateRenderDerivationV1,
+): string {
+  const derivation = CandidateRenderDerivationV1Schema.parse(derivationInput);
+  return ProjectRenderOutputRequestSchema.shape.path.parse(
+    `renders/${derivation.candidateRevision.candidate.namespace}/${derivation.revision.revisionSha256}/derivations/${derivation.derivationSha256}.mp4`,
+  );
+}
+
+export function bindCandidateRenderOutputInput(
+  resolvedInput: unknown,
+  hostToolchain: ProjectRenderToolchain,
+): BindCandidateRenderOutputInput {
+  const requested = BindCandidateRenderOutputInputRequestSchema.parse(
+    resolvedInput,
+  );
+  const binding = ProjectRenderToolchainSchema.parse(hostToolchain);
+  if (
+    requested.binding !== undefined
+    && canonicalJson(requested.binding) !== canonicalJson(binding)
+  ) {
+    throw new ApplicationError(
+      "conflict",
+      "Candidate render tool binding changed after exact node planning.",
+    );
+  }
+  if (requested.rendererAbi !== undefined) {
+    assertCurrentCandidateProjectRendererAbi(requested.rendererAbi);
+  }
+  const exact = BindCandidateRenderOutputInputSchema.parse({
+    ...requested,
+    binding,
+    rendererAbi: SLOPCAMERA_PROJECT_RENDERER_ABI,
+  });
+  validateCandidateRenderRelationships(exact);
+  return exact;
+}
+
+export const bindCandidateRenderOutputOperationDefinition = {
+  inputSchema: BindCandidateRenderOutputInputSchema,
+  inputSchemaId: "slopcamera.operation.render.bind-candidate-output.input/v1",
+  kind: "render.bind-candidate-output",
+  lifecycle: {
+    kind: "pure",
+    execute: (context, input) => {
+      throwIfAborted(context.abortSignal);
+      const derivation = createCandidateRenderDerivationV1(input);
+      return Promise.resolve(CandidateProjectRenderInputSchema.parse({
+        binding: input.binding,
+        derivation,
+        output: {
+          maximumBytes: input.maximumBytes,
+          path: candidateRenderOutputPath(derivation),
+        },
+        plan: input.plan,
+        syncPolicy: input.syncPolicy,
+        target: input.target,
+      }));
+    },
+  },
+  outputSchema: CandidateProjectRenderInputSchema,
+  outputSchemaId: "slopcamera.operation.render.bind-candidate-output.output/v1",
+  policy: {
+    cache: "content-addressed",
+    cancellable: true,
+    effect: "pure",
+    maxDurationMs: 5_000,
+    maxFanOut: 0,
+    maxInputBytes: 64 * 1024,
+    maxOutputBytes: 64 * 1024,
+    preparation: [],
+    resources: [{ amount: 1, resource: "cpu" }],
+    resume: "deterministic",
+  },
+  summarize: output => ({
+    fields: {
+      derivationSha256: output.derivation.derivationSha256,
+      outputPath: output.output.path,
+      renderPlanSha256: output.plan.renderPlanSha256,
+    },
+    kind: "render.bind-candidate-output",
+  }),
+  version: 1,
+} satisfies OperationDefinition<
+  "render.bind-candidate-output",
+  BindCandidateRenderOutputInput,
+  CandidateProjectRenderInput
+>;

package/apps/desktop/application/operations/render/materialize-selection.ts

@@ -0,0 +1,322 @@
+import { z } from "zod";
+
+import {
+  canonicalJson,
+  sha256Hex,
+} from "../../../core";
+import {
+  createDeliveryMaterializationReceiptV1,
+  CreativeRenderNameSchema,
+  CreativeVariantKeySchema,
+  DeliveryMaterializationReceiptReferenceV1Schema,
+  DeliveryMaterializationReceiptV1Schema,
+  deliveryMaterializationReceiptPath,
+  deliveryMaterializationReceiptReferenceV1,
+  VariantSelectionReferenceV1Schema,
+  type DeliveryMaterializationReceiptV1,
+} from "../../creative-iteration";
+import {
+  ProjectRenderOutputPathSchema,
+} from "../../../contracts";
+import type { ApplicationContext } from "../../context";
+import { ApplicationError } from "../../errors";
+import type { OperationDefinition } from "../../operation";
+import { withOutputPublicationLease } from "../../output-publication-lease";
+import { ProjectReferenceSchema, throwIfAborted } from "../shared";
+import {
+  creativeProjectFileSystem,
+  loadCreativeCandidate,
+  loadVariantMatrix,
+  loadVariantSelection,
+  publishCreativeDocument,
+  verifyCandidateRender,
+} from "../iteration/shared";
+import { ProjectRenderOutputReferenceSchema } from "../../receipts";
+
+const MaterializeVariantSelectionUnboundInputSchema = z.strictObject({
+  deliveryKey: CreativeVariantKeySchema.default("delivery"),
+  destinationPath: ProjectRenderOutputPathSchema.optional(),
+  project: ProjectReferenceSchema,
+  renderName: CreativeRenderNameSchema,
+  selection: VariantSelectionReferenceV1Schema,
+}).superRefine((input, context) => {
+  if (input.project !== input.selection.base.projectId) {
+    context.addIssue({
+      code: "custom",
+      message: "Delivery materialization project does not match its selection.",
+      path: ["project"],
+    });
+  }
+});
+
+export const MaterializeVariantSelectionInputSchema =
+  MaterializeVariantSelectionUnboundInputSchema.safeExtend({
+    destinationPath: ProjectRenderOutputPathSchema,
+  }).strict();
+
+export const MaterializeVariantSelectionOutputSchema = z.strictObject({
+  output: ProjectRenderOutputReferenceSchema,
+  receipt: DeliveryMaterializationReceiptReferenceV1Schema,
+});
+
+export type MaterializeVariantSelectionInput = z.infer<
+  typeof MaterializeVariantSelectionInputSchema
+>;
+export type MaterializeVariantSelectionOutput = z.infer<
+  typeof MaterializeVariantSelectionOutputSchema
+>;
+
+export function defaultDeliveryMaterializationPath(input: {
+  readonly deliveryKey: string;
+  readonly renderName: string;
+  readonly selectionSha256: string;
+}): string {
+  return ProjectRenderOutputPathSchema.parse(
+    `renders/deliveries/selections/${input.selectionSha256}/${
+      CreativeVariantKeySchema.parse(input.deliveryKey)
+    }/${CreativeRenderNameSchema.parse(input.renderName)}.mp4`,
+  );
+}
+
+export function bindMaterializeVariantSelectionInput(
+  _application: ApplicationContext,
+  input: unknown,
+): MaterializeVariantSelectionInput {
+  const request = MaterializeVariantSelectionUnboundInputSchema.parse(input);
+  return MaterializeVariantSelectionInputSchema.parse({
+    ...request,
+    destinationPath: request.destinationPath
+      ?? defaultDeliveryMaterializationPath({
+        deliveryKey: request.deliveryKey,
+        renderName: request.renderName,
+        selectionSha256: request.selection.selectionSha256,
+      }),
+  });
+}
+
+function missing(error: unknown): boolean {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+
+async function loadExistingMaterialization(input: {
+  readonly fileSystem: Awaited<ReturnType<typeof creativeProjectFileSystem>>;
+  readonly path: string;
+}): Promise<{
+  readonly artifact: {
+    readonly bytes: number;
+    readonly path: string;
+    readonly sha256: string;
+  };
+  readonly receipt: DeliveryMaterializationReceiptV1;
+} | null> {
+  let contents: string;
+  try {
+    contents = await input.fileSystem.readText(input.path);
+  } catch (error) {
+    if (missing(error)) return null;
+    throw error;
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(contents) as unknown;
+  } catch {
+    throw new ApplicationError(
+      "invalid-data",
+      "Delivery materialization receipt is not valid JSON.",
+    );
+  }
+  const receipt = DeliveryMaterializationReceiptV1Schema.parse(value);
+  if (contents !== `${canonicalJson(receipt)}\n`) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Delivery materialization receipt is not canonical immutable JSON.",
+    );
+  }
+  return {
+    artifact: {
+      bytes: new TextEncoder().encode(contents).byteLength,
+      path: input.path,
+      sha256: sha256Hex(contents),
+    },
+    receipt,
+  };
+}
+
+export const materializeVariantSelectionOperationDefinition = {
+  inputSchema: MaterializeVariantSelectionInputSchema,
+  inputSchemaId: "slopcamera.operation.render.materialize-selection.input/v1",
+  kind: "render.materialize-selection",
+  lifecycle: {
+    kind: "local-artifact",
+    execute: async (context, input) => {
+      throwIfAborted(context.abortSignal);
+      const fileSystem = await creativeProjectFileSystem(
+        context.application,
+        input.project,
+      );
+      const selection = await loadVariantSelection({
+        fileSystem,
+        reference: input.selection,
+      });
+      const matrix = await loadVariantMatrix({
+        fileSystem,
+        reference: selection.matrix,
+      });
+      const chosen = matrix.candidates.find(candidate => (
+        candidate.candidate.candidateId === selection.chosen.candidate.candidateId
+      ));
+      if (
+        chosen === undefined
+        || canonicalJson(chosen) !== canonicalJson(selection.chosen)
+      ) {
+        throw new ApplicationError(
+          "conflict",
+          "Delivery selection is not an exact member of its closed matrix.",
+        );
+      }
+      const candidate = await loadCreativeCandidate({
+        fileSystem,
+        reference: chosen,
+      });
+      const render = candidate.renders.find(item => item.name === input.renderName);
+      if (render === undefined) {
+        throw new ApplicationError(
+          "not-found",
+          `Selected candidate has no verified render named ${input.renderName}.`,
+        );
+      }
+      if (!selection.result.renders.some(result => (
+        result.name === render.name
+        && result.outputSha256 === render.output.sha256
+        && result.receiptSha256 === render.receipt.receiptSha256
+      ))) {
+        throw new ApplicationError(
+          "conflict",
+          "Selected render hashes are absent from the immutable selection result.",
+        );
+      }
+      await verifyCandidateRender({ candidate, fileSystem, render });
+      if (render.output.path === input.destinationPath) {
+        throw new ApplicationError(
+          "conflict",
+          "Delivery materialization requires a new output path.",
+        );
+      }
+      const receipt = createDeliveryMaterializationReceiptV1({
+        candidate: chosen,
+        destinationPath: input.destinationPath,
+        renderName: input.renderName,
+        selection: input.selection,
+        source: render.output,
+      });
+      const receiptPath = deliveryMaterializationReceiptPath(
+        receipt.materializationSha256,
+      );
+      throwIfAborted(context.abortSignal);
+      return await withOutputPublicationLease(
+        context.application,
+        {
+          outputPath: input.destinationPath,
+          projectId: input.project,
+        },
+        async () => {
+          const existing = await loadExistingMaterialization({
+            fileSystem,
+            path: receiptPath,
+          });
+          if (existing !== null) {
+            if (canonicalJson(existing.receipt) !== canonicalJson(receipt)) {
+              throw new ApplicationError(
+                "conflict",
+                "Delivery materialization receipt path contains another result.",
+              );
+            }
+            if (fileSystem.inspectFile === undefined) {
+              throw new ApplicationError(
+                "internal",
+                "Project storage does not support delivery verification.",
+              );
+            }
+            const integrity = await fileSystem.inspectFile(input.destinationPath);
+            if (
+              integrity.bytes !== receipt.destination.bytes
+              || integrity.sha256 !== receipt.destination.sha256
+            ) {
+              throw new ApplicationError(
+                "conflict",
+                "Existing materialized delivery no longer matches its receipt.",
+              );
+            }
+            const reference = deliveryMaterializationReceiptReferenceV1(existing);
+            return MaterializeVariantSelectionOutputSchema.parse({
+              output: receipt.destination,
+              receipt: reference,
+            });
+          }
+          if (fileSystem.copyFileNoReplace === undefined) {
+            throw new ApplicationError(
+              "internal",
+              "Project storage does not support immutable delivery materialization.",
+            );
+          }
+          throwIfAborted(context.abortSignal);
+          await context.workflow?.beforePublication();
+          throwIfAborted(context.abortSignal);
+          await fileSystem.copyFileNoReplace(
+            render.output.path,
+            input.destinationPath,
+            render.output,
+          );
+          // Copy publication is the point of no return. Finalize its deterministic
+          // receipt even if cancellation arrives immediately afterward.
+          const artifact = await publishCreativeDocument({
+            document: receipt,
+            fileSystem,
+            path: receiptPath,
+            schema: DeliveryMaterializationReceiptV1Schema,
+          });
+          const reference = deliveryMaterializationReceiptReferenceV1({
+            artifact,
+            receipt,
+          });
+          return MaterializeVariantSelectionOutputSchema.parse({
+            output: receipt.destination,
+            receipt: reference,
+          });
+        },
+      );
+    },
+  },
+  outputSchema: MaterializeVariantSelectionOutputSchema,
+  outputSchemaId: "slopcamera.operation.render.materialize-selection.output/v1",
+  policy: {
+    cache: "none",
+    cancellable: true,
+    effect: "local-derived-write",
+    maxDurationMs: 6 * 60 * 60_000,
+    maxFanOut: 0,
+    maxInputBytes: 32 * 1024,
+    maxOutputBytes: 32 * 1024,
+    preparation: ["local-media"],
+    resources: [
+      { amount: 1, resource: "local-io" },
+      { amount: 1, resource: "output-publication" },
+    ],
+    resume: "deterministic",
+  },
+  receiptReference: output => output.receipt.artifact.path,
+  summarize: output => ({
+    fields: {
+      materializationSha256: output.receipt.materializationSha256,
+      outputPath: output.output.path,
+      outputSha256: output.output.sha256,
+      selectionSha256: output.receipt.selectionSha256,
+    },
+    kind: "render.materialize-selection",
+  }),
+  version: 1,
+} satisfies OperationDefinition<
+  "render.materialize-selection",
+  MaterializeVariantSelectionInput,
+  MaterializeVariantSelectionOutput
+>;