@hraness/slopcamera 3.2.4

package/apps/desktop/application/spatial-project-store.ts

@@ -0,0 +1,286 @@
+import {
+  SPATIAL_PROJECT_LIMITS,
+  SpatialProjectAttemptV1Schema,
+  SpatialProjectArtifactSchema,
+  SpatialProjectBasisSchema,
+  SpatialProjectHeadV2Schema,
+  SpatialProjectRevisionV2Schema,
+  SpatialProjectSettlementV1Schema,
+  SpatialTransactionIdSchema,
+  type SpatialProjectArtifact,
+  type SpatialProjectBasis,
+  type SpatialProjectHeadV2,
+  type SpatialProjectRevisionV2,
+  type SpatialProjectSceneSource,
+} from "../contracts/spatial-project";
+import { ProjectEditPlanV1Schema, VideoProjectV1Schema } from "../contracts/project";
+import { canonicalJson, sha256Hex } from "../core/canonical-json";
+import type { SpatialDurabilityPort } from "../core/spatial-durability";
+import {
+  spatialProjectArtifact,
+  spatialProjectContents,
+  spatialProjectDocumentText,
+  spatialProjectRevisionSha256,
+  validateSpatialProjectContents,
+  type SpatialProjectContents,
+} from "../core/spatial-project";
+import { saveImmutableText, type BundleFileSystem } from "../core/storage";
+import { parseSpatialScene, spatialSceneSha256 } from "../../../src/spatial-scene/index";
+import { hashProjectGeneration } from "./project-store";
+import { createProjectEditRevisionDocument } from "./receipts";
+
+/** Adapter-owned authority. Never constructed from operation input. */
+export interface SpatialProjectCustody {
+  assertHeld(): Promise<void>;
+  assertLegacyTransactionSettled(): Promise<void>;
+}
+export interface SpatialProjectStorePorts {
+  /** Exact adapter-owned project identity, supplied by every production adapter. */
+  readonly projectId?: string;
+  readonly fileSystem: BundleFileSystem;
+  readonly durability: SpatialDurabilityPort;
+  readonly custody: SpatialProjectCustody;
+}
+export interface SpatialProjectSnapshot {
+  readonly version: 2;
+  readonly basis: SpatialProjectBasis;
+  readonly headText: string;
+  readonly head: SpatialProjectHeadV2;
+  readonly revision: SpatialProjectRevisionV2;
+  readonly contents: SpatialProjectContents;
+}
+export interface SpatialLegacyProjectSnapshot {
+  readonly version: 1;
+  readonly basis: SpatialProjectBasis;
+  readonly headText: string;
+  readonly contents: SpatialProjectContents;
+}
+export type SpatialProjectAuthority = SpatialProjectSnapshot | SpatialLegacyProjectSnapshot;
+export type SpatialProjectCommitResult =
+  | { readonly kind: "completed"; readonly attempt: SpatialProjectArtifact; readonly settlement: SpatialProjectArtifact; readonly projectRevisionSha256: string; readonly currentHeadMatches: boolean }
+  | { readonly kind: "conflict" | "precommit"; readonly message: string; readonly attempt?: SpatialProjectArtifact }
+  | { readonly kind: "ambiguous"; readonly attempt: SpatialProjectArtifact; readonly message: string };
+
+const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
+const isMissing = (error: unknown): boolean => error instanceof Error && "code" in error && error.code === "ENOENT";
+function assertNotCancelled(signal?: AbortSignal): void {
+  if (signal?.aborted === true) throw new Error("Spatial publication cancelled before head dispatch.");
+}
+async function readBoundedText(fs: BundleFileSystem, path: string, maximum = SPATIAL_PROJECT_LIMITS.documentBytes): Promise<string> {
+  if (fs.inspectFile !== undefined && (await fs.inspectFile(path, maximum)).bytes > maximum) throw new Error("Spatial structured byte budget exceeded.");
+  const text = await fs.readText(path, maximum);
+  if (new TextEncoder().encode(text).byteLength > maximum) throw new Error("Spatial structured byte budget exceeded.");
+  return text;
+}
+async function readArtifact(fs: BundleFileSystem, input: SpatialProjectArtifact): Promise<string> {
+  const ref = SpatialProjectArtifactSchema.parse(input);
+  const text = await readBoundedText(fs, ref.path, ref.bytes);
+  if (sha256Hex(text) !== ref.sha256 || new TextEncoder().encode(text).byteLength !== ref.bytes) throw new Error("Spatial artifact integrity mismatch.");
+  return text;
+}
+async function publish(ports: SpatialProjectStorePorts, reference: SpatialProjectArtifact, text: string): Promise<void> {
+  await ports.custody.assertHeld();
+  await saveImmutableText({
+    ...ports.fileSystem,
+    readText: path => ports.fileSystem.readText(path, reference.bytes),
+  }, reference.path, text, reference.sha256);
+  await ports.durability.syncExactFile(reference.path, reference);
+  if (await readArtifact(ports.fileSystem, reference) !== text) throw new Error("Spatial immutable durability readback changed.");
+}
+async function verifyPayloads(fs: BundleFileSystem, contents: SpatialProjectContents, durability?: SpatialDurabilityPort): Promise<void> {
+  const payloads = new Map<string, { readonly path: string; readonly bytes: number; readonly sha256: string }>();
+  let sourceBytes = 0;
+  let outputBytes = 0;
+  const add = (payload: { readonly path: string; readonly bytes: number; readonly sha256: string }, kind: "source" | "output"): void => {
+    const prior = payloads.get(payload.path);
+    if (prior !== undefined) {
+      if (prior.bytes !== payload.bytes || prior.sha256 !== payload.sha256) throw new Error("Conflicting physical payload identity.");
+      return;
+    }
+    payloads.set(payload.path, payload);
+    if (kind === "source") sourceBytes += payload.bytes;
+    else outputBytes += payload.bytes;
+  };
+  for (const scene of contents.scenes) for (const asset of scene.document.assets) add(asset.payload, "source");
+  for (const candidate of contents.candidates) for (const output of candidate.outputs) add(output, "output");
+  if (sourceBytes > 256 * 1024 * 1024 || outputBytes > 1_024 * 1024 * 1024) throw new Error("Spatial project payload budget exceeded.");
+  if (payloads.size > 0 && fs.inspectFile === undefined) throw new Error("Physical payload inspection is required for spatial source and candidate publication.");
+  for (const payload of payloads.values()) {
+    const actual = await fs.inspectFile?.(payload.path, payload.bytes);
+    if (actual === undefined || actual.bytes !== payload.bytes || actual.sha256 !== payload.sha256) throw new Error("Spatial physical payload integrity mismatch.");
+    await durability?.syncExactFile(payload.path, payload);
+  }
+}
+async function loadExactHead(fs: BundleFileSystem, head: SpatialProjectHeadV2, headText: string): Promise<SpatialProjectSnapshot> {
+  const revisionText = await readArtifact(fs, head.revision);
+  const revision = SpatialProjectRevisionV2Schema.parse(JSON.parse(revisionText));
+  if (revisionText !== spatialProjectDocumentText(revision)
+    || spatialProjectRevisionSha256(revision) !== head.projectRevisionSha256
+    || revision.projectId !== head.projectId || revision.transactionId !== head.transactionId) throw new Error("Spatial head and revision binding mismatch.");
+  // Reuse the unchanged V1 revision verifier, including its structural/hash laws.
+  createProjectEditRevisionDocument(revision.legacy.project, revision.legacy.projectEditPlan);
+  const scenes: SpatialProjectSceneSource[] = [];
+  for (const reference of revision.scenes) {
+    const text = await readArtifact(fs, reference.artifact);
+    const document = parseSpatialScene(JSON.parse(text));
+    if (text !== spatialProjectDocumentText(document) || spatialSceneSha256(document) !== reference.sceneSha256) throw new Error("Spatial source digest or canonical bytes mismatch.");
+    scenes.push({ sceneSha256: reference.sceneSha256, document: structuredClone(document) as SpatialProjectSceneSource["document"] });
+  }
+  const contents = spatialProjectContents(revision, scenes);
+  await verifyPayloads(fs, contents);
+  return { version: 2, basis: { version: 2, sha256: head.projectRevisionSha256 }, headText, head, revision, contents };
+}
+/** V2 reads consult only project.json and immutable references, never historical V1 pointers. */
+export async function loadSpatialProject(fs: BundleFileSystem): Promise<SpatialProjectSnapshot> {
+  const text = await readBoundedText(fs, "project.json");
+  const head = SpatialProjectHeadV2Schema.parse(JSON.parse(text));
+  if (text !== spatialProjectDocumentText(head)) throw new Error("Noncanonical spatial head.");
+  return await loadExactHead(fs, head, text);
+}
+export async function readSpatialProjectAuthority(ports: SpatialProjectStorePorts): Promise<SpatialProjectAuthority> {
+  const text = await readBoundedText(ports.fileSystem, "project.json");
+  const value: unknown = JSON.parse(text);
+  const head = SpatialProjectHeadV2Schema.safeParse(value);
+  if (head.success) {
+    if (ports.projectId !== undefined && ports.projectId !== head.data.projectId) throw new Error("Spatial head belongs to another project.");
+    if (text !== spatialProjectDocumentText(head.data)) throw new Error("Noncanonical spatial head.");
+    return await loadExactHead(ports.fileSystem, head.data, text);
+  }
+  const project = VideoProjectV1Schema.parse(value);
+  if (ports.projectId !== undefined && ports.projectId !== project.projectId) throw new Error("Legacy head belongs to another project.");
+  await ports.custody.assertLegacyTransactionSettled();
+  // Match the existing V1 reader's authoritative pair exactly, including a
+  // nullable historical currentEditPlanPath field in the frozen project value.
+  const projectEditPlan = ProjectEditPlanV1Schema.parse(JSON.parse(await readBoundedText(ports.fileSystem, "edits/current.json")));
+  createProjectEditRevisionDocument(project, projectEditPlan);
+  return {
+    version: 1,
+    basis: { version: 1, sha256: hashProjectGeneration(project, projectEditPlan).generationSha256 },
+    headText: text,
+    contents: { legacy: { project, projectEditPlan }, scenes: [], shots: [], candidates: [], selections: [] },
+  };
+}
+export interface SpatialProjectCommitOptions {
+  readonly ports: SpatialProjectStorePorts;
+  readonly expected: SpatialProjectBasis;
+  readonly transactionId: string;
+  readonly change: (current: SpatialProjectAuthority) => SpatialProjectContents;
+  readonly signal?: AbortSignal;
+}
+/** Must run under the existing publication lease, which remains owned until settlement. */
+export async function commitSpatialProjectRevision(options: SpatialProjectCommitOptions): Promise<SpatialProjectCommitResult> {
+  const { ports } = options;
+  let attempt: SpatialProjectArtifact | undefined;
+  let dispatched = false;
+  try {
+    await ports.custody.assertHeld();
+    assertNotCancelled(options.signal);
+    const expected = SpatialProjectBasisSchema.parse(options.expected);
+    const transactionId = SpatialTransactionIdSchema.parse(options.transactionId);
+    if (ports.fileSystem.writeTextAtomicGuarded === undefined) throw new Error("Spatial head publication requires the guarded atomic-replace capability.");
+    const current = await readSpatialProjectAuthority(ports);
+    if (canonicalJson(current.basis) !== canonicalJson(expected)) return { kind: "conflict", message: "Expected complete project revision is stale." };
+    const contents = validateSpatialProjectContents(options.change(current));
+    const scenes = contents.scenes.map(source => ({ sceneSha256: source.sceneSha256, artifact: spatialProjectArtifact("scenes", spatialProjectDocumentText(source.document)) }));
+    const revision = SpatialProjectRevisionV2Schema.parse({
+      kind: "slopcamera.spatial-project-revision", schemaVersion: 2, projectId: current.contents.legacy.project.projectId,
+      parent: expected, transactionId, legacy: contents.legacy, scenes, shots: contents.shots, candidates: contents.candidates, selections: contents.selections,
+    });
+    // All source dependencies are validated and made durable before publishing a head.
+    await verifyPayloads(ports.fileSystem, contents, ports.durability);
+    for (const source of contents.scenes) {
+      const text = spatialProjectDocumentText(source.document);
+      await publish(ports, spatialProjectArtifact("scenes", text), text);
+    }
+    const revisionText = spatialProjectDocumentText(revision);
+    const reference = spatialProjectArtifact("revisions", revisionText);
+    await publish(ports, reference, revisionText);
+    const after = SpatialProjectHeadV2Schema.parse({
+      kind: "slopcamera.spatial-project-head", schemaVersion: 2, projectId: revision.projectId,
+      projectRevisionSha256: spatialProjectRevisionSha256(revision), revision: reference, transactionId,
+    });
+    const attemptText = spatialProjectDocumentText(SpatialProjectAttemptV1Schema.parse({
+      kind: "slopcamera.spatial-project-attempt", schemaVersion: 1, beforeHeadSha256: sha256Hex(current.headText), expected, after,
+    }));
+    attempt = spatialProjectArtifact("attempts", attemptText);
+    await publish(ports, attempt, attemptText);
+    await ports.custody.assertHeld();
+    assertNotCancelled(options.signal);
+    const last = await readSpatialProjectAuthority(ports);
+    if (canonicalJson(last.basis) !== canonicalJson(expected) || last.headText !== current.headText) return { kind: "conflict", attempt, message: "Project changed before publication." };
+    const afterText = spatialProjectDocumentText(after);
+    // The final authority read is asynchronous. Its completion is not evidence
+    // that the lease or cancellation state survived that read.
+    await ports.custody.assertHeld();
+    assertNotCancelled(options.signal);
+    await ports.fileSystem.writeTextAtomicGuarded("project.json", afterText, async () => {
+      // The native adapter stages and flushes its temporary file before this
+      // fence, then starts rename immediately after it returns. A cancellation
+      // or lost lease during staging therefore cannot publish an authority.
+      await ports.custody.assertHeld();
+      assertNotCancelled(options.signal);
+      // Beyond this exact dispatch point a thrown write cannot prove noncommit.
+      dispatched = true;
+    });
+    await ports.durability.syncExactFile("project.json", { bytes: new TextEncoder().encode(afterText).byteLength, sha256: sha256Hex(afterText) });
+    if (await readBoundedText(ports.fileSystem, "project.json") !== afterText) throw new Error("Spatial head readback mismatch.");
+    await loadExactHead(ports.fileSystem, after, afterText);
+    const receiptText = settlementText(attempt, afterText);
+    const settlement = spatialProjectArtifact("receipts", receiptText);
+    await publish(ports, settlement, receiptText);
+    return { kind: "completed", attempt, settlement, projectRevisionSha256: after.projectRevisionSha256, currentHeadMatches: true };
+  } catch (error) {
+    if (dispatched && attempt !== undefined) return { kind: "ambiguous", attempt, message: messageOf(error) };
+    return { kind: "precommit", message: messageOf(error), ...(attempt === undefined ? {} : { attempt }) };
+  }
+}
+export async function migrateSpatialProject(options: Omit<SpatialProjectCommitOptions, "change"> & {
+  readonly scenes: readonly SpatialProjectSceneSource[];
+  readonly shots: SpatialProjectContents["shots"];
+}): Promise<SpatialProjectCommitResult> {
+  return await commitSpatialProjectRevision({ ...options, change(current) {
+    if (current.version !== 1) throw new Error("Spatial migration requires an existing V1 authority.");
+    return { ...current.contents, scenes: options.scenes, shots: options.shots };
+  } });
+}
+function settlementText(attempt: SpatialProjectArtifact, headText: string): string {
+  return spatialProjectDocumentText(SpatialProjectSettlementV1Schema.parse({
+    kind: "slopcamera.spatial-project-settlement", schemaVersion: 1, attempt, headSha256: sha256Hex(headText),
+  }));
+}
+/** Reconciliation proves an exact commit; it never restores, overwrites, or replays a head. */
+export async function reconcileSpatialProjectCommit(options: {
+  readonly ports: SpatialProjectStorePorts;
+  readonly attempt: SpatialProjectArtifact;
+}): Promise<SpatialProjectCommitResult> {
+  const { ports } = options;
+  const reference = SpatialProjectArtifactSchema.parse(options.attempt);
+  try {
+    await ports.custody.assertHeld();
+    if (!reference.path.startsWith("spatial/attempts/")) throw new Error("Reconciliation requires an immutable attempt reference.");
+    const text = await readArtifact(ports.fileSystem, reference);
+    const attempt = SpatialProjectAttemptV1Schema.parse(JSON.parse(text));
+    if (ports.projectId !== undefined && ports.projectId !== attempt.after.projectId) throw new Error("Spatial attempt belongs to another project.");
+    if (text !== spatialProjectDocumentText(attempt)) throw new Error("Noncanonical spatial attempt.");
+    const headText = spatialProjectDocumentText(attempt.after);
+    const receiptText = settlementText(reference, headText);
+    const receipt = spatialProjectArtifact("receipts", receiptText);
+    const snapshot = await loadExactHead(ports.fileSystem, attempt.after, headText);
+    if (canonicalJson(snapshot.revision.parent) !== canonicalJson(attempt.expected)) throw new Error("Spatial attempt does not bind its revision parent.");
+    let provenReceipt = false;
+    try {
+      if (await readArtifact(ports.fileSystem, receipt) !== receiptText) throw new Error("Spatial settlement receipt mismatch.");
+      // Existing identical bytes may come from a failed link/fsync attempt.
+      await ports.durability.syncExactFile(receipt.path, receipt);
+      provenReceipt = true;
+    } catch (error) { if (!isMissing(error)) throw error; }
+    const matches = await readBoundedText(ports.fileSystem, "project.json") === headText;
+    if (!provenReceipt) {
+      if (!matches) throw new Error("No durable completion proof and current head differs; rollback and replay are forbidden.");
+      await ports.durability.syncExactFile("project.json", { bytes: new TextEncoder().encode(headText).byteLength, sha256: sha256Hex(headText) });
+      if (await readBoundedText(ports.fileSystem, "project.json") !== headText) throw new Error("Spatial head changed during reconciliation.");
+      await publish(ports, receipt, receiptText);
+    }
+    return { kind: "completed", attempt: reference, settlement: receipt, projectRevisionSha256: attempt.after.projectRevisionSha256, currentHeadMatches: matches };
+  } catch (error) { return { kind: "ambiguous", attempt: reference, message: messageOf(error) }; }
+}

