@hraness/slopcamera 3.2.4

package/apps/desktop/application/operations/spatial-scene.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { createBoundedJsonValueSnapshot } from "../../../../src/code/json-snapshot";
+import {
+  EvaluatedSpatialSceneSchema, SpatialAssetManifestSchema, SpatialCameraSchema,
+  SpatialDigestSchema, SpatialEntityIdSchema, SpatialGeneratorSchema,
+  SpatialOriginSchema, SpatialScenePatchV1Schema, SpatialPlacementSchema, SpatialPoseSchema,
+  SpatialSceneV1Schema, SpatialTimeUsSchema,
+} from "../../../../src/spatial-scene/contracts";
+import { applySpatialScenePatch, evaluateSpatialScene, inspectSpatialScene } from "../../../../src/spatial-scene/index";
+import type { OperationDefinition, OperationPolicy } from "../operation";
+import { throwIfAborted } from "./shared";
+
+const boundedVector = z.tuple([z.number().finite(), z.number().finite(), z.number().finite()]);
+export const SpatialSceneInspectionOutputSchema = z.strictObject({
+  sceneId: z.string(), sceneSha256: SpatialDigestSchema, durationUs: SpatialTimeUsSchema,
+  entities: z.array(z.strictObject({
+    entityId: SpatialEntityIdSchema, name: z.string(),
+    kind: z.enum(["group", "mesh", "image", "diagram", "video", "text", "light", "splat"]),
+    origin: SpatialOriginSchema, parentId: SpatialEntityIdSchema.nullable(), placement: SpatialPlacementSchema,
+    editableControls: z.array(z.enum(["color", "opacity", "transform"])),
+    animatedProperties: z.array(z.string()), assetIds: z.array(z.string()),
+    bounds: z.discriminatedUnion("status", [
+      z.strictObject({ status: z.literal("authored-enclosure"), coordinateDomain: SpatialPlacementSchema,
+        atTimeUs: z.literal(0), bounds: z.strictObject({ min: boundedVector, max: boundedVector }) }),
+      z.strictObject({ status: z.literal("unknown"), reason: z.enum(["requires-asset-decoding", "requires-text-layout", "no-surface"]) }),
+    ]),
+  })).max(4096),
+  cameras: z.array(SpatialCameraSchema).max(64),
+  assets: z.array(z.strictObject({ assetId: z.string(), manifestSha256: SpatialDigestSchema, manifest: SpatialAssetManifestSchema })).max(128),
+  generators: z.array(SpatialGeneratorSchema),
+});
+const capture = (value: unknown) => createBoundedJsonValueSnapshot(value, 4 * 1024 * 1024, "scene operation", { maximumDepth: 36, maximumValues: 400_000 }).value;
+export const SpatialInspectInputSchema = z.preprocess(capture, z.strictObject({ scene: SpatialSceneV1Schema }));
+export const SpatialPatchInputSchema = z.preprocess(capture, z.strictObject({ scene: SpatialSceneV1Schema, patch: SpatialScenePatchV1Schema }));
+export const SpatialPatchOutputSchema = z.strictObject({
+  scene: SpatialSceneV1Schema, sceneSha256: SpatialDigestSchema,
+  diff: z.array(z.strictObject({
+    kind: z.enum(["added", "removed", "changed"]),
+    collection: z.enum(["entities", "cameras", "animations", "generators", "overrides", "assets"]),
+    id: z.string(), properties: z.array(z.string()),
+  })),
+});
+export const SpatialEvaluateInputSchema = z.preprocess(capture, z.strictObject({
+  scene: SpatialSceneV1Schema, timeUs: SpatialTimeUsSchema, cameraId: z.string(),
+  cameraPoseOverride: SpatialPoseSchema.optional(),
+}));
+export type SpatialInspectInput = z.infer<typeof SpatialInspectInputSchema>;
+export type SpatialInspectOutput = z.infer<typeof SpatialSceneInspectionOutputSchema>;
+export type SpatialPatchInput = z.infer<typeof SpatialPatchInputSchema>;
+export type SpatialPatchOutput = z.infer<typeof SpatialPatchOutputSchema>;
+export type SpatialEvaluateInput = z.infer<typeof SpatialEvaluateInputSchema>;
+export type SpatialEvaluateOutput = z.infer<typeof EvaluatedSpatialSceneSchema>;
+
+const purePolicy = Object.freeze({
+  cache: "content-addressed", cancellable: true, effect: "pure", maxDurationMs: 10_000,
+  maxFanOut: 0, maxInputBytes: 4 * 1024 * 1024, maxOutputBytes: 8 * 1024 * 1024,
+  preparation: [], resources: [{ amount: 1, resource: "cpu" }], resume: "deterministic",
+} as const) satisfies OperationPolicy;
+
+export const spatialInspectOperationDefinition = {
+  kind: "scene.inspect", version: 1,
+  inputSchema: SpatialInspectInputSchema, inputSchemaId: "slopcamera.operation.scene.inspect.input/v1",
+  outputSchema: SpatialSceneInspectionOutputSchema, outputSchemaId: "slopcamera.operation.scene.inspect.output/v1",
+  policy: purePolicy,
+  lifecycle: { kind: "pure", execute: (context, input) => {
+    throwIfAborted(context.abortSignal);
+    return Promise.resolve(SpatialSceneInspectionOutputSchema.parse(inspectSpatialScene(input.scene)));
+  } },
+  summarize: output => ({ kind: "scene.inspect", fields: { sceneSha256: output.sceneSha256, entities: output.entities.length, cameras: output.cameras.length } }),
+} satisfies OperationDefinition<"scene.inspect", SpatialInspectInput, SpatialInspectOutput>;
+
+export const spatialPatchOperationDefinition = {
+  kind: "scene.patch", version: 1,
+  inputSchema: SpatialPatchInputSchema, inputSchemaId: "slopcamera.operation.scene.patch.input/v1",
+  outputSchema: SpatialPatchOutputSchema, outputSchemaId: "slopcamera.operation.scene.patch.output/v1",
+  policy: purePolicy,
+  lifecycle: { kind: "pure", execute: (context, input) => {
+    throwIfAborted(context.abortSignal);
+    return Promise.resolve(SpatialPatchOutputSchema.parse(applySpatialScenePatch(input.scene, input.patch)));
+  } },
+  summarize: output => ({ kind: "scene.patch", fields: { sceneSha256: output.sceneSha256, changes: output.diff.length } }),
+} satisfies OperationDefinition<"scene.patch", SpatialPatchInput, SpatialPatchOutput>;
+
+export const spatialEvaluateOperationDefinition = {
+  kind: "scene.evaluate", version: 1,
+  inputSchema: SpatialEvaluateInputSchema, inputSchemaId: "slopcamera.operation.scene.evaluate.input/v1",
+  outputSchema: EvaluatedSpatialSceneSchema, outputSchemaId: "slopcamera.operation.scene.evaluate.output/v1",
+  policy: purePolicy,
+  lifecycle: { kind: "pure", execute: (context, input) => {
+    throwIfAborted(context.abortSignal);
+    return Promise.resolve(EvaluatedSpatialSceneSchema.parse(evaluateSpatialScene(input.scene, {
+      timeUs: input.timeUs, cameraId: input.cameraId,
+      ...(input.cameraPoseOverride === undefined ? {} : { cameraPoseOverride: input.cameraPoseOverride }),
+    })));
+  } },
+  summarize: output => ({ kind: "scene.evaluate", fields: { sceneSha256: output.sceneSha256, viewSha256: output.viewSha256, timeUs: output.timeUs } }),
+} satisfies OperationDefinition<"scene.evaluate", SpatialEvaluateInput, SpatialEvaluateOutput>;

