@hraness/slopcamera 3.2.4

package/apps/desktop/cli/studio-files.ts

@@ -0,0 +1,179 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, opendir, realpath } from "node:fs/promises";
+import { dirname, join, parse, relative, resolve, sep } from "node:path";
+import { canonicalJson } from "../../../src/code/canonical-json";
+import {
+  parseStudioSourceBundle, StudioPathSchema, studioOutputPath, studioSourceBundleSha256,
+  type StudioJob, type StudioOutputArtifact, type StudioSourceBundle,
+} from "../../../src/studio";
+import { createNodeBundleFileSystem } from "../core/storage";
+import { ensurePhysicalPrivateDirectoryWithin } from "./paths";
+
+export const studioBytesSha256 = (bytes: string | Uint8Array): string => createHash("sha256").update(bytes).digest("hex");
+export const studioJson = (value: unknown): string => `${canonicalJson(value)}\n`;
+
+export async function readStudioFileEdges(path: string, expectedBytes: number, edgeBytes = 256): Promise<{ readonly first: Buffer; readonly last: Buffer }> {
+  if (!Number.isInteger(edgeBytes) || edgeBytes < 1 || edgeBytes > 1_048_576) throw new Error("Invalid studio header bound.");
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.size !== BigInt(expectedBytes)) throw new Error("Studio output changed before header validation.");
+    const length = Math.min(edgeBytes, expectedBytes), first = Buffer.alloc(length), last = Buffer.alloc(length);
+    const a = await handle.read(first, 0, length, 0), b = await handle.read(last, 0, length, expectedBytes - length);
+    const after = await handle.stat({ bigint: true });
+    if (a.bytesRead !== length || b.bytesRead !== length || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs) throw new Error("Studio output changed during header validation.");
+    return { first, last };
+  } finally { await handle.close(); }
+}
+
+export async function readStudioBytes(path: string, expected: { readonly bytes: number; readonly sha256: string }, maximumBytes: number): Promise<Buffer> {
+  if (expected.bytes > maximumBytes) throw new Error("Studio binary exceeds its decode profile.");
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.size !== BigInt(expected.bytes)) throw new Error("Studio binary changed before decode.");
+    const bytes = Buffer.alloc(expected.bytes);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const result = await handle.read(bytes, offset, Math.min(256 * 1024, bytes.length - offset), offset);
+      if (result.bytesRead === 0) throw new Error("Studio binary ended during decode capture.");
+      offset += result.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs || studioBytesSha256(bytes) !== expected.sha256) throw new Error("Studio binary changed during decode capture.");
+    return bytes;
+  } finally { await handle.close(); }
+}
+
+export async function studioPhysicalRoot(path: string): Promise<string> {
+  const root = resolve(path), stat = await lstat(root);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("Studio root must be a physical directory.");
+  return await realpath(root);
+}
+
+/** The source root is selected explicitly; only named files are read. */
+export async function captureStudioSource(input: {
+  readonly sourceRoot: string; readonly engine: StudioSourceBundle["engine"];
+  readonly entrypoint: StudioSourceBundle["entrypoint"]; readonly files: readonly string[];
+}): Promise<StudioSourceBundle> {
+  if (input.files.length < 1 || input.files.length > 512) throw new Error("Studio sources require 1–512 explicit files.");
+  const root = await studioPhysicalRoot(input.sourceRoot), fs = createNodeBundleFileSystem(root);
+  const files = [];
+  let bytes = 0;
+  for (const path of input.files) {
+    StudioPathSchema.parse(path);
+    const integrity = await fs.inspectFile!(path, 4_294_967_296 - bytes);
+    bytes += integrity.bytes;
+    files.push({ path, ...integrity });
+  }
+  return parseStudioSourceBundle({ kind: "slopcamera.studio-source-bundle", schemaVersion: 1, engine: input.engine, entrypoint: input.entrypoint, files });
+}
+
+export async function verifyStudioSource(sourceRoot: string, bundle: StudioSourceBundle): Promise<void> {
+  const fs = createNodeBundleFileSystem(await studioPhysicalRoot(sourceRoot));
+  const inventory = await inventoryStudioFiles(sourceRoot, 512, 4_294_967_296);
+  if (inventory.length !== bundle.files.length || inventory.some(item => !bundle.files.some(file => file.path === item.path && file.bytes === item.bytes))) throw new Error("Retained studio source contains an undeclared or changed file.");
+  for (const file of bundle.files) {
+    const found = await fs.inspectFile!(file.path, file.bytes);
+    if (found.bytes !== file.bytes || found.sha256 !== file.sha256) throw new Error(`Studio source changed: ${file.path}`);
+  }
+}
+
+/** Reuse the storage layer's inode-pinned exact copy and no-replace publication across two explicit roots. */
+export async function copyStudioSource(sourceRoot: string, destinationRoot: string, bundle: StudioSourceBundle, fence: () => Promise<void>): Promise<void> {
+  const source = await studioPhysicalRoot(sourceRoot), destination = await studioPhysicalRoot(destinationRoot);
+  let ancestor = source;
+  while (relative(ancestor, destination) === ".." || relative(ancestor, destination).startsWith(`..${sep}`)) {
+    const parent = dirname(ancestor);
+    if (parent === ancestor) throw new Error("Studio source and destination do not share a filesystem root.");
+    ancestor = parent;
+  }
+  if (parse(source).root !== parse(destination).root) throw new Error("Studio copies require a shared filesystem root.");
+  const fs = createNodeBundleFileSystem(ancestor);
+  for (const file of bundle.files) {
+    await fs.copyFileNoReplace!(relative(ancestor, join(source, file.path)), relative(ancestor, join(destination, file.path)), file, fence);
+  }
+}
+
+export async function retainStudioSource(input: {
+  readonly studioRoot: string; readonly sourceRoot: string; readonly bundle: StudioSourceBundle; readonly fence: () => Promise<void>;
+}): Promise<{ readonly bundle: StudioSourceBundle; readonly bundleSha256: string; readonly sourceRoot: string }> {
+  const bundle = parseStudioSourceBundle(input.bundle), bundleSha256 = studioSourceBundleSha256(bundle);
+  const directory = await ensurePhysicalPrivateDirectoryWithin(input.studioRoot, `bundles/${bundleSha256}`);
+  const sourceRoot = await ensurePhysicalPrivateDirectoryWithin(directory, "source");
+  await copyStudioSource(input.sourceRoot, sourceRoot, bundle, input.fence);
+  const fs = createNodeBundleFileSystem(directory), text = studioJson(bundle);
+  const disposition = await fs.writeTextNoReplace!("bundle.json", text, input.fence);
+  if (disposition !== "created" && await fs.readText("bundle.json") !== text) throw new Error("Retained studio bundle conflicts with its digest.");
+  await verifyStudioSource(sourceRoot, bundle);
+  return { bundle, bundleSha256, sourceRoot };
+}
+
+export interface StudioFileInventory { readonly path: string; readonly bytes: number }
+
+/** Bounded traversal is restricted to the newly owned output/cache directory, never an asset source. */
+export async function inventoryStudioFiles(rootInput: string, maximumFiles: number, maximumBytes: number, mode: "settled" | "live" = "settled"): Promise<readonly StudioFileInventory[]> {
+  const root = await studioPhysicalRoot(rootInput), found: StudioFileInventory[] = [];
+  const rootIdentity = await lstat(root, { bigint: true });
+  if (!rootIdentity.isDirectory() || rootIdentity.isSymbolicLink()) throw new Error("Studio output root must remain a physical directory.");
+  const pending = [""], names = new Set<string>();
+  // Native caches atomically rename and remove temporary descendants. A live
+  // observation may omit an already removed entry; settled publication may not.
+  const disappeared = (error: unknown): boolean => mode === "live" && error instanceof Error && "code" in error && error.code === "ENOENT";
+  let bytes = 0, entries = 0;
+  while (pending.length > 0) {
+    const current = pending.pop()!;
+    let directory;
+    try { directory = await opendir(join(root, current)); }
+    catch (error) { if (current !== "" && disappeared(error)) continue; throw error; }
+    for await (const entry of directory) {
+      if (++entries > maximumFiles * 8 + 1024) throw new Error("Studio output directory-entry budget exceeded.");
+      const path = current === "" ? entry.name : `${current}/${entry.name}`;
+      StudioPathSchema.parse(path);
+      if (path.split("/").length > 32 || names.has(path.toLowerCase())) throw new Error("Studio output paths exceed depth or collide.");
+      names.add(path.toLowerCase());
+      let stat;
+      try { stat = await lstat(join(root, path)); }
+      catch (error) { if (disappeared(error)) continue; throw error; }
+      // APFS can return the just-unlinked inode with nlink=0 instead of ENOENT.
+      // Reobserve once; only disappearance or a valid replacement can pass.
+      if (mode === "live" && stat.isFile() && stat.nlink === 0) {
+        try { stat = await lstat(join(root, path)); }
+        catch (error) { if (disappeared(error)) continue; throw error; }
+      }
+      if (stat.isSymbolicLink()) throw new Error("Studio outputs cannot contain symlinks.");
+      if (stat.isDirectory()) pending.push(path);
+      else {
+        if (!stat.isFile() || stat.nlink !== 1 || !Number.isSafeInteger(stat.size)) throw new Error("Studio output must be a singly linked regular file.");
+        bytes += stat.size;
+        if (found.length >= maximumFiles || bytes > maximumBytes) throw new Error("Studio output budget exceeded.");
+        found.push({ path, bytes: stat.size });
+      }
+    }
+  }
+  // Disappearance of the owned root itself is always a failure, including when
+  // an open directory iterator could otherwise finish after its unlink.
+  if (await studioPhysicalRoot(rootInput) !== root) throw new Error("Studio output root changed during inventory.");
+  const after = await lstat(root, { bigint: true });
+  if (!after.isDirectory() || after.isSymbolicLink() || after.dev !== rootIdentity.dev || after.ino !== rootIdentity.ino) throw new Error("Studio output root changed during inventory.");
+  return found.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+
+export async function inspectStudioOutputs(root: string, job: StudioJob): Promise<readonly StudioOutputArtifact[]> {
+  const inventory = await inventoryStudioFiles(root, job.limits.maximumOutputFiles, job.limits.maximumOutputBytes);
+  const files = new Map<string, { readonly output: StudioJob["outputs"][number]; readonly frame?: number }>();
+  for (const output of job.outputs) {
+    if (output.kind === "file") files.set(output.path, { output });
+    else if (output.kind === "sequence") for (let frame = job.render!.startFrame; frame < job.render!.endFrameExclusive; frame++) files.set(studioOutputPath(output, frame), { output, frame });
+  }
+  const fs = createNodeBundleFileSystem(root), artifacts: StudioOutputArtifact[] = [];
+  for (const item of inventory) {
+    const match = files.get(item.path);
+    const output = match?.output ?? job.outputs.find(output => output.kind === "directory" && item.path.startsWith(`${output.path}/`));
+    if (output === undefined || item.bytes === 0) throw new Error(`Undeclared or empty studio output: ${item.path}`);
+    const integrity = await fs.inspectFile!(item.path, item.bytes);
+    artifacts.push({ outputId: output.id, path: item.path, ...integrity, role: output.role, format: output.format, ...(match?.frame === undefined ? {} : { frame: match.frame }) });
+  }
+  return artifacts;
+}

package/apps/desktop/cli/studio-output-validation.ts

@@ -0,0 +1,162 @@
+import { join } from "node:path";
+import sharp from "sharp";
+import { z } from "zod";
+import { STUDIO_LIMITS, type StudioJob, type StudioOutputArtifact } from "../../../src/studio";
+import type { ApplicationContext } from "../application/context";
+import { bindExactCapability } from "../application/capability-binding";
+import { readStudioBytes, readStudioFileEdges } from "./studio-files";
+import { inspectStudioExrHeader } from "./studio-exr";
+import type { StudioProcessPort } from "./studio-process";
+
+export interface StudioOutputValidation {
+  readonly outputId: string; readonly path: string;
+  readonly validation: "decoded-raster" | "decoded-video" | "decoded-audio" | "format-header" | "opaque-cache" | "inert-source";
+  readonly width?: number; readonly height?: number; readonly frameCount?: number;
+}
+
+const probeSchema = z.object({ streams: z.array(z.object({
+  codec_type: z.string(), codec_name: z.string().optional(), width: z.number().int().optional(), height: z.number().int().optional(),
+  pix_fmt: z.string().optional(), avg_frame_rate: z.string().optional(), nb_read_frames: z.string().optional(),
+  sample_rate: z.string().optional(), channels: z.number().int().optional(), time_base: z.string().max(32).optional(),
+})).max(32), format: z.object({ format_name: z.string().min(1).max(128) }), frames: z.array(z.object({
+  best_effort_timestamp: z.number().int().safe(), duration: z.number().int().safe().positive().optional(), pkt_duration: z.number().int().safe().positive().optional(),
+  width: z.number().int().positive(), height: z.number().int().positive(), pix_fmt: z.string().min(1).max(64),
+})).max(STUDIO_LIMITS.frames).optional() });
+
+const mediaFormats = {
+  mp4: { demuxer: "mov", names: ["mov", "mp4", "m4a", "3gp", "3g2", "mj2"] },
+  mov: { demuxer: "mov", names: ["mov", "mp4", "m4a", "3gp", "3g2", "mj2"] },
+  webm: { demuxer: "matroska", names: ["matroska", "webm"] },
+  wav: { demuxer: "wav", names: ["wav"] }, flac: { demuxer: "flac", names: ["flac"] }, mp3: { demuxer: "mp3", names: ["mp3"] },
+  exr: { demuxer: "exr_pipe", names: ["exr_pipe"] },
+} as const;
+type ProbedFormat = keyof typeof mediaFormats;
+// The portable contract can describe higher precision, but this verified video
+// delivery profile is RGB(A)8 only. Preserve uint16 PNG and float EXR masters;
+// 10/12/16-bit and floating video need separately qualified format profiles.
+const rgb8VideoPixels = new Set(["rgb24", "bgr24", "gbrp", "yuv420p", "yuv422p", "yuv444p", "yuvj420p", "yuvj422p", "yuvj444p"]);
+const rgba8VideoPixels = new Set(["rgba", "bgra", "argb", "abgr", "gbrap", "yuva420p", "yuva422p", "yuva444p"]);
+
+function mediaInputArguments(format: ProbedFormat): readonly string[] {
+  const { demuxer } = mediaFormats[format];
+  return ["-protocol_whitelist", "file", "-format_whitelist", demuxer, "-f", demuxer,
+    ...(demuxer === "mov" ? ["-enable_drefs", "0", "-use_absolute_path", "0"] : []),
+    "-max_pixels", String(STUDIO_LIMITS.pixels), "-threads", "1"];
+}
+
+/** Each rational timestamp may be quantized by less than one container tick; drift cannot accumulate. */
+function validateVideoClock(probe: z.infer<typeof probeSchema>, render: NonNullable<StudioJob["render"]>): void {
+  const stream = probe.streams[0]!, frames = probe.frames;
+  const base = /^([1-9]\d{0,8})\/([1-9]\d{0,8})$/u.exec(stream.time_base ?? "");
+  const count = render.endFrameExclusive - render.startFrame;
+  if (base === null || frames?.length !== count) throw new Error("Studio video requires every decoded timestamp and a bounded exact time base.");
+  const denominator = BigInt(render.frameRate.numerator) * BigInt(base[1]!);
+  const step = BigInt(render.frameRate.denominator) * BigInt(base[2]!);
+  // A clock coarser than a frame cannot establish every individual frame boundary.
+  if (step < denominator) throw new Error("Studio video time base cannot represent its declared frame cadence.");
+  const matches = (ticks: number, index: number, quantizedValues = 1n) => {
+    const delta = BigInt(ticks) * denominator - BigInt(index) * step;
+    return delta > -denominator * quantizedValues && delta < denominator * quantizedValues;
+  };
+  for (const [index, frame] of frames.entries()) {
+    if (index === 0 && frame.best_effort_timestamp !== 0 || index > 0 && frame.best_effort_timestamp <= frames[index - 1]!.best_effort_timestamp
+      || !matches(frame.best_effort_timestamp, index) || frame.width !== render.width || frame.height !== render.height || frame.pix_fmt !== stream.pix_fmt) {
+      throw new Error("Studio decoded frames differ from their zero-based rational clock or fixed pixel profile.");
+    }
+    const duration = frame.duration ?? frame.pkt_duration;
+    if (frame.duration !== undefined && frame.pkt_duration !== undefined && frame.duration !== frame.pkt_duration) throw new Error("Studio decoded frame durations disagree.");
+    // Matroska quantizes nominal duration independently of PTS. Their sum has two
+    // bounded quantization errors, while each PTS and duration must still match on its own.
+    if (duration !== undefined && (!matches(duration, 1) || !Number.isSafeInteger(frame.best_effort_timestamp + duration) || !matches(frame.best_effort_timestamp + duration, index + 1, 2n))) {
+      throw new Error("Studio decoded frame duration differs from its rational end boundary.");
+    }
+    if (index === count - 1 && duration === undefined) throw new Error("Studio video requires the final decoded frame duration to prove end coverage.");
+  }
+}
+
+/** Observed pixel/stream properties are checked; native units and cache meaning remain declared source semantics. */
+export async function validateStudioOutputMedia(input: {
+  readonly application: ApplicationContext; readonly process: StudioProcessPort; readonly root: string;
+  readonly job: StudioJob; readonly outputs: readonly StudioOutputArtifact[]; readonly signal: AbortSignal;
+  readonly cwd: string; readonly env: Readonly<Record<string, string>>; readonly inheritedFileDescriptors?: readonly number[];
+  readonly fence: () => Promise<void>;
+}): Promise<readonly StudioOutputValidation[]> {
+  const evidence: StudioOutputValidation[] = [];
+  for (const artifact of input.outputs) {
+    if (input.signal.aborted) throw new Error("Studio output validation cancelled.");
+    await input.fence();
+    const output = input.job.outputs.find(output => output.id === artifact.outputId)!;
+    const path = join(input.root, artifact.path);
+    if (artifact.format === "png") {
+      const bytes = await readStudioBytes(path, artifact, 272 * 1024 * 1024);
+      const metadata = await sharp(bytes, { failOn: "error", limitInputPixels: 33_554_432, animated: true }).metadata();
+      const interpretation = output.interpretation;
+      if (interpretation.kind !== "raster" || metadata.format !== "png" || (metadata.pages ?? 1) !== 1
+        || metadata.width !== input.job.render?.width || metadata.height !== input.job.render.height
+        || metadata.channels !== interpretation.channels.length
+        || Boolean(metadata.hasAlpha) !== ["straight", "premultiplied"].includes(interpretation.alpha)
+        || (interpretation.dataType === "uint16" ? metadata.depth !== "ushort" : metadata.depth !== "uchar")) throw new Error(`Studio PNG profile differs from its declaration: ${artifact.path}`);
+      await sharp(bytes, { failOn: "error", limitInputPixels: 33_554_432 }).raw().toBuffer();
+      evidence.push({ outputId: output.id, path: artifact.path, validation: "decoded-raster", width: metadata.width, height: metadata.height, frameCount: 1 });
+    } else if (["mp4", "mov", "webm", "wav", "flac", "mp3", "exr"].includes(artifact.format)) {
+      if (artifact.format === "exr") {
+        const header = inspectStudioExrHeader((await readStudioFileEdges(path, artifact.bytes, 1_048_576)).first);
+        const interpretation = output.interpretation;
+        if (interpretation.kind !== "raster" || header.width !== input.job.render?.width || header.height !== input.job.render.height
+          || header.channels.some(channel => channel.dataType !== interpretation.dataType)
+          || header.channels.map(channel => channel.name).sort().join("\0") !== [...interpretation.channels].sort().join("\0")
+          || header.channels.some(channel => channel.name === "A") !== ["straight", "premultiplied"].includes(interpretation.alpha)) throw new Error("Studio EXR channel/type/alpha profile differs from its declaration.");
+      }
+      const format = artifact.format as ProbedFormat, video = ["mp4", "mov", "webm"].includes(format);
+      const capability = await bindExactCapability(await input.application.capability("ffprobe"));
+      const entries = "stream=codec_type,codec_name,width,height,pix_fmt,avg_frame_rate,nb_read_frames,sample_rate,channels,time_base:format=format_name"
+        + (video ? ":frame=best_effort_timestamp,duration,pkt_duration,width,height,pix_fmt:frame_side_data=" : "");
+      const result = await input.process.run([capability.executablePath, "-v", "error", ...mediaInputArguments(format), "-count_frames", "-show_streams", "-show_format",
+        ...(video ? ["-show_frames"] : []), "-show_entries", entries, "-of", "json=compact=1", path], {
+        cwd: input.cwd, env: input.env, timeoutMs: Math.min(input.job.limits.timeoutSeconds * 1000, 300_000), maximumLogBytes: 4_194_304,
+        signal: input.signal, ...(input.inheritedFileDescriptors === undefined ? {} : { inheritedFileDescriptors: input.inheritedFileDescriptors }),
+      });
+      if (result.exitCode !== 0 || result.failure !== undefined || result.custody !== "closed" || result.stderr.trim() !== "") throw new Error(`Studio output does not fully decode: ${artifact.path}`);
+      const probe = probeSchema.parse(JSON.parse(result.stdout) as unknown);
+      const names = probe.format.format_name.split(","), allowed: readonly string[] = mediaFormats[format].names;
+      if (!names.includes(mediaFormats[format].demuxer) || names.some(name => !allowed.includes(name))) throw new Error("Studio media container differs from its declared format family.");
+      const interpretation = output.interpretation;
+      if (probe.streams.length !== 1) throw new Error("Studio outputs require exactly one declared media stream.");
+      const stream = probe.streams[0]!;
+      if (interpretation.kind === "audio") {
+        if (stream.codec_type !== "audio" || stream.sample_rate !== String(interpretation.sampleRate) || stream.channels !== interpretation.channels || !(Number(stream.nb_read_frames) > 0)) throw new Error("Studio audio differs from its declared profile.");
+        evidence.push({ outputId: output.id, path: artifact.path, validation: "decoded-audio" });
+      } else {
+        const render = input.job.render;
+        if (interpretation.kind !== "raster" || render === undefined || stream.codec_type !== "video" || stream.width !== render.width || stream.height !== render.height) throw new Error("Studio raster differs from its dimensions or type.");
+        const frameCount = artifact.format === "exr" ? 1 : render.endFrameExclusive - render.startFrame;
+        if (stream.nb_read_frames !== String(frameCount)) throw new Error("Studio decoded frame count differs from its exact interval.");
+        if (artifact.format !== "exr") {
+          const rate = /^([1-9]\d{0,8})\/([1-9]\d{0,8})$/u.exec(stream.avg_frame_rate ?? "");
+          if (rate === null || BigInt(rate[1]!) * BigInt(render.frameRate.denominator) !== BigInt(rate[2]!) * BigInt(render.frameRate.numerator)) throw new Error("Studio video cadence differs from its exact rational clock.");
+          const pixels = stream.pix_fmt ?? "", alpha = rgba8VideoPixels.has(pixels);
+          if (!rgb8VideoPixels.has(pixels) && !alpha || interpretation.dataType !== "uint8"
+            || interpretation.channels.join(",") !== (alpha ? "R,G,B,A" : "R,G,B")) {
+            throw new Error("Studio video requires a verified 8-bit RGB/RGBA delivery profile; retain higher precision in PNG or EXR masters.");
+          }
+          if (alpha !== ["straight", "premultiplied"].includes(interpretation.alpha)) throw new Error("Studio video alpha differs from its declaration.");
+          validateVideoClock(probe, render);
+        }
+        evidence.push({ outputId: output.id, path: artifact.path, validation: artifact.format === "exr" ? "decoded-raster" : "decoded-video", width: render.width, height: render.height, frameCount });
+      }
+    } else if (artifact.format === "cache") evidence.push({ outputId: output.id, path: artifact.path, validation: "opaque-cache" });
+    else if (artifact.format === "py") evidence.push({ outputId: output.id, path: artifact.path, validation: "inert-source" });
+    else {
+      // Native formats are retained as native authority. This checks framing, not a universal semantic round trip.
+      const { first: bytes, last } = await readStudioFileEdges(path, artifact.bytes);
+      const valid = artifact.format === "glb" ? bytes.length >= 20 && bytes.toString("ascii", 0, 4) === "glTF" && bytes.readUInt32LE(4) === 2 && bytes.readUInt32LE(8) === artifact.bytes
+        : artifact.format === "blend" ? bytes.toString("ascii", 0, 7) === "BLENDER" || bytes.subarray(0, 4).equals(Buffer.from([0x28, 0xb5, 0x2f, 0xfd]))
+          : artifact.format === "step" ? bytes.toString("ascii").includes("ISO-10303-21;") && last.toString("ascii").includes("END-ISO-10303-21;")
+            : artifact.format === "usdc" ? bytes.toString("ascii", 0, 8) === "PXR-USDC" : artifact.format === "usda" ? bytes.toString("ascii", 0, 9) === "#usda 1.0"
+              : artifact.format === "usd" && (bytes.toString("ascii", 0, 8) === "PXR-USDC" || bytes.toString("ascii", 0, 9) === "#usda 1.0");
+      if (!valid) throw new Error(`Studio native output has invalid format framing: ${artifact.path}`);
+      evidence.push({ outputId: output.id, path: artifact.path, validation: "format-header" });
+    }
+  }
+  return evidence;
+}

package/apps/desktop/cli/studio-process.ts

@@ -0,0 +1,145 @@
+import { spawn } from "node:child_process";
+import { dirname, join } from "node:path";
+
+/** Trusted native code is not sandboxed. This port supervises its ordinary POSIX process group. */
+export interface StudioProcessResult {
+  readonly exitCode: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly custody: "closed" | "unknown";
+  readonly failure?: "cancelled" | "timeout" | "output-limit" | "spawn" | "descendants";
+}
+
+export interface StudioProcessOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string>>;
+  readonly timeoutMs: number;
+  readonly maximumLogBytes: number;
+  readonly signal?: AbortSignal;
+  readonly inheritedFileDescriptors?: readonly number[];
+  readonly onSpawn?: (pid: number) => Promise<void>;
+  readonly assertBudget?: () => Promise<void>;
+}
+
+export interface StudioProcessPort {
+  run(argv: readonly [string, ...string[]], options: StudioProcessOptions): Promise<StudioProcessResult>;
+}
+
+export function studioChildEnvironment(executable: string, workingRoot: string, threads: number): Record<string, string> {
+  if (!Number.isInteger(threads) || threads < 1 || threads > 1024) throw new Error("Invalid native worker budget.");
+  return {
+    PATH: `${dirname(executable)}:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin`,
+    HOME: join(workingRoot, "home"), TMPDIR: join(workingRoot, "tmp"),
+    LANG: "en_US.UTF-8", LC_ALL: "en_US.UTF-8", TZ: "UTC",
+    PYTHONNOUSERSITE: "1", PYTHONDONTWRITEBYTECODE: "1",
+    OMP_NUM_THREADS: String(threads), OPENBLAS_NUM_THREADS: String(threads),
+    MKL_NUM_THREADS: String(threads), NUMEXPR_NUM_THREADS: String(threads),
+    BLENDER_USER_RESOURCES: join(workingRoot, "blender-user"),
+  };
+}
+
+function groupState(pid: number): "present" | "absent" | "unknown" {
+  try { process.kill(-pid, 0); return "present"; }
+  catch (error) {
+    return error instanceof Error && "code" in error && error.code === "ESRCH" ? "absent" : "unknown";
+  }
+}
+
+/** Detached sessions created by authored code are unsupported; process groups are custody, not confinement. */
+export class NativeStudioProcess implements StudioProcessPort {
+  async run(argv: readonly [string, ...string[]], options: StudioProcessOptions): Promise<StudioProcessResult> {
+    if (process.platform !== "darwin" && process.platform !== "linux") throw new Error("Native studio execution currently requires POSIX process-group supervision.");
+    if (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1 || options.timeoutMs > 21_600_000
+      || !Number.isSafeInteger(options.maximumLogBytes) || options.maximumLogBytes < 1 || options.maximumLogBytes > 4_194_304) throw new Error("Invalid native process limits.");
+    if (options.signal?.aborted) return { exitCode: null, stdout: "", stderr: "", custody: "closed", failure: "cancelled" };
+    const child = spawn(argv[0], [...argv.slice(1)], {
+      cwd: options.cwd, env: { ...options.env }, detached: true,
+      stdio: ["ignore", "pipe", "pipe", ...(options.inheritedFileDescriptors ?? [])],
+    });
+    let failure: StudioProcessResult["failure"];
+    let total = 0;
+    const stdout: Buffer[] = [], stderr: Buffer[] = [];
+    let spawned = false;
+    let escalation: ReturnType<typeof setTimeout> | undefined;
+    let custodyDeadline: ReturnType<typeof setTimeout> | undefined;
+    let budgetTimer: ReturnType<typeof setInterval> | undefined;
+    let budgetCheck: Promise<void> | undefined;
+    let spawnCheckpoint: Promise<void> | undefined;
+    let leaderExited = false;
+    let resolveExit: (code: number | null) => void = () => {};
+    const signalGroup = (signal: NodeJS.Signals) => {
+      if (!spawned || child.pid === undefined) return;
+      try { process.kill(-child.pid, signal); }
+      catch (error) { if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) failure ??= "descendants"; }
+    };
+    const stop = (reason: NonNullable<StudioProcessResult["failure"]>) => {
+      failure ??= reason;
+      signalGroup("SIGTERM");
+      escalation ??= setTimeout(() => signalGroup("SIGKILL"), 500);
+      custodyDeadline ??= setTimeout(() => resolveExit(null), 5_500);
+    };
+    const capture = (target: Buffer[], chunk: Buffer) => {
+      const remaining = Math.max(0, options.maximumLogBytes - total);
+      if (remaining > 0) target.push(Buffer.from(chunk.subarray(0, remaining)));
+      total += chunk.length;
+      if (total > options.maximumLogBytes) stop("output-limit");
+    };
+    child.stdout?.on("data", (chunk: Buffer) => capture(stdout, chunk));
+    child.stderr?.on("data", (chunk: Buffer) => capture(stderr, chunk));
+    child.stdout?.on("error", () => stop("spawn"));
+    child.stderr?.on("error", () => stop("spawn"));
+    const abort = () => stop("cancelled");
+    const exit = new Promise<number | null>(resolve => {
+      resolveExit = resolve;
+      child.once("error", () => { failure ??= "spawn"; resolve(null); });
+      child.once("exit", code => { leaderExited = true; resolve(code); });
+    });
+    const closed = new Promise<void>(resolve => child.once("close", () => resolve()));
+    child.once("spawn", () => {
+      spawned = true;
+      if (options.signal?.aborted) stop("cancelled");
+      spawnCheckpoint = Promise.resolve().then(() => options.onSpawn?.(child.pid!)).catch(() => stop("spawn"));
+    });
+    options.signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => stop("timeout"), options.timeoutMs);
+    if (options.assertBudget !== undefined) budgetTimer = setInterval(() => {
+      if (budgetCheck !== undefined) return;
+      budgetCheck = options.assertBudget!().catch(() => { stop("output-limit"); }).finally(() => { budgetCheck = undefined; });
+    }, 500);
+    try {
+      const exitCode = await exit;
+      if (budgetTimer !== undefined) { clearInterval(budgetTimer); budgetTimer = undefined; }
+      let callbacksSettled = false, callbackTimer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        callbacksSettled = await Promise.race([
+          Promise.all([spawnCheckpoint, budgetCheck]).then(() => true),
+          new Promise<false>(resolve => { callbackTimer = setTimeout(() => resolve(false), 5_000); }),
+        ]);
+        if (!callbacksSettled) stop("descendants");
+      } finally { if (callbackTimer !== undefined) clearTimeout(callbackTimer); }
+      if (child.pid !== undefined && spawned && groupState(child.pid) !== "absent") {
+        stop("descendants");
+        const deadline = performance.now() + 5_000;
+        while (groupState(child.pid) === "present" && performance.now() < deadline) {
+          await new Promise(resolve => setTimeout(resolve, 50));
+        }
+      }
+      let custody: StudioProcessResult["custody"] = callbacksSettled && (!spawned || (child.pid !== undefined && leaderExited && groupState(child.pid) === "absent")) ? "closed" : "unknown";
+      if (custody === "closed") {
+        let drainTimer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          const drained = await Promise.race([closed.then(() => true), new Promise<false>(resolve => { drainTimer = setTimeout(() => resolve(false), 5_000); })]);
+          if (!drained) { custody = "unknown"; failure ??= "descendants"; }
+        } finally { if (drainTimer !== undefined) clearTimeout(drainTimer); }
+      }
+      if (custody !== "closed") { child.stdout?.destroy(); child.stderr?.destroy(); }
+      return { exitCode, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), custody, ...(failure === undefined ? {} : { failure }) };
+    } finally {
+      clearTimeout(timer);
+      if (escalation !== undefined) clearTimeout(escalation);
+      if (custodyDeadline !== undefined) clearTimeout(custodyDeadline);
+      if (budgetTimer !== undefined) clearInterval(budgetTimer);
+      options.signal?.removeEventListener("abort", abort);
+    }
+  }
+}