package/apps/desktop/application/spatial-render-projection.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+import { HtmlOverlayExecutionProfileSchema } from "../html-overlay/execution-profile";
+
+import { createBoundedJsonValueSnapshot, deepFreezeJson } from "../../../src/code/json-snapshot";
+import { reduceSpatialFrameRate, spatialFrameCount } from "../../../src/spatial-scene/index";
+import { SpatialDigestSchema, SpatialFrameRateSchema, SpatialShotIdSchema, SpatialShotV1Schema } from "../../../src/spatial-scene/contracts";
+import { ProjectEditPlanV1Schema, VideoProjectV1Schema } from "../contracts/project";
+import { RepositoryRelativePathSchema } from "../contracts/recording";
+import { SPATIAL_PROJECT_LIMITS, SpatialProjectBasisSchema, SpatialProjectHeadV2Schema, SpatialProjectRevisionV2Schema } from "../contracts/spatial-project";
+import { canonicalJson, canonicalJsonSha256, sha256Hex } from "../core/canonical-json";
+import { hashProjectStructure } from "../core/project-plan";
+import { compileProjectRenderPlan } from "../core/project-render-plan";
+import { SpatialProjectContentsSchema, spatialProjectArtifact, spatialProjectContents, spatialProjectDocumentText, spatialProjectRevisionSha256, spatialShotSha256 } from "../core/spatial-project";
+import { projectEditRevisionPath } from "../core/storage";
+import { createProjectEditRevisionDocument, ProjectEditRevisionArtifactSchema } from "./receipts";
+import type { SpatialProjectSnapshot } from "./spatial-project-store";
+
+export const SpatialSceneProgramPolicySchema = z.strictObject({
+  kind: z.literal("full-frame-above-legacy-video-below-overlays"),
+  alpha: z.enum(["opaque", "straight"]),
+});
+export const SpatialProjectionOutputSchema = z.strictObject({
+  executionProfile: HtmlOverlayExecutionProfileSchema.optional(),
+  pixelWidth: z.number().int().positive().max(16_384),
+  pixelHeight: z.number().int().positive().max(16_384),
+  frameRate: SpatialFrameRateSchema,
+  background: z.string().regex(/^#[a-fA-F0-9]{6}ff$/u),
+  /** Canvas transfer; final codec conversion is separately recorded by the encoder. */
+  colorSpace: z.literal("srgb"),
+}).superRefine((output, context) => {
+  if (output.pixelWidth * output.pixelHeight > 33_554_432 || output.frameRate.numerator / output.frameRate.denominator > 240) context.addIssue({ code: "custom", message: "Projection exceeds the existing compositor dimensions or frame-rate limit." });
+});
+export const SpatialMaterializedShotVideoSchema = z.strictObject({
+  shotId: SpatialShotIdSchema,
+  shotSha256: SpatialDigestSchema,
+  sceneSha256: SpatialDigestSchema,
+  receiptSha256: SpatialDigestSchema,
+  artifact: z.strictObject({
+    path: RepositoryRelativePathSchema.refine(path => /^spatial\/outputs\/[a-f0-9]{64}\.(?:mov|mp4|webm)$/u.test(path)),
+    sha256: SpatialDigestSchema,
+    bytes: z.number().int().positive().max(256 * 1024 * 1024),
+  }).superRefine((artifact, context) => {
+    if (!artifact.path.startsWith(`spatial/outputs/${artifact.sha256}.`)) context.addIssue({ code: "custom", message: "Materialized shot path must name its exact payload digest." });
+  }),
+  pixelWidth: z.number().int().positive().max(16_384),
+  pixelHeight: z.number().int().positive().max(16_384),
+  frameRate: SpatialFrameRateSchema,
+  frameCount: z.number().int().positive().max(864_000),
+  alpha: z.enum(["opaque", "straight"]),
+  colorSpace: z.literal("srgb"),
+  codec: z.enum(["qtrle", "h264", "vp9", "prores"]),
+  container: z.enum(["mov", "mp4", "webm"]),
+  streamIndex: z.number().int().min(0).max(255),
+}).superRefine((video, context) => {
+  if (!video.artifact.path.endsWith(`.${video.container}`)) context.addIssue({ code: "custom", message: "Materialized shot extension and container must match." });
+  if (((video.codec === "qtrle" || video.codec === "prores") && video.container !== "mov")
+    || (video.codec === "vp9" && video.container !== "webm")
+    || (video.codec === "h264" && video.container === "webm")) context.addIssue({ code: "custom", message: "Materialized codec and container are incompatible." });
+  if (video.alpha === "straight" && (video.container !== "mov" || video.codec !== "qtrle")) context.addIssue({ code: "custom", message: "The initial straight-alpha projection requires the qualified qtrle MOV profile." });
+});
+export const SceneRenderProjectionV1Schema = z.strictObject({
+  kind: z.literal("slopcamera.scene-render-projection"),
+  schemaVersion: z.literal(1),
+  source: SpatialProjectHeadV2Schema,
+  policy: SpatialSceneProgramPolicySchema,
+  output: SpatialProjectionOutputSchema,
+  shots: z.array(z.strictObject({ shot: SpatialShotV1Schema, materialized: SpatialMaterializedShotVideoSchema })).max(1_024),
+  legacyFrameRateAdapter: z.strictObject({
+    kind: z.literal("numeric-ratio-for-planning-only"),
+    value: z.number().positive().max(240),
+    requiredEncoderArgument: z.string().regex(/^[1-9][0-9]*\/[1-9][0-9]*$/u),
+  }),
+  derivedV1RevisionSha256: SpatialDigestSchema,
+  derivedV1Revision: ProjectEditRevisionArtifactSchema,
+  compositionPlanSha256: SpatialDigestSchema,
+}).superRefine((projection, context) => {
+  const rate = reduceSpatialFrameRate(projection.output.frameRate);
+  if (canonicalJson(rate) !== canonicalJson(projection.output.frameRate)
+    || projection.legacyFrameRateAdapter.value !== rate.numerator / rate.denominator
+    || projection.legacyFrameRateAdapter.requiredEncoderArgument !== `${rate.numerator}/${rate.denominator}`) context.addIssue({ code: "custom", message: "Projection frame-rate identities must agree exactly." });
+  if (projection.derivedV1Revision.path !== projectEditRevisionPath(projection.derivedV1Revision.sha256)) context.addIssue({ code: "custom", message: "Derived V1 revision must use its immutable byte-digest path." });
+  const seen = new Set<string>();
+  let endUs = 0;
+  for (const { shot, materialized } of projection.shots) {
+    if (seen.has(shot.shotId) || shot.range.startUs < endUs) context.addIssue({ code: "custom", message: "Projection shots must be unique, ordered, and nonoverlapping." });
+    seen.add(shot.shotId);
+    endUs = shot.range.endUs;
+    if (materialized.shotId !== shot.shotId || materialized.shotSha256 !== spatialShotSha256(shot)
+      || materialized.sceneSha256 !== shot.sceneSha256 || materialized.alpha !== projection.policy.alpha
+      || materialized.pixelWidth !== projection.output.pixelWidth || materialized.pixelHeight !== projection.output.pixelHeight
+      || materialized.colorSpace !== projection.output.colorSpace
+      || canonicalJson(materialized.frameRate) !== canonicalJson(rate)
+      || materialized.frameCount !== spatialFrameCount(shot.range.endUs - shot.range.startUs, rate)) context.addIssue({ code: "custom", message: "Projection materialized shot does not match its exact authored shot and output profile." });
+  }
+});
+export type SpatialMaterializedShotVideo = z.infer<typeof SpatialMaterializedShotVideoSchema>;
+export type SpatialProjectionOutput = z.infer<typeof SpatialProjectionOutputSchema>;
+export type SpatialSceneProgramPolicy = z.infer<typeof SpatialSceneProgramPolicySchema>;
+export type SceneRenderProjectionV1 = z.infer<typeof SceneRenderProjectionV1Schema>;
+const ProjectionRequestSchema = z.strictObject({
+  snapshot: z.strictObject({
+    version: z.literal(2), basis: SpatialProjectBasisSchema,
+    headText: z.string().max(SPATIAL_PROJECT_LIMITS.documentBytes),
+    head: SpatialProjectHeadV2Schema, revision: SpatialProjectRevisionV2Schema,
+    contents: SpatialProjectContentsSchema,
+  }),
+  materializedShots: z.array(SpatialMaterializedShotVideoSchema).max(SPATIAL_PROJECT_LIMITS.shots),
+  policy: SpatialSceneProgramPolicySchema,
+  output: SpatialProjectionOutputSchema,
+});
+
+export function spatialProjectionEncoderFrameRate(rateInput: unknown): string {
+  const rate = reduceSpatialFrameRate(rateInput);
+  return `${rate.numerator}/${rate.denominator}`;
+}
+
+/**
+ * Pure lowering from verified V2 authority and already-materialized, receipt-bound
+ * source-clock shot videos. This function never reads a mutable project or starts
+ * a render. The caller verifies the supplied physical videos/receipts before use.
+ *
+ * New video placements enter the logical source clock before the V1 compositor
+ * applies global cuts and speed once. V1 overlays are intentionally preserved:
+ * appending a shot as an overlay would incorrectly use compressed output time.
+ */
+export function createSpatialRenderProjection(input: {
+  readonly snapshot: SpatialProjectSnapshot;
+  readonly materializedShots: readonly SpatialMaterializedShotVideo[];
+  readonly policy: SpatialSceneProgramPolicy;
+  readonly output: SpatialProjectionOutput;
+}) {
+  const request = ProjectionRequestSchema.parse(createBoundedJsonValueSnapshot(input, SPATIAL_PROJECT_LIMITS.totalSceneBytes + 2 * SPATIAL_PROJECT_LIMITS.documentBytes, "spatial projection input", { maximumDepth: 48, maximumValues: 2_000_000 }).value);
+  const head = request.snapshot.head;
+  const aggregate = request.snapshot.revision;
+  if (request.snapshot.version !== 2 || request.snapshot.basis.version !== 2
+    || request.snapshot.basis.sha256 !== head.projectRevisionSha256
+    || spatialProjectRevisionSha256(aggregate) !== head.projectRevisionSha256
+    || aggregate.projectId !== head.projectId || aggregate.transactionId !== head.transactionId
+    || canonicalJson(spatialProjectArtifact("revisions", spatialProjectDocumentText(aggregate))) !== canonicalJson(head.revision)) throw new Error("Render projection requires the exact verified V2 aggregate and head.");
+  const contents = spatialProjectContents(aggregate, request.snapshot.contents.scenes);
+  const references = contents.scenes.map(scene => ({ sceneSha256: scene.sceneSha256, artifact: spatialProjectArtifact("scenes", spatialProjectDocumentText(scene.document)) }));
+  if (canonicalJson(references) !== canonicalJson(aggregate.scenes)) throw new Error("Render projection scene sources do not match the immutable aggregate.");
+  const policy = SpatialSceneProgramPolicySchema.parse(request.policy);
+  const rawOutput = SpatialProjectionOutputSchema.parse(request.output);
+  const output = { ...rawOutput, frameRate: reduceSpatialFrameRate(rawOutput.frameRate) };
+  const videos = request.materializedShots.map(video => SpatialMaterializedShotVideoSchema.parse(video));
+  if (videos.length !== contents.shots.length || new Set(videos.map(video => video.shotId)).size !== videos.length) throw new Error("Projection requires exactly one materialized video per shot.");
+  const shots = [...contents.shots].sort((a, b) => a.range.startUs - b.range.startUs || a.shotId.localeCompare(b.shotId));
+  for (let index = 1; index < shots.length; index++) if (shots[index]!.range.startUs < shots[index - 1]!.range.endUs) throw new Error("Full-frame camera-program projection rejects overlapping shot ranges.");
+  const base = contents.legacy;
+  const layers = base.project.placements.flatMap(placement => placement.enabled ? placement.video.flatMap(video => video.presentation.enabled ? [video.presentation.layer] : []) : []);
+  const layer = Math.max(-1, ...layers) + 1;
+  if (!Number.isSafeInteger(layer)) throw new Error("No safe integer video layer remains above legacy video.");
+  const numericFrameRate = output.frameRate.numerator / output.frameRate.denominator;
+  const assets = [...base.project.assets];
+  const placements = [...base.project.placements];
+  const boundShots: z.infer<typeof SceneRenderProjectionV1Schema>["shots"] = [];
+  for (const shot of shots) {
+    const materialized = videos.find(video => video.shotId === shot.shotId);
+    if (materialized === undefined || materialized.shotSha256 !== spatialShotSha256(shot)
+      || materialized.sceneSha256 !== shot.sceneSha256) throw new Error("Materialized video does not bind the exact shot and source scene.");
+    const durationUs = shot.range.endUs - shot.range.startUs;
+    if (materialized.pixelWidth !== output.pixelWidth || materialized.pixelHeight !== output.pixelHeight
+      || materialized.alpha !== policy.alpha || materialized.colorSpace !== output.colorSpace
+      || canonicalJson(reduceSpatialFrameRate(materialized.frameRate)) !== canonicalJson(output.frameRate)
+      || materialized.frameCount !== spatialFrameCount(durationUs, output.frameRate)) throw new Error("Materialized shot does not match the exact source duration and render profile.");
+    const key = spatialShotSha256(shot).slice(0, 48);
+    const assetId = `asset_spatial_${key}`;
+    const placementId = `placement_spatial_${key}`;
+    const streamId = `stream_spatial_${key}`;
+    if (assets.some(asset => asset.assetId === assetId || asset.streams.some(stream => stream.streamId === streamId))
+      || placements.some(placement => placement.placementId === placementId)) throw new Error("Derived spatial identity collides with a retained media identity.");
+    assets.push(VideoProjectV1Schema.shape.assets.element.parse({
+      assetId, createdAt: base.project.updatedAt, durationUs, label: `Spatial shot ${shot.shotId}`, role: "b-roll",
+      source: { kind: "generated", generator: "slopcamera.spatial-render-projection", generatorVersion: "1", sourceSha256: materialized.shotSha256 },
+      streams: [{ streamId, label: `Spatial shot ${shot.shotId}`, kind: "video", role: "b-roll", frameRate: numericFrameRate, pixelWidth: output.pixelWidth, pixelHeight: output.pixelHeight,
+        segments: [{ assetRange: { startUs: 0, endUs: durationUs }, fileRange: { startUs: 0, endUs: durationUs }, ...materialized.artifact, codec: materialized.codec, container: materialized.container, streamIndex: materialized.streamIndex }] }],
+    }));
+    placements.push({
+      placementId: placementId as typeof placements[number]["placementId"], assetId: assetId as typeof placements[number]["assetId"],
+      assetRange: { startUs: 0, endUs: durationUs }, enabled: true, audio: [],
+      sync: { anchors: [{ assetTimeUs: 0, projectTimeUs: shot.range.startUs }, { assetTimeUs: durationUs, projectTimeUs: shot.range.endUs }], provenance: { kind: "identity" } },
+      video: [{ streamId: streamId as typeof base.project.assets[number]["streams"][number]["streamId"], presentation: { enabled: true, blendMode: "normal", crop: { kind: "none" }, fit: "fill", layer, layout: { kind: "normalized", x: 0, y: 0, width: 1, height: 1 }, opacity: 1 } }],
+    });
+    boundShots.push({ shot: SpatialShotV1Schema.parse(shot), materialized: { ...materialized, frameRate: reduceSpatialFrameRate(materialized.frameRate) } });
+  }
+  const project = VideoProjectV1Schema.parse({ ...base.project, assets, placements });
+  const plan = ProjectEditPlanV1Schema.parse({ ...base.projectEditPlan, projectStructureSha256: hashProjectStructure(project) });
+  const revision = createProjectEditRevisionDocument(project, plan);
+  const revisionText = spatialProjectDocumentText(revision);
+  const artifactSha256 = sha256Hex(revisionText);
+  const renderPlan = compileProjectRenderPlan(project, plan, { frameRate: numericFrameRate, pixelWidth: output.pixelWidth, pixelHeight: output.pixelHeight, background: output.background });
+  const projection = SceneRenderProjectionV1Schema.parse({
+    kind: "slopcamera.scene-render-projection", schemaVersion: 1, source: head, policy, output, shots: boundShots,
+    legacyFrameRateAdapter: { kind: "numeric-ratio-for-planning-only", value: numericFrameRate, requiredEncoderArgument: spatialProjectionEncoderFrameRate(output.frameRate) },
+    derivedV1RevisionSha256: revision.revisionSha256,
+    derivedV1Revision: { bytes: new TextEncoder().encode(revisionText).byteLength, sha256: artifactSha256, path: projectEditRevisionPath(artifactSha256) },
+    compositionPlanSha256: renderPlan.planSha256,
+  });
+  return deepFreezeJson({ projection, projectionSha256: canonicalJsonSha256({ domain: "slopcamera.scene-render-projection/v1", projection }), revision, renderPlan });
+}