package/apps/desktop/application/operations/studio.ts

@@ -0,0 +1,143 @@
+import { posix } from "node:path";
+
+import { deepFreezeJson } from "../../../../src/code/json-snapshot";
+import { validateStudioReceipt } from "../../../../src/studio";
+import { canonicalJson } from "../../core/canonical-json";
+import type { ApplicationContext } from "../context";
+import { ApplicationError } from "../errors";
+import type { OperationDefinition, OperationExecutionContext } from "../operation";
+import { writeOperationCompletionCheckpoint } from "../operation-completion-checkpoint";
+import {
+  BoundStudioRunInputSchema, StudioRunInputSchema, StudioRunOutputSchema,
+  type BoundStudioRunInput, type StudioHostControl, type StudioReconciliation, type StudioRunInput, type StudioRunOutput,
+} from "../studio-port";
+import { throwIfAborted } from "./shared";
+
+const definitionIdentity = {
+  kind: "slopcamera.studio.run", version: 1,
+  inputSchemaId: "slopcamera.operation.studio.run.input/v1", outputSchemaId: "slopcamera.operation.studio.run.output/v1",
+} as const;
+
+function requirePort(application: ApplicationContext) {
+  if (application.studioPort === undefined) throw new ApplicationError("unavailable", "This host has no trusted studio adapter.");
+  return application.studioPort;
+}
+
+function boundInput(value: unknown): BoundStudioRunInput {
+  const input = BoundStudioRunInputSchema.parse(value);
+  if (canonicalJson(input.job) !== canonicalJson(input.plan.job)) throw new ApplicationError("conflict", "Studio request job disagrees with its exact plan.");
+  if (input.plan.runtime === undefined) throw new ApplicationError("unavailable", "Studio execution requires an observed runtime binding.");
+  return deepFreezeJson(input);
+}
+
+export function studioAuthorizationRequest(value: unknown) {
+  const input = boundInput(value);
+  return Object.freeze({ planSha256: input.plan.planSha256, bundleSha256: input.plan.bundleSha256, jobId: input.job.jobId });
+}
+
+/** Manifest closure and fixed runtime probing are inert with respect to authored source. */
+export async function bindStudioRunInput(application: ApplicationContext, value: unknown, signal = new AbortController().signal, beforePublication?: () => Promise<void>): Promise<BoundStudioRunInput> {
+  throwIfAborted(signal);
+  const input = deepFreezeJson(StudioRunInputSchema.parse(value));
+  const guard = async () => { throwIfAborted(signal); await application.hostResourceLease?.assertOwned(); await beforePublication?.(); throwIfAborted(signal); };
+  await guard();
+  const bound = boundInput(await requirePort(application).bind(input, signal, { inheritedFileDescriptors: application.hostResourceLease?.inheritedFileDescriptors ?? [], beforePublication: guard }));
+  throwIfAborted(signal);
+  if (canonicalJson(input.job) !== canonicalJson(bound.job) || input.bundle.path !== bound.bundle.path
+    || ("sha256" in input.bundle && canonicalJson(input.bundle) !== canonicalJson(bound.bundle))
+    || (input.plan !== undefined && canonicalJson(input.plan) !== canonicalJson(bound.plan))) {
+    throw new ApplicationError("conflict", "Studio source, job, or runtime changed after planning.");
+  }
+  return bound;
+}
+
+/** The host verifies physical bytes; this boundary verifies their complete typed projection. */
+export function validateStudioRunOutput(inputValue: unknown, outputValue: unknown): StudioRunOutput {
+  const input = boundInput(inputValue);
+  const output = StudioRunOutputSchema.parse(outputValue);
+  const receipt = validateStudioReceipt({ plan: input.plan, receipt: output.document });
+  const expected = new Map(receipt.outputs.map(item => [posix.join(posix.dirname(output.receipt.path), "outputs", item.path), item]));
+  if (expected.size !== output.outputs.length) throw new ApplicationError("invalid-data", "Studio output references must cover every retained receipt artifact exactly once.");
+  for (const item of output.outputs) {
+    const artifact = expected.get(item.artifact.path);
+    if (artifact === undefined || artifact.outputId !== item.outputId || artifact.sha256 !== item.artifact.sha256
+      || artifact.bytes !== item.artifact.bytes || artifact.role !== item.role || artifact.format !== item.format) {
+      throw new ApplicationError("invalid-data", "Studio output reference disagrees with its retained receipt artifact.");
+    }
+    expected.delete(item.artifact.path);
+  }
+  return deepFreezeJson(output);
+}
+
+function controlFor(context: OperationExecutionContext): StudioHostControl {
+  const workflow = context.workflow;
+  if (workflow === undefined) throw new ApplicationError("unavailable", "Studio workflow execution requires an exact durable node workspace.");
+  return {
+    signal: context.abortSignal,
+    workspaceDirectory: workflow.workspaceDirectory,
+    identity: { runId: workflow.runId, nodeKey: workflow.nodeKey, nodePlanSha256: workflow.nodePlanSha256 },
+    inheritedFileDescriptors: context.application.hostResourceLease?.inheritedFileDescriptors ?? [],
+    beforePublication: async () => {
+      throwIfAborted(context.abortSignal);
+      await context.application.hostResourceLease?.assertOwned();
+      await workflow.beforePublication();
+      throwIfAborted(context.abortSignal);
+    },
+  };
+}
+
+function assertSucceeded(output: StudioRunOutput): void {
+  if (output.document.state === "succeeded") return;
+  throw new ApplicationError(output.document.state === "unknown-custody" ? "ambiguous" : "subprocess",
+    output.document.state === "unknown-custody" ? "Studio native process custody is unresolved; inspect the retained receipt before further execution." : "Studio job failed; inspect its retained receipt.",
+    { receipt: output.receipt, state: output.document.state });
+}
+
+export async function executeStudioRun(context: OperationExecutionContext, value: StudioRunInput): Promise<StudioRunOutput> {
+  const control = controlFor(context);
+  const original = boundInput(value);
+  const input = await bindStudioRunInput(context.application, original, context.abortSignal, control.beforePublication);
+  if (input.plan.readiness !== "authorization-required") throw new ApplicationError("unavailable", "Studio runtime has unavailable or unverified required capabilities.");
+  const authorization = context.application.studioAuthorization;
+  if (authorization === undefined || !await authorization.authorize(studioAuthorizationRequest(input))) {
+    throw new ApplicationError("authorization-required", "This exact studio plan requires explicit trusted-current-user code authorization from the host.");
+  }
+  await control.beforePublication();
+  const output = validateStudioRunOutput(input, await requirePort(context.application).execute(input, { ...control, allowTrustedCode: true }));
+  assertSucceeded(output);
+  await control.beforePublication();
+  await writeOperationCompletionCheckpoint(context, definitionIdentity, output);
+  return output;
+}
+
+/** Reconciliation never invokes authored source and never returns permission to retry. */
+export async function reconcileStudioRun(context: OperationExecutionContext, exactInput: unknown, checkpointOutput?: unknown): Promise<StudioReconciliation> {
+  const input = boundInput(exactInput);
+  const control = controlFor(context);
+  throwIfAborted(control.signal);
+  const recovered = await requirePort(context.application).reconcile(input, control);
+  throwIfAborted(control.signal);
+  if (recovered.kind !== "completed") return recovered;
+  const output = validateStudioRunOutput(input, recovered.output);
+  if (output.document.state !== "succeeded") return { kind: "ambiguous", message: "Studio retained job did not complete successfully; no automatic execution is allowed." };
+  if (checkpointOutput !== undefined && canonicalJson(StudioRunOutputSchema.parse(checkpointOutput)) !== canonicalJson(output)) {
+    return { kind: "incompatible", message: "Studio checkpoint disagrees with the authoritative native job receipt." };
+  }
+  return { kind: "completed", output };
+}
+
+export const studioRunOperationDefinition = {
+  ...definitionIdentity,
+  inputSchema: StudioRunInputSchema, outputSchema: StudioRunOutputSchema,
+  lifecycle: { kind: "local-artifact", execute: executeStudioRun },
+  policy: {
+    cache: "exact-run", cancellable: true, effect: "local-derived-write", maxDurationMs: 6 * 60 * 60 * 1000,
+    maxFanOut: 0, maxInputBytes: 64 * 1024 * 1024, maxOutputBytes: 64 * 1024 * 1024,
+    preparation: ["local-media"], resources: [
+      { amount: 1, resource: "cpu" }, { amount: 1, resource: "local-io" },
+      { amount: 1, resource: "ffmpeg" }, { amount: 1, resource: "output-publication" },
+    ], resume: "verified-receipt",
+  },
+  receiptReference: output => output.receipt.path,
+  summarize: output => ({ kind: "slopcamera.studio.run", fields: { jobId: output.document.jobId, planSha256: output.document.planSha256, state: output.document.state, outputs: output.outputs.length } }),
+} satisfies OperationDefinition<"slopcamera.studio.run", StudioRunInput, StudioRunOutput>;