package/apps/desktop/cli/studio-runtime.ts

@@ -0,0 +1,77 @@
+import { constants } from "node:fs";
+import { access, lstat, realpath } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { parseStudioRuntimeIdentity, StudioCapabilityNameSchema, type StudioSourceBundle, type StudioRuntimeIdentity } from "../../../src/studio";
+import { createNodeBundleFileSystem } from "../core/storage";
+import blenderDriver from "../studio/drivers/blender_driver.py" with { type: "text" };
+import cadqueryDriver from "../studio/drivers/cadquery_driver.py" with { type: "text" };
+import manimDriver from "../studio/education/driver.py" with { type: "text" };
+import { ensurePhysicalPrivateDirectoryWithin } from "./paths";
+import { studioBytesSha256, studioJson } from "./studio-files";
+import { studioChildEnvironment, type StudioProcessPort } from "./studio-process";
+
+export interface StudioRuntimeSelection { readonly blender?: string; readonly python?: string; readonly threads: number }
+export interface BoundStudioRuntime {
+  readonly identity: StudioRuntimeIdentity; readonly executable: string; readonly driver: string;
+  readonly environment: Readonly<Record<string, string>>; readonly workingRoot: string; readonly threads: number;
+}
+const drivers = { blender: blenderDriver, cadquery: cadqueryDriver, manim: manimDriver } as const;
+const probeSchema = z.strictObject({
+  name: z.string().min(1).max(128), version: z.string().min(1).max(512),
+  packages: z.record(z.string().min(1).max(128), z.string().max(512)).refine(value => Object.keys(value).length <= 2048),
+  capabilities: z.array(StudioCapabilityNameSchema).max(12),
+});
+
+/** Engine commands are fixed. The host selects an installed runtime; serialized jobs never carry argv. */
+export function studioDriverArgv(runtime: Pick<BoundStudioRuntime, "executable" | "driver" | "threads">, engine: StudioSourceBundle["engine"], action: { readonly probe: true } | { readonly request: string }): readonly [string, ...string[]] {
+  const tail = "probe" in action ? ["--probe"] : ["--request", action.request];
+  return engine === "blender"
+    ? [runtime.executable, "--factory-startup", "--background", "--disable-autoexec", "--python-exit-code", "23", "--threads", String(runtime.threads), "--python", runtime.driver, "--", ...tail]
+    : [runtime.executable, runtime.driver, ...tail];
+}
+
+async function executableIdentity(path: string): Promise<{ readonly executable: string; readonly sha256: string }> {
+  // Preserve the selected venv symlink in argv: resolving it changes Python's environment.
+  const executable = resolve(path), physical = await realpath(executable), stat = await lstat(physical);
+  if (!stat.isFile() || stat.size > 1024 * 1024 * 1024) throw new Error("Studio runtime must be a bounded installed executable.");
+  await access(executable, constants.X_OK);
+  const fs = createNodeBundleFileSystem(dirname(physical));
+  return { executable, sha256: (await fs.inspectFile!(physical.slice(dirname(physical).length + 1), stat.size)).sha256 };
+}
+
+export async function probeStudioRuntime(input: {
+  readonly engine: StudioSourceBundle["engine"]; readonly selection: StudioRuntimeSelection; readonly workingRoot: string;
+  readonly process: StudioProcessPort; readonly signal: AbortSignal; readonly fence: () => Promise<void>;
+  readonly inheritedFileDescriptors?: readonly number[];
+}): Promise<BoundStudioRuntime> {
+  const selected = input.engine === "blender" ? input.selection.blender : input.selection.python;
+  if (selected === undefined) throw new Error(input.engine === "blender" ? "Select an installed Blender runtime with --blender-bin." : "Select an installed Python environment with --python.");
+  const executable = await executableIdentity(selected), text = drivers[input.engine], driverSha256 = studioBytesSha256(text);
+  for (const path of ["home", "tmp", "blender-user", "driver"]) await ensurePhysicalPrivateDirectoryWithin(input.workingRoot, path);
+  const fs = createNodeBundleFileSystem(input.workingRoot), driverPath = `driver/${input.engine}-${driverSha256}.py`;
+  const disposition = await fs.writeTextNoReplace!(driverPath, text, input.fence);
+  if (disposition !== "created" && await fs.readText(driverPath) !== text) throw new Error("Fixed studio driver bytes changed.");
+  const environment = studioChildEnvironment(executable.executable, input.workingRoot, input.selection.threads);
+  const bound = { executable: executable.executable, driver: join(input.workingRoot, driverPath), environment, workingRoot: input.workingRoot, threads: input.selection.threads };
+  await input.fence();
+  const result = await input.process.run(studioDriverArgv(bound, input.engine, { probe: true }), {
+    cwd: input.workingRoot, env: environment, timeoutMs: 120_000, maximumLogBytes: 1_048_576, signal: input.signal,
+    ...(input.inheritedFileDescriptors === undefined ? {} : { inheritedFileDescriptors: input.inheritedFileDescriptors }),
+  });
+  if (result.custody !== "closed" || result.failure !== undefined || result.exitCode !== 0) throw new Error("Fixed native runtime probe did not finish with closed process custody.");
+  const lines = result.stdout.split(/\r?\n/u).filter(line => line.startsWith("SLOPCAMERA_STUDIO_PROBE="));
+  if (lines.length !== 1) throw new Error("Native runtime probe must emit one bounded identity document.");
+  const probe = probeSchema.parse(JSON.parse(lines[0]!.slice("SLOPCAMERA_STUDIO_PROBE=".length)) as unknown);
+  if (new Set(probe.capabilities).size !== probe.capabilities.length) throw new Error("Native runtime probe repeats a capability.");
+  await input.fence();
+  const after = await executableIdentity(selected);
+  if (executable.sha256 !== after.sha256) throw new Error("Studio executable changed during probing.");
+  const identity = parseStudioRuntimeIdentity({
+    kind: "slopcamera.studio-runtime", schemaVersion: 1, engine: input.engine,
+    tool: { name: probe.name, version: probe.version, executableSha256: executable.sha256 }, driverSha256,
+    environment: { fingerprintSha256: studioBytesSha256(studioJson({ platform: process.platform, architecture: process.arch, packages: probe.packages, threads: input.selection.threads })), evidence: "observed-package-environment", hermetic: false },
+    capabilities: probe.capabilities.map(name => ({ name, support: "available", evidence: "probe" })),
+  });
+  return { ...bound, identity };
+}