@hraness/slopcamera 3.2.4

package/apps/desktop/application/operations/analysis/scenes.ts

@@ -0,0 +1,272 @@
+import { z } from "zod";
+
+import {
+  AnalysisSubjectSchema,
+  MicrosecondsSchema,
+  SceneIdSchema,
+  SceneSampleIdSchema,
+  Sha256Schema,
+  SourceIntervalSchema,
+  VideoProjectIdSchema,
+} from "../../../contracts";
+import {
+  MAXIMUM_SCENE_SAMPLES,
+  planProjectScenes,
+  type PlanProjectScenesOptions,
+  type PlanProjectScenesResult,
+} from "../../../cli/scene-analysis-service";
+import {
+  SCENE_SAMPLING_VERSION,
+  canonicalJsonSha256,
+} from "../../../core";
+import type { OperationDefinition } from "../../operation";
+import { openLeasedProjectSnapshot } from "../../project-publication-lease";
+import {
+  ProjectReferenceSchema,
+  requireCapabilities,
+  throwIfAborted,
+} from "../shared";
+import {
+  AnalysisCapabilityBindingsSchema,
+  AnalysisProjectBindingSchema,
+  analysisCapabilityCommand,
+  analysisCapabilityRunner,
+  assertAnalysisCapabilityBindings,
+  assertAnalysisProjectBinding,
+} from "./shared";
+
+const SceneSampleReasonSchema = z.enum([
+  "boundary",
+  "middle",
+  "event",
+  "maximum-gap",
+  "motion",
+]);
+
+export const SceneAnalysisOperationConfigSchema = z.strictObject({
+  maximumSceneDurationUs: MicrosecondsSchema.min(1_000_000),
+  sceneThreshold: z.number().finite().positive().max(1),
+});
+
+export const DEFAULT_SCENE_ANALYSIS_CONFIG =
+  SceneAnalysisOperationConfigSchema.parse({
+    maximumSceneDurationUs: 20_000_000,
+    sceneThreshold: 0.35,
+  });
+
+export const PlannedSceneEvidenceSchema = z.strictObject({
+  boundaryConfidence: z.number().finite().min(0).max(1),
+  range: SourceIntervalSchema,
+  sampleIds: z.array(SceneSampleIdSchema).min(1).max(12),
+  sceneId: SceneIdSchema,
+});
+
+export const PlannedSceneSampleEvidenceSchema = z.strictObject({
+  reasons: z.array(SceneSampleReasonSchema).min(1).max(5),
+  requestedAssetTimeUs: MicrosecondsSchema,
+  sampleId: SceneSampleIdSchema,
+  sceneId: SceneIdSchema,
+});
+
+export const SceneAnalysisOperationInputSchema = z.strictObject({
+  capabilityBindings: AnalysisCapabilityBindingsSchema.optional(),
+  config: SceneAnalysisOperationConfigSchema.optional(),
+  project: ProjectReferenceSchema,
+  projectBinding: AnalysisProjectBindingSchema.optional(),
+  source: z.string().min(1).max(256),
+});
+
+export const SceneAnalysisOperationOutputSchema = z.strictObject({
+  planDigest: Sha256Schema,
+  projectId: VideoProjectIdSchema,
+  samples: z.array(PlannedSceneSampleEvidenceSchema)
+    .max(MAXIMUM_SCENE_SAMPLES),
+  samplingVersion: z.literal(SCENE_SAMPLING_VERSION),
+  scenes: z.array(PlannedSceneEvidenceSchema)
+    .max(MAXIMUM_SCENE_SAMPLES),
+  source: z.string().min(1).max(256),
+  subject: AnalysisSubjectSchema,
+}).superRefine((output, context) => {
+  if (
+    output.planDigest !== canonicalJsonSha256({
+      samples: output.samples,
+      samplingVersion: output.samplingVersion,
+      scenes: output.scenes,
+    })
+  ) {
+    context.addIssue({
+      code: "custom",
+      message: "Scene evidence does not match its plan digest.",
+      path: ["planDigest"],
+    });
+  }
+
+  const scenesById = new Map(
+    output.scenes.map(scene => [scene.sceneId, scene]),
+  );
+  const samplesById = new Map(
+    output.samples.map(sample => [sample.sampleId, sample]),
+  );
+  if (scenesById.size !== output.scenes.length) {
+    context.addIssue({
+      code: "custom",
+      message: "Planned scene IDs must be unique.",
+      path: ["scenes"],
+    });
+  }
+  if (samplesById.size !== output.samples.length) {
+    context.addIssue({
+      code: "custom",
+      message: "Planned scene sample IDs must be unique.",
+      path: ["samples"],
+    });
+  }
+  for (const scene of output.scenes) {
+    for (const sampleId of scene.sampleIds) {
+      const sample = samplesById.get(sampleId);
+      if (sample === undefined || sample.sceneId !== scene.sceneId) {
+        context.addIssue({
+          code: "custom",
+          message:
+            `Scene ${scene.sceneId} references a missing or differently owned sample.`,
+          path: ["scenes"],
+        });
+      }
+    }
+  }
+  for (const sample of output.samples) {
+    const scene = scenesById.get(sample.sceneId);
+    if (
+      scene === undefined
+      || !scene.sampleIds.includes(sample.sampleId)
+      || sample.requestedAssetTimeUs < scene.range.startUs
+      || sample.requestedAssetTimeUs >= scene.range.endUs
+    ) {
+      context.addIssue({
+        code: "custom",
+        message:
+          `Sample ${sample.sampleId} is outside its owning scene evidence.`,
+        path: ["samples"],
+      });
+    }
+  }
+});
+
+export type SceneAnalysisOperationInput = z.infer<
+  typeof SceneAnalysisOperationInputSchema
+>;
+export type SceneAnalysisOperationOutput = z.infer<
+  typeof SceneAnalysisOperationOutputSchema
+>;
+
+type ScenePlanningExecutor = (
+  options: PlanProjectScenesOptions,
+) => Promise<PlanProjectScenesResult>;
+
+export interface SceneAnalysisOperationDependencies {
+  readonly plan?: ScenePlanningExecutor;
+}
+
+export function createSceneAnalysisOperationDefinition(
+  dependencies: SceneAnalysisOperationDependencies = {},
+): OperationDefinition<
+  "analysis.scenes",
+  SceneAnalysisOperationInput,
+  SceneAnalysisOperationOutput
+> {
+  const planScenes = dependencies.plan ?? planProjectScenes;
+  return {
+    inputSchema: SceneAnalysisOperationInputSchema,
+    inputSchemaId: "slopcamera.operation.analysis.scenes.input/v1",
+    kind: "analysis.scenes",
+    lifecycle: {
+      kind: "local-artifact",
+      execute: async (context, input) => {
+        throwIfAborted(context.abortSignal);
+        const snapshot = await openLeasedProjectSnapshot(
+          context.application,
+          input.project,
+        );
+        assertAnalysisProjectBinding(context, input.projectBinding, snapshot);
+        const capabilities = await requireCapabilities(
+          context.application,
+          ["ffmpeg"],
+        );
+        await assertAnalysisCapabilityBindings(
+          context,
+          input.capabilityBindings,
+          context.application,
+          ["ffmpeg"],
+        );
+        const config = input.config ?? DEFAULT_SCENE_ANALYSIS_CONFIG;
+        const result = await planScenes({
+          ffmpeg: analysisCapabilityCommand(
+            input.capabilityBindings,
+            capabilities,
+            "ffmpeg",
+          ),
+          maximumSceneDurationUs: config.maximumSceneDurationUs,
+          project: snapshot.project,
+          repositoryRoot: context.application.paths.repositoryRoot,
+          runner: analysisCapabilityRunner(
+            context.application,
+            input.capabilityBindings,
+          ),
+          sceneThreshold: config.sceneThreshold,
+          source: input.source,
+        });
+        throwIfAborted(context.abortSignal);
+        const finalSnapshot = await openLeasedProjectSnapshot(
+          context.application,
+          snapshot.project.projectId,
+        );
+        assertAnalysisProjectBinding(
+          { workflow: {} },
+          snapshot.editBasis,
+          finalSnapshot,
+        );
+        return SceneAnalysisOperationOutputSchema.parse({
+          planDigest: result.plan.planDigest,
+          projectId: snapshot.project.projectId,
+          samples: result.plan.samples,
+          samplingVersion: result.plan.samplingVersion,
+          scenes: result.plan.scenes,
+          source: input.source,
+          subject: result.subject,
+        });
+      },
+    },
+    outputSchema: SceneAnalysisOperationOutputSchema,
+    outputSchemaId: "slopcamera.operation.analysis.scenes.output/v1",
+    policy: {
+      cache: "exact-run",
+      cancellable: true,
+      effect: "local-read",
+      maxDurationMs: 2 * 60 * 60_000,
+      maxFanOut: 1,
+      maxInputBytes: 16_384,
+      maxOutputBytes: 16 * 1024 * 1024,
+      preparation: ["project-state", "local-media"],
+      resources: [
+        { amount: 1, resource: "cpu" },
+        { amount: 1, resource: "ffmpeg" },
+        { amount: 1, resource: "local-io" },
+      ],
+      resume: "deterministic",
+    },
+    summarize: output => ({
+      fields: {
+        planDigest: output.planDigest,
+        projectId: output.projectId,
+        samples: output.samples.length,
+        scenes: output.scenes.length,
+        source: output.source,
+      },
+      kind: "analysis.scenes",
+    }),
+    version: 1,
+  };
+}
+
+export const sceneAnalysisOperationDefinition =
+  createSceneAnalysisOperationDefinition();

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