package/apps/desktop/application/output-publication-lease.ts

@@ -0,0 +1,163 @@
+import {
+  lstat,
+  mkdir,
+  realpath,
+} from "node:fs/promises";
+import { join } from "node:path";
+import { Effect } from "effect";
+
+import {
+  RepositoryRelativePathSchema,
+  VideoProjectIdSchema,
+} from "../contracts";
+import { sha256Hex } from "../core/canonical-json";
+import { acquireMutationLease, type MutationLease } from "../cli/mutation-lock";
+import type { ApplicationContext } from "./context";
+import { ApplicationError } from "./errors";
+import { operationBoundary, operationFinally, operationResource, type OperationEffectFailure } from "./operation-effects";
+
+const OUTPUT_LEASE_ROOT = "output-publication-leases";
+const inProcessOutputTails = new Map<string, Promise<void>>();
+
+export interface OutputPublicationTarget {
+  readonly outputPath: string;
+  readonly projectId: string;
+}
+
+async function privatePhysicalDirectory(
+  path: string,
+  create: boolean,
+): Promise<string> {
+  if (create) await mkdir(path, { mode: 0o700, recursive: true });
+  const details = await lstat(path);
+  if (
+    details.isSymbolicLink()
+    || !details.isDirectory()
+    || (details.mode & 0o077) !== 0
+  ) {
+    throw new ApplicationError(
+      "unsafe-path",
+      `Output publication lease state must be a private physical directory: ${path}`,
+    );
+  }
+  return await realpath(path);
+}
+
+async function leaseDirectory(
+  application: ApplicationContext,
+  target: OutputPublicationTarget,
+): Promise<{
+  readonly directory: string;
+  readonly outputPath: string;
+  readonly projectId: string;
+}> {
+  const projectId = VideoProjectIdSchema.parse(target.projectId);
+  const outputPath = RepositoryRelativePathSchema.parse(target.outputPath);
+  if (!outputPath.startsWith("renders/")) {
+    throw new ApplicationError(
+      "unsafe-path",
+      "Workflow render outputs must remain beneath the project renders directory.",
+    );
+  }
+  const privateRoot = await privatePhysicalDirectory(
+    application.paths.privateRoot,
+    true,
+  );
+  const rootPath = join(privateRoot, OUTPUT_LEASE_ROOT);
+  await mkdir(rootPath, { mode: 0o700, recursive: true });
+  const root = await privatePhysicalDirectory(rootPath, false);
+  const key = sha256Hex(
+    `studio.output-publication-lease/v1\0${projectId}\0${outputPath}`,
+  );
+  const requestedDirectory = join(root, key);
+  await mkdir(requestedDirectory, { mode: 0o700, recursive: true });
+  return {
+    directory: await privatePhysicalDirectory(requestedDirectory, false),
+    outputPath,
+    projectId,
+  };
+}
+
+function reserveOutputTurn(key: string): { readonly ready: Promise<void>; release(): void } {
+  const previous = inProcessOutputTails.get(key) ?? Promise.resolve();
+  const { promise: settled, resolve: complete } = Promise.withResolvers<void>();
+  inProcessOutputTails.set(key, settled);
+  let released = false;
+  return {
+    ready: previous,
+    release: () => {
+      if (released) return;
+      released = true;
+      if (inProcessOutputTails.get(key) === settled) inProcessOutputTails.delete(key);
+      complete();
+    },
+  };
+}
+
+interface OutputLease extends MutationLease {
+  releaseTurn(): void;
+}
+
+async function acquireOutputLease(
+  application: ApplicationContext,
+  target: OutputPublicationTarget,
+): Promise<OutputLease> {
+  const targetLease = await leaseDirectory(application, target);
+  // Promise and native Effect callers reserve in the same physical-key queue.
+  const turn = reserveOutputTurn(targetLease.directory);
+  await turn.ready;
+  try {
+    const lease = await acquireMutationLease(targetLease.directory, {
+      command: "workflow:render.project",
+      label: `${targetLease.projectId}/${targetLease.outputPath}`,
+      now: application.clock.now,
+    });
+    return { ...lease, releaseTurn: turn.release };
+  } catch (error) {
+    turn.release();
+    throw error;
+  }
+}
+
+export function withOutputPublicationLeaseEffect<Value, R>(
+  application: ApplicationContext,
+  target: OutputPublicationTarget,
+  use: Effect.Effect<Value, OperationEffectFailure, R>,
+): Effect.Effect<Value, OperationEffectFailure, R> {
+  return operationResource(
+    operationBoundary("publication", () => acquireOutputLease(application, target)),
+    () => use,
+    lease => operationFinally(
+      operationFinally(
+        operationBoundary("cleanup", () => lease.close()),
+        operationBoundary("cleanup", () => lease.unlinkIfOwned()),
+      ),
+      Effect.sync(() => lease.releaseTurn()),
+    ),
+  );
+}
+
+/**
+ * Serializes only publication of one exact project output. Different output
+ * paths retain scheduler and process-level concurrency.
+ */
+export async function withOutputPublicationLease<Value>(
+  application: ApplicationContext,
+  target: OutputPublicationTarget,
+  execute: () => Promise<Value>,
+): Promise<Value> {
+  const lease = await acquireOutputLease(application, target);
+  try {
+    return await execute();
+  } finally {
+    try {
+      await lease.close();
+    } finally {
+      try {
+        await lease.unlinkIfOwned();
+      } finally {
+        lease.releaseTurn();
+      }
+    }
+  }
+}

