@hraness/slopcamera 3.2.4

package/apps/desktop/application/operation-completion-checkpoint.ts

@@ -0,0 +1,333 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import {
+  link,
+  lstat,
+  open,
+  realpath,
+  rm,
+} from "node:fs/promises";
+import {
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from "node:path";
+
+import { z } from "zod";
+
+import { Sha256Schema } from "../contracts";
+import {
+  canonicalJson,
+  sha256Hex,
+} from "../core/canonical-json";
+import { ensurePrivateDirectory } from "../cli/paths";
+import { ApplicationError } from "./errors";
+import type {
+  OperationExecutionContext,
+  OperationKind,
+} from "./operation";
+
+export const OPERATION_COMPLETION_CHECKPOINT_FILE =
+  "operation-completion.v1.json";
+
+const MAXIMUM_CHECKPOINT_BYTES = 65 * 1024 * 1024;
+const OUTPUT_DIGEST_DOMAIN = "studio.workflow.operation-completion-output/v1";
+
+const OperationCompletionCheckpointSchema = z.strictObject({
+  identity: z.strictObject({
+    inputSchemaId: z.string().min(1).max(256),
+    kind: z.string().min(1).max(128),
+    nodeKey: z.string().min(1).max(255).regex(
+      /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*(?:\/[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*)*$/u,
+    ),
+    nodePlanSha256: Sha256Schema,
+    outputSchemaId: z.string().min(1).max(256),
+    runId: z.string().min(1).max(256),
+    version: z.number().int().safe().positive(),
+  }),
+  kind: z.literal("slopcamera.workflow-operation-completion"),
+  output: z.unknown(),
+  outputSha256: Sha256Schema,
+  schemaVersion: z.literal(1),
+}).superRefine((checkpoint, context) => {
+  let digest: string;
+  try {
+    digest = operationCheckpointOutputSha256(checkpoint.output);
+  } catch {
+    context.addIssue({
+      code: "custom",
+      message: "Operation completion output must be canonical JSON.",
+      path: ["output"],
+    });
+    return;
+  }
+  if (digest !== checkpoint.outputSha256) {
+    context.addIssue({
+      code: "custom",
+      message: "Operation completion output digest does not match its payload.",
+      path: ["outputSha256"],
+    });
+  }
+});
+
+export interface OperationCheckpointDefinitionIdentity {
+  readonly inputSchemaId: string;
+  readonly kind: OperationKind;
+  readonly outputSchemaId: string;
+  readonly version: number;
+}
+
+export interface OperationCheckpointExecutionIdentity
+  extends OperationCheckpointDefinitionIdentity {
+  readonly nodeKey: string;
+  readonly nodePlanSha256: string;
+  readonly runId: string;
+}
+
+export type OperationCompletionCheckpoint = z.infer<
+  typeof OperationCompletionCheckpointSchema
+>;
+
+function operationCheckpointOutputSha256(output: unknown): string {
+  return sha256Hex(
+    `${OUTPUT_DIGEST_DOMAIN}\0${canonicalJson(output)}`,
+  );
+}
+
+function isWithin(root: string, candidate: string): boolean {
+  const fromRoot = relative(root, candidate);
+  return fromRoot === ""
+    || (!fromRoot.startsWith("..") && !isAbsolute(fromRoot));
+}
+
+async function physicalPrivateWorkspace(
+  privateRootInput: string,
+  workspaceInput: string,
+): Promise<string> {
+  await ensurePrivateDirectory(privateRootInput);
+  const privateRoot = await realpath(resolve(privateRootInput));
+  const workspace = resolve(workspaceInput);
+  const details = await lstat(workspace).catch((error: unknown) => {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      throw new ApplicationError(
+        "invalid-data",
+        "Operation completion workspace does not exist.",
+      );
+    }
+    throw error;
+  });
+  if (
+    details.isSymbolicLink()
+    || !details.isDirectory()
+    || (details.mode & 0o077) !== 0
+  ) {
+    throw new ApplicationError(
+      "unsafe-path",
+      "Operation completion workspace must be a private physical directory.",
+    );
+  }
+  const physical = await realpath(workspace);
+  if (physical === privateRoot || !isWithin(privateRoot, physical)) {
+    throw new ApplicationError(
+      "unsafe-path",
+      "Operation completion workspace escaped the application private root.",
+    );
+  }
+  return physical;
+}
+
+async function syncDirectory(path: string): Promise<void> {
+  const directory = await open(
+    path,
+    constants.O_RDONLY | (constants.O_DIRECTORY ?? 0),
+  );
+  try {
+    await directory.sync();
+  } finally {
+    await directory.close();
+  }
+}
+
+function checkpointFor(
+  identity: OperationCheckpointExecutionIdentity,
+  output: unknown,
+): OperationCompletionCheckpoint {
+  return OperationCompletionCheckpointSchema.parse({
+    identity,
+    kind: "slopcamera.workflow-operation-completion",
+    output,
+    outputSha256: operationCheckpointOutputSha256(output),
+    schemaVersion: 1,
+  });
+}
+
+async function readCheckpointFile(
+  path: string,
+): Promise<OperationCompletionCheckpoint | null> {
+  let handle;
+  try {
+    handle = await open(
+      path,
+      constants.O_RDONLY
+        | (constants.O_NOFOLLOW ?? 0)
+        | (constants.O_NONBLOCK ?? 0),
+    );
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+  try {
+    const before = await handle.stat();
+    if (
+      !before.isFile()
+      || before.nlink !== 1
+      || before.size < 1
+      || before.size > MAXIMUM_CHECKPOINT_BYTES
+      || (before.mode & 0o077) !== 0
+    ) {
+      throw new ApplicationError(
+        "invalid-data",
+        "Operation completion checkpoint is unsafe or exceeds its size bound.",
+      );
+    }
+    const text = await handle.readFile("utf8");
+    const after = await handle.stat();
+    if (
+      before.dev !== after.dev
+      || before.ino !== after.ino
+      || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs
+      || before.ctimeMs !== after.ctimeMs
+    ) {
+      throw new ApplicationError(
+        "conflict",
+        "Operation completion checkpoint changed while it was being read.",
+      );
+    }
+    let input: unknown;
+    try {
+      input = JSON.parse(text) as unknown;
+    } catch {
+      throw new ApplicationError(
+        "invalid-data",
+        "Operation completion checkpoint is not valid JSON.",
+      );
+    }
+    const parsed = OperationCompletionCheckpointSchema.parse(input);
+    if (`${canonicalJson(parsed)}\n` !== text) {
+      throw new ApplicationError(
+        "invalid-data",
+        "Operation completion checkpoint is not canonical immutable JSON.",
+      );
+    }
+    return parsed;
+  } finally {
+    await handle.close();
+  }
+}
+
+function assertCheckpointIdentity(
+  actual: OperationCompletionCheckpoint["identity"],
+  expected: OperationCheckpointExecutionIdentity,
+): void {
+  if (canonicalJson(actual) !== canonicalJson(expected)) {
+    throw new ApplicationError(
+      "conflict",
+      "Operation completion checkpoint belongs to a different exact node plan.",
+      {
+        actualNodePlanSha256: actual.nodePlanSha256,
+        expectedNodePlanSha256: expected.nodePlanSha256,
+        nodeKey: expected.nodeKey,
+      },
+    );
+  }
+}
+
+export async function writeOperationCompletionCheckpoint(
+  context: OperationExecutionContext,
+  definition: OperationCheckpointDefinitionIdentity,
+  output: unknown,
+): Promise<void> {
+  const workflow = context.workflow;
+  if (workflow === undefined) return;
+  const workspace = await physicalPrivateWorkspace(
+    context.application.paths.privateRoot,
+    workflow.workspaceDirectory,
+  );
+  const checkpoint = checkpointFor({
+    ...definition,
+    nodeKey: workflow.nodeKey,
+    nodePlanSha256: workflow.nodePlanSha256,
+    runId: workflow.runId,
+  }, output);
+  const source = `${canonicalJson(checkpoint)}\n`;
+  const bytes = new TextEncoder().encode(source);
+  if (bytes.byteLength > MAXIMUM_CHECKPOINT_BYTES) {
+    throw new ApplicationError(
+      "invalid-data",
+      "Operation completion checkpoint exceeds its size bound.",
+    );
+  }
+  await workflow.beforePublication();
+  const temporary = join(
+    workspace,
+    `.operation-completion-${randomUUID()}.json`,
+  );
+  const target = join(workspace, OPERATION_COMPLETION_CHECKPOINT_FILE);
+  const handle = await open(
+    temporary,
+    constants.O_CREAT
+      | constants.O_EXCL
+      | constants.O_WRONLY
+      | (constants.O_NOFOLLOW ?? 0),
+    0o600,
+  );
+  try {
+    await handle.writeFile(bytes);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  try {
+    try {
+      await link(temporary, target);
+      await syncDirectory(workspace);
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) {
+        throw error;
+      }
+      const existing = await readCheckpointFile(target);
+      if (
+        existing === null
+        || canonicalJson(existing) !== canonicalJson(checkpoint)
+      ) {
+        throw new ApplicationError(
+          "conflict",
+          "The exact node workspace already contains a different completion checkpoint.",
+        );
+      }
+    }
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}
+
+export async function readOperationCompletionCheckpoint(options: {
+  readonly expected: OperationCheckpointExecutionIdentity;
+  readonly privateRoot: string;
+  readonly workspaceDirectory: string;
+}): Promise<OperationCompletionCheckpoint | null> {
+  const workspace = await physicalPrivateWorkspace(
+    options.privateRoot,
+    options.workspaceDirectory,
+  );
+  const checkpoint = await readCheckpointFile(
+    join(workspace, OPERATION_COMPLETION_CHECKPOINT_FILE),
+  );
+  if (checkpoint === null) return null;
+  assertCheckpointIdentity(checkpoint.identity, options.expected);
+  return checkpoint;
+}

package/apps/desktop/application/operation-effects.ts

@@ -0,0 +1,94 @@
+import { Cause, Effect, Exit } from "effect";
+
+export type OperationFailurePhase = "input" | "execution" | "output" | "media" | "capability" | "project" | "workspace" | "publication" | "checkpoint" | "cleanup";
+export type OperationEffectFailure = Readonly<{
+  _tag: "OperationBoundaryFailure";
+  phase: OperationFailurePhase;
+  cause: unknown;
+  /** Earlier native failures; never part of the public rejection or a receipt. */
+  priorCause?: Cause.Cause<OperationEffectFailure>;
+}>;
+
+/** Native application ports preserve their existing public exception identity. */
+export function operationBoundary<A>(
+  phase: OperationFailurePhase,
+  execute: () => A | Promise<A>,
+): Effect.Effect<A, OperationEffectFailure> {
+  return Effect.tryPromise({
+    try: async () => await execute(),
+    catch: (cause): OperationEffectFailure => ({ _tag: "OperationBoundaryFailure", phase, cause }),
+  });
+}
+
+export function operationValidation<A>(
+  phase: OperationFailurePhase,
+  evaluate: () => A,
+): Effect.Effect<A, OperationEffectFailure> {
+  return Effect.try({
+    try: evaluate,
+    catch: (cause): OperationEffectFailure => ({ _tag: "OperationBoundaryFailure", phase, cause }),
+  });
+}
+
+function operationCauseValue(cause: Cause.Cause<OperationEffectFailure>): unknown {
+  const failures = [
+    ...Array.from(Cause.failures(cause), failure => failure.cause),
+    ...Cause.defects(cause),
+  ];
+  if (failures.length === 1) return failures[0];
+  if (failures.length > 1) return new AggregateError(failures, "Operation execution and cleanup failed.");
+  return Cause.squash(cause);
+}
+
+export function operationExitValue<A>(exit: Exit.Exit<A, OperationEffectFailure>): A {
+  if (Exit.isSuccess(exit)) return exit.value;
+  throw operationCauseValue(exit.cause);
+}
+
+/** Preserve native finally precedence without losing the earlier typed Cause. */
+export function operationFinally<A, R, R2>(
+  use: Effect.Effect<A, OperationEffectFailure, R>,
+  release: Effect.Effect<void, OperationEffectFailure, R2>,
+): Effect.Effect<A, OperationEffectFailure, R | R2> {
+  return Effect.uninterruptibleMask(restore => Effect.gen(function*() {
+    const result = yield* Effect.exit(restore(use));
+    const cleanup = yield* Effect.exit(release);
+    if (Exit.isSuccess(cleanup)) return yield* result;
+    const selected = Cause.failureOption(cleanup.cause);
+    const failure: OperationEffectFailure = selected._tag === "Some"
+      && Array.from(Cause.failures(cleanup.cause)).length === 1
+      && Array.from(Cause.defects(cleanup.cause)).length === 0
+      ? Exit.isSuccess(result) ? selected.value : {
+          ...selected.value,
+          priorCause: selected.value.priorCause === undefined
+            ? result.cause
+            : Cause.sequential(result.cause, selected.value.priorCause),
+        }
+      : {
+          _tag: "OperationBoundaryFailure",
+          phase: "cleanup",
+          cause: operationCauseValue(cleanup.cause),
+          ...(Exit.isFailure(result) ? { priorCause: result.cause } : {}),
+        };
+    return yield* Effect.fail(failure);
+  }));
+}
+
+/** Acquisition cannot escape before its native release has an owner. */
+export function operationResource<A, B, R, R2, R3>(
+  acquire: Effect.Effect<A, OperationEffectFailure, R>,
+  use: (value: A) => Effect.Effect<B, OperationEffectFailure, R2>,
+  release: (value: A) => Effect.Effect<void, OperationEffectFailure, R3>,
+): Effect.Effect<B, OperationEffectFailure, R | R2 | R3> {
+  return Effect.uninterruptibleMask(restore => Effect.gen(function*() {
+    const value = yield* acquire;
+    return yield* operationFinally(Effect.suspend(() => restore(use(value))), Effect.suspend(() => release(value)));
+  }));
+}
+
+/** Compatibility root for a standalone operation; schedulers compose directly. */
+export async function runStandaloneOperation<A>(
+  program: Effect.Effect<A, OperationEffectFailure>,
+): Promise<A> {
+  return operationExitValue(await Effect.runPromiseExit(program));
+}

package/apps/desktop/application/operation.ts

@@ -0,0 +1,224 @@
+import type { Effect } from "effect";
+import type { OperationEffectFailure } from "./operation-effects";
+import type { z } from "zod";
+
+import type { ApplicationContext } from "./context";
+
+export const SLOPCAMERA_APPLICATION_TOOL_VERSION = "slopcamera-3.2.4" as const;
+
+export const OPERATION_KINDS = [
+  "scene.inspect",
+  "scene.patch",
+  "scene.evaluate",
+  "scene.render",
+  "slopcamera.studio.run",
+  "spatial.project.snapshot",
+  "spatial.project.migrate",
+  "spatial.project.patch",
+  "spatial.project.restore",
+  "spatial.project.add-shot",
+  "spatial.project.add-candidate",
+  "spatial.project.select-candidate",
+  "spatial.project.reconcile",
+  "project.snapshot",
+  "analysis.project-inactivity",
+  "analysis.faces",
+  "analysis.music",
+  "analysis.scenes",
+  "analysis.project-auto-zooms",
+  "derive.edit-batch",
+  "project.commit-edits",
+  "derive.follow-faces",
+  "edit.create-revision",
+  "edit.create-candidate-revision",
+  "edit.bind-candidate-revision",
+  "edit.freeze-revision",
+  "iteration.create-candidate",
+  "iteration.create-matrix",
+  "iteration.select",
+  "project.promote-selection",
+  "render.bind-candidate-output",
+  "render.project-plan",
+  "render.project",
+  "render.materialize-selection",
+  "media.ingest",
+  "media.overlay",
+  "media.html-overlay",
+  "media.audio-effects",
+  "media.color-grade",
+  "gateway.image",
+  "gateway.video",
+  "gateway.speech",
+  "gateway.transcription",
+  "recording.start",
+  "recording.pause",
+  "recording.resume",
+  "recording.stop",
+  "slopcamera.diagram.check",
+  "slopcamera.diagram.render",
+  "slopcamera.image.vectorize",
+  "slopcamera.image.generate",
+] as const;
+
+export type OperationKind = typeof OPERATION_KINDS[number];
+
+export const RESOURCE_KINDS = [
+  "cpu",
+  "local-io",
+  "ffmpeg",
+  "vision",
+  "whisper",
+  "network",
+  "paid-call",
+  "project-render",
+  "project-publication",
+  "output-publication",
+  "capture-device",
+  "browser",
+] as const;
+
+export type OperationResourceKind = typeof RESOURCE_KINDS[number];
+
+export type OperationEffectClass =
+  | "pure"
+  | "local-read"
+  | "local-derived-write"
+  | "project-mutation"
+  | "paid-cloud"
+  | "live-control";
+
+export type OperationResumeClass =
+  | "deterministic"
+  | "verified-receipt"
+  | "recoverable-transaction"
+  | "ambiguous-after-dispatch"
+  | "non-resumable-live";
+
+export interface OperationResourceClaim {
+  readonly amount: number;
+  readonly resource: OperationResourceKind;
+}
+
+export interface OperationPolicy {
+  readonly cache: "none" | "exact-run" | "content-addressed";
+  readonly cancellable: boolean;
+  readonly effect: OperationEffectClass;
+  readonly maxDurationMs: number;
+  readonly maxFanOut: number;
+  readonly maxInputBytes: number;
+  readonly maxOutputBytes: number;
+  readonly preparation: readonly (
+    | "project-state"
+    | "recording-metadata"
+    | "screen-capture"
+    | "camera"
+    | "microphone"
+    | "system-audio"
+    | "typed-text"
+    | "window-metadata"
+    | "local-media"
+    | "provider-options"
+  )[];
+  readonly resources: readonly OperationResourceClaim[];
+  readonly resume: OperationResumeClass;
+}
+
+export interface BoundedOperationSummary {
+  readonly fields: Readonly<Record<string, boolean | null | number | string>>;
+  readonly kind: OperationKind;
+}
+
+export interface OperationExecutionContext {
+  readonly abortSignal: AbortSignal;
+  readonly application: ApplicationContext;
+  readonly expectedProjectGeneration?: string;
+  readonly runFence?: {
+    readonly generation: number;
+    readonly owner: string;
+    readonly token: string;
+  };
+  /**
+   * Ephemeral runner-owned state. It is never accepted from graph input or
+   * persisted as operation authority.
+   */
+  readonly workflow?: {
+    /**
+     * Revalidates the physical run fence and durable cancellation marker at
+     * the last safe point before an operation publishes external bytes.
+     */
+    beforePublication(): Promise<void>;
+    readonly nodeKey: string;
+    readonly nodePlanSha256: string;
+    readonly runId: string;
+    /** Private, deterministic, exact-run/node-plan staging directory. */
+    readonly workspaceDirectory: string;
+  };
+}
+
+interface LifecycleBase<Input, Output> {
+  execute(context: OperationExecutionContext, input: Input): Promise<Output>;
+  /** Local native composition only; never part of discovery or graph identity. */
+  executeEffect?(context: OperationExecutionContext, input: Input): Effect.Effect<Output, OperationEffectFailure>;
+}
+
+export interface PureLifecycle<Input, Output> extends LifecycleBase<Input, Output> {
+  readonly kind: "pure";
+}
+
+export interface LocalArtifactLifecycle<Input, Output> extends LifecycleBase<Input, Output> {
+  readonly kind: "local-artifact";
+}
+
+export interface ProjectTransactionLifecycle<Input, Output> extends LifecycleBase<Input, Output> {
+  readonly kind: "project-transaction";
+}
+
+export interface PaidDispatchLifecycle<Input, Output> extends LifecycleBase<Input, Output> {
+  readonly kind: "paid-dispatch";
+}
+
+export interface LiveControlLifecycle<Input, Output> extends LifecycleBase<Input, Output> {
+  readonly kind: "live-control";
+}
+
+export type OperationLifecycle<Input, Output> =
+  | PureLifecycle<Input, Output>
+  | LocalArtifactLifecycle<Input, Output>
+  | ProjectTransactionLifecycle<Input, Output>
+  | PaidDispatchLifecycle<Input, Output>
+  | LiveControlLifecycle<Input, Output>;
+
+export interface OperationDefinition<
+  Kind extends OperationKind = OperationKind,
+  Input = unknown,
+  Output = unknown,
+> {
+  readonly inputSchema: z.ZodType<Input>;
+  readonly inputSchemaId: string;
+  readonly kind: Kind;
+  readonly lifecycle: OperationLifecycle<Input, Output>;
+  readonly outputSchema: z.ZodType<Output>;
+  readonly outputSchemaId: string;
+  readonly policy: OperationPolicy;
+  /**
+   * Selects the operation-owned authoritative receipt after output parsing.
+   * The scheduler records this reference; it does not replace the receipt.
+   */
+  readonly receiptReference?: (output: Output) => string | undefined;
+  summarize(output: Output): BoundedOperationSummary;
+  readonly version: number;
+}
+
+export interface OperationRequest {
+  readonly input: unknown;
+  readonly kind: OperationKind;
+  readonly version: number;
+}
+
+export interface OperationResult {
+  readonly kind: OperationKind;
+  readonly output: unknown;
+  readonly receiptReference?: string;
+  readonly summary: BoundedOperationSummary;
+  readonly version: number;
+}