@@ -0,0 +1,202 @@
+import { z } from "zod";
+
+import {
+  AnalysisIdSchema,
+  type ProjectAnalysisReferenceSchema,
+  type VideoProjectV1,
+} from "../../../contracts";
+import { canonicalJson } from "../../../core/canonical-json";
+import {
+  ExactCapabilityApplicationRunner,
+  ExactCapabilityBindingSchema,
+  assertExactCapabilityBindings,
+  bindExactCapabilities,
+  exactCapabilityByName,
+  type ExactCapabilityBinding,
+} from "../../capability-binding";
+import type {
+  ApplicationCapability,
+  ApplicationContext,
+  ApplicationProcessRunner,
+} from "../../context";
+import { ApplicationError } from "../../errors";
+import type { OperationKind } from "../../operation";
+import { openLeasedProjectSnapshot } from "../../project-publication-lease";
+import {
+  assertProjectEditBasis,
+  ProjectEditBasisSchema,
+  type OpenProjectSnapshot,
+} from "../../project-store";
+import {
+  requiredCapabilityCommand,
+} from "../shared";
+
+const ANALYSIS_CAPABILITY_NAMES = [
+  "face-analyzer",
+  "ffmpeg",
+  "ffprobe",
+] as const;
+type AnalysisCapabilityName = typeof ANALYSIS_CAPABILITY_NAMES[number];
+
+export const AnalysisCapabilityBindingSchema = ExactCapabilityBindingSchema
+  .extend({
+    name: z.enum(ANALYSIS_CAPABILITY_NAMES),
+  })
+  .strict();
+
+export const AnalysisCapabilityBindingsSchema = z.array(
+  AnalysisCapabilityBindingSchema,
+).max(ANALYSIS_CAPABILITY_NAMES.length).superRefine((bindings, context) => {
+  for (let index = 0; index < bindings.length; index += 1) {
+    const previous = bindings[index - 1];
+    if (
+      previous !== undefined
+      && previous.name.localeCompare(bindings[index]!.name) >= 0
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "Analysis capability bindings must have unique sorted names.",
+        path: [index, "name"],
+      });
+    }
+  }
+});
+
+export const AnalysisProjectBindingSchema = ProjectEditBasisSchema;
+
+const ANALYSIS_CAPABILITIES = {
+  "analysis.faces": ["face-analyzer", "ffprobe"],
+  "analysis.music": ["ffmpeg"],
+  "analysis.project-inactivity": ["ffmpeg", "ffprobe"],
+  "analysis.scenes": ["ffmpeg"],
+} as const satisfies Partial<Record<OperationKind, readonly AnalysisCapabilityName[]>>;
+
+export async function bindAnalysisCapabilityInput(
+  application: ApplicationContext,
+  kind: Extract<
+    OperationKind,
+    | "analysis.faces"
+    | "analysis.music"
+    | "analysis.project-inactivity"
+    | "analysis.scenes"
+  >,
+  input: unknown,
+): Promise<unknown> {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new ApplicationError("invalid-data", "Analysis operation input must be an object.");
+  }
+  const names = ANALYSIS_CAPABILITIES[kind];
+  const project = "project" in input ? input.project : undefined;
+  if (typeof project !== "string") {
+    throw new ApplicationError(
+      "invalid-data",
+      "Analysis operation input must contain a project reference.",
+    );
+  }
+  const [capabilityBindings, snapshot] = await Promise.all([
+    bindExactCapabilities(application, names),
+    openLeasedProjectSnapshot(application, project),
+  ]);
+  return {
+    ...input,
+    capabilityBindings: AnalysisCapabilityBindingsSchema.parse(
+      capabilityBindings,
+    ),
+    projectBinding: snapshot.editBasis,
+  };
+}
+
+export async function assertAnalysisCapabilityBindings(
+  context: { readonly workflow?: unknown },
+  expected: z.infer<typeof AnalysisCapabilityBindingsSchema> | undefined,
+  application: ApplicationContext,
+  names: readonly AnalysisCapabilityName[],
+): Promise<void> {
+  if (context.workflow !== undefined && expected === undefined) {
+    throw new ApplicationError(
+      "incompatible",
+      "Workflow analysis requires exact capability bindings.",
+    );
+  }
+  if (expected !== undefined) {
+    await assertExactCapabilityBindings(application, expected, names);
+  }
+}
+
+export function analysisCapabilityCommand(
+  expected: readonly ExactCapabilityBinding[] | undefined,
+  capabilities: ReadonlyMap<
+    string,
+    ApplicationCapability & { readonly command: string }
+  >,
+  name: AnalysisCapabilityName,
+): string {
+  return expected === undefined
+    ? requiredCapabilityCommand(capabilities, name)
+    : exactCapabilityByName(expected, name).executablePath;
+}
+
+export function analysisCapabilityRunner(
+  application: Pick<ApplicationContext, "paths" | "runner">,
+  expected: readonly ExactCapabilityBinding[] | undefined,
+): ApplicationProcessRunner {
+  return expected === undefined
+    ? application.runner
+    : new ExactCapabilityApplicationRunner(
+      application.runner,
+      expected,
+      application.paths.privateRoot,
+    );
+}
+
+export function assertAnalysisProjectBinding(
+  context: { readonly workflow?: unknown },
+  expected: z.infer<typeof AnalysisProjectBindingSchema> | undefined,
+  snapshot: OpenProjectSnapshot,
+): void {
+  if (context.workflow !== undefined && expected === undefined) {
+    throw new ApplicationError(
+      "incompatible",
+      "Workflow analysis requires an exact project edit basis.",
+    );
+  }
+  if (expected !== undefined) {
+    assertProjectEditBasis(expected, snapshot);
+  }
+}
+
+export interface AnalysisIdDependencies {
+  readonly nextAnalysisId: () => string;
+}
+
+export interface VersionedAnalysisDependencies extends AnalysisIdDependencies {
+  readonly toolVersion: string;
+}
+
+export function resolveAnalysisId(
+  requested: string | undefined,
+  dependencies: AnalysisIdDependencies,
+) {
+  return AnalysisIdSchema.parse(requested ?? dependencies.nextAnalysisId());
+}
+
+export function resolveToolVersion(
+  dependencies: VersionedAnalysisDependencies,
+): string {
+  return z.string().min(1).max(128).parse(dependencies.toolVersion);
+}
+
+export function assertPublishedAnalysisReference(
+  project: VideoProjectV1,
+  reference: z.infer<typeof ProjectAnalysisReferenceSchema>,
+): void {
+  const installed = project.analyses.find(
+    candidate => candidate.analysisId === reference.analysisId,
+  );
+  if (installed === undefined || canonicalJson(installed) !== canonicalJson(reference)) {
+    throw new ApplicationError(
+      "internal",
+      `Analysis publication did not install its authoritative ${reference.analysisId} reference.`,
+    );
+  }
+}