package/apps/desktop/application/project-publication-lease.ts

@@ -0,0 +1,233 @@
+import type { ApplicationContext } from "./context";
+import { ApplicationError } from "./errors";
+import type { OperationKind } from "./operation";
+import {
+  ProjectAnalysisReferenceSchema,
+  VideoProjectV1Schema,
+  type VideoProjectV1,
+} from "../contracts";
+import { canonicalJson } from "../core/canonical-json";
+import {
+  canonicalSlopcameraPersistenceDocument,
+  createNodeBundleFileSystem,
+  saveVideoProject,
+} from "../core/storage";
+import { withMutationLock } from "../cli/mutation-lock";
+import {
+  recoverProjectStateTransaction,
+} from "../cli/project-state-transaction";
+import { resolveProjectDirectory } from "../cli/project-service";
+import {
+  assertProjectEditBasis,
+  openProjectSnapshot,
+  type ProjectEditBasis,
+  type OpenProjectSnapshot,
+} from "./project-store";
+
+const inProcessPublicationTails = new Map<string, Promise<void>>();
+
+async function withInProcessPublicationQueue<Value>(
+  key: string,
+  execute: () => Promise<Value>,
+): Promise<Value> {
+  const previous = inProcessPublicationTails.get(key) ?? Promise.resolve();
+  const result = previous.then(execute);
+  const settled = result.then(
+    () => undefined,
+    () => undefined,
+  );
+  inProcessPublicationTails.set(key, settled);
+  try {
+    return await result;
+  } finally {
+    if (inProcessPublicationTails.get(key) === settled) {
+      inProcessPublicationTails.delete(key);
+    }
+  }
+}
+
+function projectReference(input: unknown): string {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new ApplicationError(
+      "invalid-data",
+      "A project publication operation requires an object input.",
+    );
+  }
+  const project = (input as Readonly<Record<string, unknown>>).project;
+  if (typeof project !== "string") {
+    throw new ApplicationError(
+      "invalid-data",
+      "A project publication operation requires a project reference.",
+    );
+  }
+  return project;
+}
+
+async function withResolvedProjectMutationLease<Value>(
+  application: ApplicationContext,
+  reference: string,
+  command: string,
+  execute: (
+    directory: Awaited<ReturnType<typeof resolveProjectDirectory>>,
+  ) => Promise<Value>,
+): Promise<Value> {
+  const directory = await resolveProjectDirectory(
+    application.paths.projectRoot,
+    reference,
+  );
+  return await withInProcessPublicationQueue(directory.path, async () =>
+    await withMutationLock(directory.path, {
+      command,
+      label: `project ${directory.id}`,
+      now: application.clock.now,
+    }, async () => await execute(directory)));
+}
+
+/**
+ * Bind one immutable project/plan generation while sharing the same brief
+ * in-process and physical mutation lease as project publication. The lease is
+ * released before any analysis work begins. Reads fail closed on an unsettled
+ * transaction; only mutation owners may recover one.
+ */
+export async function openLeasedProjectSnapshot(
+  application: ApplicationContext,
+  reference: string,
+): Promise<OpenProjectSnapshot> {
+  return await withResolvedProjectMutationLease(
+    application,
+    reference,
+    "workflow:project.snapshot:read",
+    async directory => await openProjectSnapshot(
+      application.paths.projectRoot,
+      directory.id,
+    ),
+  );
+}
+
+/** Serialize only the checked publication phase with existing CLI mutations. */
+export async function withProjectPublicationLease<Value>(
+  application: ApplicationContext,
+  operation: OperationKind,
+  input: unknown,
+  execute: () => Promise<Value>,
+  beforeRecoveryMutation?: () => Promise<void>,
+): Promise<Value> {
+  const reference = projectReference(input);
+  return await withResolvedProjectMutationLease(
+    application,
+    reference,
+    `workflow:${operation}`,
+    async directory => {
+      // Transaction recovery may itself restore project or plan bytes. A
+      // reconciliation caller therefore fences after acquiring the physical
+      // lock and immediately before allowing that recovery write boundary.
+      await beforeRecoveryMutation?.();
+      await recoverProjectStateTransaction(createNodeBundleFileSystem(
+        directory.path,
+      ));
+      return await execute();
+    },
+  );
+}
+
+type ProjectAnalysisReference = ReturnType<
+  typeof ProjectAnalysisReferenceSchema.parse
+>;
+
+export function projectAnalysisPublicationBasis(
+  snapshot: OpenProjectSnapshot,
+): ProjectEditBasis {
+  return snapshot.editBasis;
+}
+
+export interface MergeProjectAnalysisReferenceOptions {
+  readonly application: ApplicationContext;
+  /**
+   * The original edit basis that authorized the analysis. Its prefix
+   * commitment deliberately permits later sibling analyses while rejecting
+   * removal, reordering, or replacement of any prior authority.
+   */
+  readonly basis: ProjectEditBasis;
+  /**
+   * Revalidates a durable workflow fence after waiting for the physical
+   * publication lock and immediately before mutating the project document.
+   */
+  readonly beforePublication?: () => Promise<void>;
+  readonly operation: Extract<OperationKind, `analysis.${string}`>;
+  readonly project: string;
+  readonly reference: ProjectAnalysisReference;
+}
+
+export async function mergeProjectAnalysisReference(
+  options: MergeProjectAnalysisReferenceOptions,
+): Promise<{
+  readonly project: VideoProjectV1;
+  readonly reference: ProjectAnalysisReference;
+}> {
+  const reference = ProjectAnalysisReferenceSchema.parse(options.reference);
+  if (Date.parse(reference.createdAt) < Date.parse(options.basis.projectUpdatedAt)) {
+    throw new ApplicationError(
+      "conflict",
+      "The analysis update time cannot precede the project snapshot update time.",
+    );
+  }
+  return await withProjectPublicationLease(
+    options.application,
+    options.operation,
+    { project: options.project },
+    async () => {
+      await options.beforePublication?.();
+      const latest = await openProjectSnapshot(
+        options.application.paths.projectRoot,
+        options.project,
+      );
+      assertProjectEditBasis(options.basis, latest);
+      const existing = latest.project.analyses.find(
+        candidate => candidate.analysisId === reference.analysisId,
+      );
+      if (existing !== undefined) {
+        if (canonicalJson(existing) !== canonicalJson(reference)) {
+          throw new ApplicationError(
+            "conflict",
+            `Project analysis identity was published with different evidence: ${reference.analysisId}`,
+          );
+        }
+        return { project: latest.project, reference };
+      }
+      const publicationSnapshot = await openProjectSnapshot(
+        options.application.paths.projectRoot,
+        options.project,
+      );
+      // Reassert the original append-only basis after the final durable
+      // workflow fence. This both preserves sibling analyses that arrived
+      // during recovery and makes the check the last fallible I/O before save.
+      assertProjectEditBasis(options.basis, publicationSnapshot);
+      const publicationExisting = publicationSnapshot.project.analyses.find(
+        candidate => candidate.analysisId === reference.analysisId,
+      );
+      if (publicationExisting !== undefined) {
+        if (canonicalJson(publicationExisting) !== canonicalJson(reference)) {
+          throw new ApplicationError(
+            "conflict",
+            `Project analysis identity was published with different evidence: ${reference.analysisId}`,
+          );
+        }
+        return { project: publicationSnapshot.project, reference };
+      }
+      const updatedAt = Date.parse(reference.createdAt)
+        >= Date.parse(publicationSnapshot.project.updatedAt)
+        ? reference.createdAt
+        : publicationSnapshot.project.updatedAt;
+      const project = canonicalSlopcameraPersistenceDocument(VideoProjectV1Schema.parse({
+        ...publicationSnapshot.project,
+        analyses: [...publicationSnapshot.project.analyses, reference],
+        updatedAt,
+      }));
+      await options.beforePublication?.();
+      assertProjectEditBasis(options.basis, publicationSnapshot);
+      await saveVideoProject(publicationSnapshot.openProject.fileSystem, project);
+      return { project, reference };
+    },
+    options.beforePublication,
+  );
+}