@hraness/slopcamera 3.2.4

package/src/spatial-scene/patch.ts

@@ -0,0 +1,131 @@
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialScenePatchV1Schema, type SpatialEntity, type SpatialSceneV1 } from "./contracts.js"
+import { applySpatialEntityOverride } from "./evaluate.js"
+import { parseSpatialScene, parseSpatialValue, SpatialSceneError, spatialAssetClosureDigests, spatialValueSha256 } from "./identity.js"
+
+export interface SpatialSceneDiffEntry {
+  readonly kind: "added" | "removed" | "changed"
+  readonly collection: "entities" | "cameras" | "animations" | "generators" | "overrides" | "assets"
+  readonly id: string
+  readonly properties: readonly string[]
+}
+export interface SpatialScenePatchResult {
+  readonly scene: SpatialSceneV1
+  readonly sceneSha256: string
+  readonly diff: readonly SpatialSceneDiffEntry[]
+}
+
+function diffCollection<T extends object>(collection: SpatialSceneDiffEntry["collection"], before: readonly T[], after: readonly T[], identify: (item: T) => string): SpatialSceneDiffEntry[] {
+  const old = new Map(before.map(item => [identify(item), item]))
+  const current = new Map(after.map(item => [identify(item), item]))
+  const result: SpatialSceneDiffEntry[] = []
+  for (const id of [...new Set([...old.keys(), ...current.keys()])].sort()) {
+    const a = old.get(id), b = current.get(id)
+    if (a === undefined || b === undefined) {
+      result.push({ kind: a === undefined ? "added" : "removed", collection, id, properties: Object.keys(a ?? b!).sort() })
+    } else {
+      const aRecord = a as Record<string, unknown>, bRecord = b as Record<string, unknown>
+      const properties = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort().filter(key =>
+        spatialValueSha256(Object.hasOwn(a, key) ? { value: aRecord[key] } : {}) !== spatialValueSha256(Object.hasOwn(b, key) ? { value: bRecord[key] } : {}))
+      if (properties.length) result.push({ kind: "changed", collection, id, properties })
+    }
+  }
+  return result
+}
+
+/** Atomic in-memory transaction. Final closure is checked once, before publishing any result. */
+export function applySpatialScenePatch(sceneInput: unknown, patchInput: unknown): SpatialScenePatchResult {
+  const original = parseSpatialScene(sceneInput)
+  const patch = parseSpatialValue(SpatialScenePatchV1Schema, patchInput, "scene patch")
+  if (patch.expectedSceneSha256 !== spatialValueSha256(original)) throw new SpatialSceneError("conflict", "Scene revision changed; inspect and rebase the patch.", "expectedSceneSha256")
+  const entities = new Map(original.entities.map(entity => [entity.entityId, entity]))
+  const assets = new Map(original.assets.map(asset => [asset.assetId, asset]))
+  const addressedGeometry = new Set<string>(), replacedGenerators = new Set<string>()
+  const cameras = new Map(original.cameras.map(camera => [camera.cameraId, camera]))
+  const animations = new Map(original.animations.map(channel => [channel.channelId, channel]))
+  const generators = new Map(original.generators.map(generator => [generator.generatorId, generator]))
+  const overrides = new Map(original.overrides.map(override => [`${override.entityId}:${override.property}`, override]))
+  function authored(id: string): SpatialEntity {
+    const entity = entities.get(id)
+    if (!entity) throw new SpatialSceneError("not-found", `Entity ${id} does not exist.`, "operations")
+    if (entity.origin.kind !== "authored") throw new SpatialSceneError("conflict", "Generated entities can be edited only through declared overrides or retained output replacement.", "operations")
+    return entity
+  }
+  for (const operation of patch.operations) {
+    switch (operation.kind) {
+      case "add-asset":
+        if (assets.has(operation.asset.assetId)) throw new SpatialSceneError("conflict", `Asset ${operation.asset.assetId} already exists.`)
+        assets.set(operation.asset.assetId, operation.asset)
+        break
+      case "replace-asset":
+        if (!assets.has(operation.asset.assetId)) throw new SpatialSceneError("not-found", `Asset ${operation.asset.assetId} does not exist.`)
+        assets.set(operation.asset.assetId, operation.asset)
+        break
+      case "set-mesh-geometry": {
+        const entity = authored(operation.entityId)
+        if (entity.kind !== "mesh") throw new SpatialSceneError("conflict", "Geometry replacement requires an authored mesh wrapper.")
+        entities.set(operation.entityId, { ...entity, geometry: operation.geometry })
+        addressedGeometry.add(operation.entityId)
+        break
+      }
+      case "rename-entity": entities.set(operation.entityId, { ...authored(operation.entityId), name: operation.name }); break
+      case "reparent-entity": entities.set(operation.entityId, { ...authored(operation.entityId), parentId: operation.parentId }); break
+      case "set-transform": entities.set(operation.entityId, { ...authored(operation.entityId), transform: operation.transform }); break
+      case "set-color": entities.set(operation.entityId, applySpatialEntityOverride(authored(operation.entityId), { entityId: operation.entityId, property: "color", value: operation.color })); break
+      case "set-opacity": entities.set(operation.entityId, applySpatialEntityOverride(authored(operation.entityId), { entityId: operation.entityId, property: "opacity", value: operation.opacity })); break
+      case "set-camera": cameras.set(operation.camera.cameraId, operation.camera); break
+      case "set-channel": animations.set(operation.channel.channelId, operation.channel); break
+      case "remove-channel":
+        if (!animations.delete(operation.channelId)) throw new SpatialSceneError("not-found", `Channel ${operation.channelId} does not exist.`)
+        break
+      case "add-entity":
+        if (entities.has(operation.entity.entityId)) throw new SpatialSceneError("conflict", `Entity ${operation.entity.entityId} already exists.`)
+        if (operation.entity.origin.kind !== "authored") throw new SpatialSceneError("conflict", "Add generated entities through retained generator output replacement.")
+        entities.set(operation.entity.entityId, operation.entity)
+        if (operation.entity.kind === "mesh") addressedGeometry.add(operation.entity.entityId)
+        break
+      case "remove-entity": authored(operation.entityId); entities.delete(operation.entityId); break
+      case "set-override": overrides.set(`${operation.override.entityId}:${operation.override.property}`, operation.override); break
+      case "remove-override":
+        if (!overrides.delete(`${operation.entityId}:${operation.property}`)) throw new SpatialSceneError("not-found", "Override does not exist.")
+        break
+      case "replace-generator-output": {
+        const generatorId = operation.generator.generatorId
+        replacedGenerators.add(generatorId)
+        for (const entity of entities.values()) if (entity.origin.kind === "generated" && entity.origin.generatorId === generatorId) entities.delete(entity.entityId)
+        for (const entity of operation.entities) {
+          if (entity.origin.kind !== "generated" || entity.origin.generatorId !== generatorId) throw new SpatialSceneError("conflict", "Generator replacement must contain only its own retained output.")
+          if (entities.has(entity.entityId)) throw new SpatialSceneError("conflict", `Generator output collides with ${entity.entityId}.`)
+          entities.set(entity.entityId, entity)
+        }
+        generators.set(generatorId, operation.generator)
+        break
+      }
+    }
+  }
+  const scene = parseSpatialScene({ ...original, assets: [...assets.values()], entities: [...entities.values()], cameras: [...cameras.values()], animations: [...animations.values()], generators: [...generators.values()], overrides: [...overrides.values()] })
+  const beforeAssets = new Map(original.assets.map(asset => [asset.assetId, asset]))
+  const oldClosure = spatialAssetClosureDigests(original.assets), newClosure = spatialAssetClosureDigests(scene.assets)
+  for (const entity of scene.entities) {
+    const assetId = entity.kind === "mesh" && entity.geometry.kind === "asset" ? entity.geometry.assetId
+      : entity.kind === "text" ? entity.fontAssetId : "assetId" in entity ? entity.assetId : undefined
+    if (assetId === undefined) continue
+    if (entity.origin.kind === "generated" && oldClosure[assetId] !== undefined && oldClosure[assetId] !== newClosure[assetId] && !replacedGenerators.has(entity.origin.generatorId)) {
+      throw new SpatialSceneError("conflict", "Changing a generated part's asset closure requires explicit retained generator output replacement.")
+    }
+    if (entity.kind === "mesh" && entity.geometry.kind === "asset" && (entity.geometry.nodeIndex !== undefined || entity.geometry.clip !== undefined)
+      && beforeAssets.has(assetId) && beforeAssets.get(assetId)!.payload.sha256 !== assets.get(assetId)!.payload.sha256
+      && !addressedGeometry.has(entity.entityId) && !(entity.origin.kind === "generated" && replacedGenerators.has(entity.origin.generatorId))) {
+      throw new SpatialSceneError("conflict", "Replacing addressed GLB bytes requires explicit set-mesh-geometry with the new local node/clip addresses; internal correspondence is not inferred.")
+    }
+  }
+  const diff = [
+    ...diffCollection("assets", original.assets, scene.assets, asset => asset.assetId),
+    ...diffCollection("entities", original.entities, scene.entities, entity => entity.entityId),
+    ...diffCollection("cameras", original.cameras, scene.cameras, camera => camera.cameraId),
+    ...diffCollection("animations", original.animations, scene.animations, channel => channel.channelId),
+    ...diffCollection("generators", original.generators, scene.generators, generator => generator.generatorId),
+    ...diffCollection("overrides", original.overrides, scene.overrides, override => `${override.entityId}:${override.property}`),
+  ]
+  return deepFreezeJson({ scene, sceneSha256: spatialValueSha256(scene), diff })
+}

package/src/spatial-scene/time.ts

@@ -0,0 +1,53 @@
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialFrameRateSchema, SpatialTimeUsSchema, type SpatialFrameRate } from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError } from "./identity.js"
+
+/** Decimal strings retain exact rational values across JSON and SDK boundaries. */
+export interface SpatialRational { readonly numerator: string; readonly denominator: string }
+export interface SpatialFrameSample { readonly frameIndex: number; readonly timeUs: number; readonly exactTimeUs: SpatialRational }
+
+function gcd(a: bigint, b: bigint): bigint {
+  while (b !== 0n) { const remainder = a % b; a = b; b = remainder }
+  return a
+}
+function rational(numerator: bigint, denominator: bigint): SpatialRational {
+  const divisor = gcd(numerator, denominator)
+  return Object.freeze({ numerator: String(numerator / divisor), denominator: String(denominator / divisor) })
+}
+function integer(input: number, name: string): bigint {
+  if (!Number.isSafeInteger(input) || input < 0) throw new SpatialSceneError("invalid-data", `${name} must be a nonnegative safe integer.`)
+  return BigInt(input)
+}
+function duration(input: number): bigint {
+  const value = parseSpatialValue(SpatialTimeUsSchema, input, "durationUs")
+  if (value === 0) throw new SpatialSceneError("invalid-data", "Output duration must be positive.")
+  return BigInt(value)
+}
+
+export function reduceSpatialFrameRate(input: unknown): SpatialFrameRate {
+  const rate = parseSpatialValue(SpatialFrameRateSchema, input, "frame rate")
+  const divisor = Number(gcd(BigInt(rate.numerator), BigInt(rate.denominator)))
+  return Object.freeze({ numerator: rate.numerator / divisor, denominator: rate.denominator / divisor })
+}
+
+/** Number of nominal samples i/fps in the half-open authored duration. */
+export function spatialFrameCount(durationUs: number, rateInput: unknown): number {
+  const end = duration(durationUs), rate = reduceSpatialFrameRate(rateInput)
+  const numerator = end * BigInt(rate.numerator), denominator = 1_000_000n * BigInt(rate.denominator)
+  return Number((numerator + denominator - 1n) / denominator)
+}
+
+/** Every sample is rounded independently to nearest microsecond, with ties toward +infinity. */
+export function spatialFrameSample(frameIndex: number, durationUs: number, rateInput: unknown): SpatialFrameSample {
+  const index = integer(frameIndex, "frameIndex"), end = duration(durationUs), rate = reduceSpatialFrameRate(rateInput)
+  const numerator = index * 1_000_000n * BigInt(rate.denominator), denominator = BigInt(rate.numerator)
+  if (numerator >= end * denominator) throw new SpatialSceneError("invalid-data", "Frame lies outside the half-open duration before quantization.", "frameIndex")
+  const timeUs = Number((2n * numerator + denominator) / (2n * denominator))
+  return deepFreezeJson({ frameIndex, timeUs, exactTimeUs: rational(numerator, denominator) })
+}
+
+/** Encoded duration is frameCount/fps and can exceed authored duration by less than one frame. */
+export function spatialOutputDuration(durationUs: number, rateInput: unknown): SpatialRational {
+  const rate = reduceSpatialFrameRate(rateInput)
+  return rational(BigInt(spatialFrameCount(durationUs, rate)) * 1_000_000n * BigInt(rate.denominator), BigInt(rate.numerator))
+}

package/src/studio/contracts.ts

@@ -0,0 +1,129 @@
+import { z } from "zod"
+import { createBoundedJsonValueSnapshot } from "../code/json-snapshot.js"
+import { assertDistinctPaths, parseStudioValue, STUDIO_LIMITS, studioCompare, studioDocument, type StudioReadonly } from "./shared.js"
+
+export { STUDIO_LIMITS } from "./shared.js"
+export const StudioDigestSchema = z.string().regex(/^[a-f0-9]{64}$/u)
+export const StudioEngineSchema = z.enum(["blender", "manim", "cadquery"])
+export const StudioPathSchema = z.string().min(1).max(1024).refine(path =>
+  path.normalize("NFC") === path && !path.startsWith("/") && !/[\\:\u0000-\u001f\u007f]/u.test(path)
+  && path.split("/").every(part => part !== "" && part !== "." && part !== ".." && !/[. ]$/u.test(part)),
+"Studio paths must be normalized, contained POSIX-relative names.")
+const identifier = z.string().regex(/^[A-Za-z_][A-Za-z0-9_]{0,127}$/u)
+const stableId = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/u)
+const sourceFile = z.strictObject({ path: StudioPathSchema, sha256: StudioDigestSchema, bytes: z.number().int().safe().nonnegative().max(STUDIO_LIMITS.sourceBytes) })
+const sourceBundleShape = z.strictObject({
+  kind: z.literal("slopcamera.studio-source-bundle"), schemaVersion: z.literal(1), engine: StudioEngineSchema,
+  entrypoint: z.discriminatedUnion("kind", [z.strictObject({ kind: z.literal("python"), path: StudioPathSchema.refine(path => path.endsWith(".py")) }), z.strictObject({ kind: z.literal("blend"), path: StudioPathSchema.refine(path => path.endsWith(".blend")) })]),
+  files: z.array(sourceFile).min(1).max(STUDIO_LIMITS.sourceFiles),
+}).superRefine((value, context) => {
+  const issue = (message: string) => context.addIssue({ code: "custom", message })
+  try { assertDistinctPaths(value.files.map(file => file.path)) } catch { issue("Source paths must be distinct and cannot have file ancestors.") }
+  if (value.files.reduce((total, file) => total + file.bytes, 0) > STUDIO_LIMITS.sourceBytes) issue("Source bundle exceeds four GiB.")
+  if (!value.files.some(file => file.path === value.entrypoint.path && file.bytes > 0)) issue("Entrypoint must name a declared nonempty source file.")
+  if (value.entrypoint.kind === "blend" && value.engine !== "blender") issue("Blend entrypoints require Blender.")
+})
+const sourceBundle = sourceBundleShape.transform(value => ({ ...value, files: [...value.files].sort((a, b) => studioCompare(a.path, b.path)) })).pipe(sourceBundleShape)
+export const StudioSourceBundleSchema = studioDocument(sourceBundle, "studio source bundle")
+export type StudioSourceBundle = StudioReadonly<z.infer<typeof StudioSourceBundleSchema>>
+export const parseStudioSourceBundle = (input: unknown): StudioSourceBundle => parseStudioValue(StudioSourceBundleSchema, input)
+
+export const StudioSourceSpaceSchema = z.strictObject({ units: z.enum(["meters", "millimeters", "centimeters"]), upAxis: z.enum(["x", "y", "z"]), handedness: z.enum(["right", "left"]) })
+export const StudioOutputRoleSchema = z.enum(["native-source", "model", "beauty", "auxiliary", "simulation-cache", "audio"])
+export const StudioOutputFormatSchema = z.enum(["py", "blend", "usd", "usda", "usdc", "glb", "step", "png", "exr", "mp4", "mov", "webm", "wav", "flac", "mp3", "cache"])
+const raster = z.strictObject({
+  kind: z.literal("raster"), colorSpace: z.enum(["srgb", "linear-rec709", "data", "unspecified"]), alpha: z.enum(["opaque", "straight", "premultiplied", "none"]),
+  dataType: z.enum(["uint8", "uint16", "float16", "float32"]), channels: z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]{0,63}$/u)).min(1).max(32),
+  semantic: z.enum(["color", "depth", "normal", "object-id", "mask", "custom"]), unit: z.enum(["unitless", "meters", "millimeters", "centimeters"]),
+}).superRefine((value, context) => {
+  if (new Set(value.channels).size !== value.channels.length) context.addIssue({ code: "custom", message: "Raster channels must be unique." })
+  if (value.semantic !== "color" && value.colorSpace !== "data") context.addIssue({ code: "custom", message: "Non-color raster passes must declare data color space." })
+  if (value.semantic === "color" && value.colorSpace === "data") context.addIssue({ code: "custom", message: "Color output cannot declare data color space." })
+  if (value.semantic !== "depth" && value.unit !== "unitless") context.addIssue({ code: "custom", message: "Only depth passes declare distance units." })
+})
+export const StudioOutputInterpretationSchema = z.discriminatedUnion("kind", [
+  raster, z.strictObject({ kind: z.literal("model"), sourceSpace: StudioSourceSpaceSchema }),
+  z.strictObject({ kind: z.literal("native-source") }), z.strictObject({ kind: z.literal("cache"), semantics: z.literal("opaque-native") }),
+  z.strictObject({ kind: z.literal("audio"), sampleRate: z.number().int().min(8000).max(384000), channels: z.number().int().min(1).max(32) }),
+])
+const outputCommon = { id: stableId, role: StudioOutputRoleSchema, format: StudioOutputFormatSchema, interpretation: StudioOutputInterpretationSchema }
+const pattern = z.string().max(1024).refine(value => value.split("%06d").length === 2 && !value.replace("%06d", "").includes("%") && StudioPathSchema.safeParse(value.replace("%06d", "000000")).success,
+"Sequence paths require exactly one %06d placeholder in a safe relative path.")
+function compatibleOutput(value: { role: z.infer<typeof StudioOutputRoleSchema>; format: z.infer<typeof StudioOutputFormatSchema>; interpretation: z.infer<typeof StudioOutputInterpretationSchema> }): boolean {
+  if (value.role === "native-source") return ["py", "blend"].includes(value.format) && value.interpretation.kind === "native-source"
+  if (value.role === "model") return ["blend", "usd", "usda", "usdc", "glb", "step"].includes(value.format) && value.interpretation.kind === "model"
+  if (value.role === "simulation-cache") return value.format === "cache" && value.interpretation.kind === "cache"
+  if (value.role === "audio") return ["wav", "flac", "mp3"].includes(value.format) && value.interpretation.kind === "audio"
+  return ["png", "exr", "mp4", "mov", "webm"].includes(value.format) && value.interpretation.kind === "raster" && (value.role !== "beauty" || value.interpretation.semantic === "color")
+}
+export const StudioOutputSpecSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ ...outputCommon, kind: z.literal("file"), path: StudioPathSchema }),
+  z.strictObject({ ...outputCommon, kind: z.literal("sequence"), pathPattern: pattern }),
+  z.strictObject({ ...outputCommon, kind: z.literal("directory"), path: StudioPathSchema }),
+]).superRefine((value, context) => {
+  const issue = (message: string) => context.addIssue({ code: "custom", message })
+  if (!compatibleOutput(value)) issue("Output role, format, and interpretation disagree.")
+  if ((value.kind === "directory") !== (value.format === "cache")) issue("Only native cache outputs use directory declarations.")
+  if (value.kind === "sequence" && !["png", "exr"].includes(value.format)) issue("Numbered sequences support PNG or EXR only.")
+  if (value.kind !== "directory") {
+    const path = value.kind === "sequence" ? value.pathPattern : value.path
+    if (!path.endsWith(`.${value.format}`) && !(value.format === "step" && path.endsWith(".stp"))) issue("Output extension must agree with its declared format.")
+  }
+  if (value.interpretation.kind === "raster") {
+    if (value.format === "png" && !["uint8", "uint16"].includes(value.interpretation.dataType)) issue("PNG declares integer sample data.")
+    if (value.format === "exr" && !["float16", "float32"].includes(value.interpretation.dataType)) issue("The admitted EXR profile declares floating point sample data.")
+  }
+})
+export type StudioOutputSpec = StudioReadonly<z.infer<typeof StudioOutputSpecSchema>>
+const frameRateShape = z.strictObject({ numerator: z.number().int().min(1).max(1_000_000), denominator: z.number().int().min(1).max(1_000_000) })
+  .refine(value => value.numerator / value.denominator <= 240, "Studio cadence exceeds 240 fps.")
+const frameRate = frameRateShape.transform(value => { let a = value.numerator, b = value.denominator; while (b !== 0) { const remainder = a % b; a = b; b = remainder } return { numerator: value.numerator / a, denominator: value.denominator / a } }).pipe(frameRateShape)
+export const StudioRenderSchema = z.strictObject({
+  width: z.number().int().min(1).max(STUDIO_LIMITS.dimension), height: z.number().int().min(1).max(STUDIO_LIMITS.dimension), frameRate,
+  startFrame: z.number().int().nonnegative().max(STUDIO_LIMITS.frameIndexExclusive - 1), endFrameExclusive: z.number().int().positive().max(STUDIO_LIMITS.frameIndexExclusive),
+}).refine(value => value.endFrameExclusive > value.startFrame && value.endFrameExclusive - value.startFrame <= STUDIO_LIMITS.frames && value.width * value.height <= STUDIO_LIMITS.pixels,
+"Render requires a bounded, nonempty half-open frame interval and pixel area.")
+export const StudioEngineOptionsSchema = z.discriminatedUnion("engine", [
+  z.strictObject({ engine: z.literal("blender"), renderer: z.enum(["cycles", "eevee"]), device: z.enum(["cpu", "gpu"]), samples: z.number().int().min(1).max(4096), transparent: z.boolean(), viewTransform: z.enum(["AgX", "Standard"]), denoise: z.boolean(), seed: z.number().int().min(0).max(0xffff_ffff) }),
+  z.strictObject({ engine: z.literal("manim"), scene: identifier, renderer: z.literal("cairo"), transparent: z.boolean() }),
+  z.strictObject({ engine: z.literal("cadquery"), exportVariable: identifier, tolerance: z.number().finite().positive().max(1), angularTolerance: z.number().finite().positive().max(Math.PI) }),
+])
+// Capture proves the full JSON closure; avoid a second recursive schema/type expansion.
+const parameters = z.preprocess(value => value === undefined ? undefined : createBoundedJsonValueSnapshot(value, STUDIO_LIMITS.parameterBytes, "studio parameters", { maximumDepth: STUDIO_LIMITS.parameterDepth, maximumValues: STUDIO_LIMITS.parameterValues }).value, z.record(z.string(), z.unknown()))
+export const StudioExecutionProfileSchema = z.strictObject({ trust: z.literal("trusted-current-user"), isolation: z.literal("none"), hermetic: z.literal(false) })
+const jobShape = z.strictObject({
+  kind: z.literal("slopcamera.studio-job"), schemaVersion: z.literal(1), jobId: z.string().regex(/^studio_[a-zA-Z0-9][a-zA-Z0-9_-]{0,120}$/u), bundleSha256: StudioDigestSchema,
+  stage: z.enum(["build", "bake", "render"]), parameters, engine: StudioEngineOptionsSchema, render: StudioRenderSchema.optional(),
+  outputs: z.array(StudioOutputSpecSchema).min(1).max(STUDIO_LIMITS.outputSpecifications),
+  limits: z.strictObject({ timeoutSeconds: z.number().int().min(1).max(STUDIO_LIMITS.timeoutSeconds), maximumOutputBytes: z.number().int().safe().min(1).max(STUDIO_LIMITS.outputBytes), maximumOutputFiles: z.number().int().min(1).max(STUDIO_LIMITS.outputFiles) }),
+  execution: StudioExecutionProfileSchema,
+}).superRefine((value, context) => {
+  if (value.render === undefined && (value.stage === "render" && value.engine.engine !== "cadquery" || value.outputs.some(output => output.kind === "sequence" || output.interpretation.kind === "raster"))) context.addIssue({ code: "custom", message: "Raster outputs, render stage, and numbered sequences require explicit dimensions and a frame interval." })
+  if (new Set(value.outputs.map(output => output.id)).size !== value.outputs.length) context.addIssue({ code: "custom", message: "Output IDs must be unique." })
+  const count = value.outputs.reduce((sum, output) => sum + (output.kind === "sequence" && value.render !== undefined ? value.render.endFrameExclusive - value.render.startFrame : 1), 0)
+  if (count > value.limits.maximumOutputFiles) context.addIssue({ code: "custom", message: "Declared outputs exceed the job's output-file limit." })
+})
+const job = jobShape.transform((value): z.input<typeof jobShape> => ({ ...value, outputs: [...value.outputs].sort((a, b) => studioCompare(a.id, b.id)) })).pipe(jobShape)
+export const StudioJobSchema = studioDocument(job, "studio job")
+export type StudioJob = StudioReadonly<z.infer<typeof StudioJobSchema>>
+export const parseStudioJob = (input: unknown): StudioJob => parseStudioValue(StudioJobSchema, input)
+
+export const StudioCapabilityNameSchema = z.enum(["python-authoring", "blend-authoring", "build", "bake", "render", "gpu-render", "image-sequence", "beauty-video", "model-export", "auxiliary-passes", "native-cache", "audio-output"])
+const capability = z.strictObject({ name: StudioCapabilityNameSchema, support: z.enum(["available", "unavailable", "unverified"]), evidence: z.enum(["probe", "qualification"]), receiptSha256: StudioDigestSchema.optional() })
+  .refine(value => value.evidence !== "qualification" || value.receiptSha256 !== undefined, "Qualification evidence requires a retained receipt digest.")
+const runtimeShape = z.strictObject({
+  kind: z.literal("slopcamera.studio-runtime"), schemaVersion: z.literal(1), engine: StudioEngineSchema,
+  tool: z.strictObject({ name: z.string().min(1).max(128), version: z.string().min(1).max(512), executableSha256: StudioDigestSchema }), driverSha256: StudioDigestSchema,
+  environment: z.strictObject({ fingerprintSha256: StudioDigestSchema, evidence: z.literal("observed-package-environment"), hermetic: z.literal(false) }),
+  capabilities: z.array(capability).max(12),
+}).refine(value => new Set(value.capabilities.map(item => item.name)).size === value.capabilities.length, "Runtime capability names must be unique.")
+const runtime = runtimeShape.transform(value => ({ ...value, capabilities: [...value.capabilities].sort((a, b) => studioCompare(a.name, b.name)) })).pipe(runtimeShape)
+export const StudioRuntimeIdentitySchema = studioDocument(runtime, "studio runtime identity")
+export type StudioRuntimeIdentity = StudioReadonly<z.infer<typeof StudioRuntimeIdentitySchema>>
+export const parseStudioRuntimeIdentity = (input: unknown): StudioRuntimeIdentity => parseStudioValue(StudioRuntimeIdentitySchema, input)
+
+export const StudioOutputArtifactSchema = z.strictObject({
+  outputId: stableId, path: StudioPathSchema, sha256: StudioDigestSchema, bytes: z.number().int().safe().positive().max(STUDIO_LIMITS.outputBytes), role: StudioOutputRoleSchema, format: StudioOutputFormatSchema,
+  frame: z.number().int().nonnegative().max(STUDIO_LIMITS.frameIndexExclusive - 1).optional(),
+})
+export type StudioOutputArtifact = StudioReadonly<z.infer<typeof StudioOutputArtifactSchema>>

package/src/studio/index.ts

@@ -0,0 +1,2 @@
+export * from "./contracts.js"
+export * from "./plan.js"

package/src/studio/plan.ts

@@ -0,0 +1,156 @@
+import { z } from "zod"
+import { canonicalJson } from "../code/canonical-json.js"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import {
+  parseStudioJob, parseStudioRuntimeIdentity, parseStudioSourceBundle, StudioCapabilityNameSchema, StudioDigestSchema,
+  StudioJobSchema, StudioOutputArtifactSchema, StudioRuntimeIdentitySchema, StudioSourceBundleSchema,
+  type StudioJob, type StudioOutputSpec, type StudioRuntimeIdentity, type StudioSourceBundle,
+} from "./contracts.js"
+import { assertDistinctPaths, parseStudioValue, STUDIO_LIMITS, studioCompare, studioDocument, studioHash, studioRequire, type StudioReadonly } from "./shared.js"
+
+export const studioSourceBundleSha256 = (input: unknown): string => studioHash("slopcamera.studio-source-bundle/v1", parseStudioSourceBundle(input))
+export const studioJobSha256 = (input: unknown): string => studioHash("slopcamera.studio-job/v1", parseStudioJob(input))
+export const studioRuntimeSha256 = (input: unknown): string => studioHash("slopcamera.studio-runtime/v1", parseStudioRuntimeIdentity(input))
+
+/** Resolves only the declared fixed-width frame token. It never evaluates paths or source. */
+export function studioOutputPath(output: StudioOutputSpec, frame?: number): string {
+  if (output.kind === "sequence") {
+    studioRequire(Number.isInteger(frame) && frame! >= 0 && frame! < STUDIO_LIMITS.frameIndexExclusive, "Sequence output requires an admitted frame index.")
+    return output.pathPattern.replace("%06d", String(frame).padStart(6, "0"))
+  }
+  studioRequire(frame === undefined, "Only sequence outputs have a frame index.")
+  return output.path
+}
+
+function declaration(job: StudioJob) {
+  const files: { readonly id: string; readonly path: string; readonly frame?: number }[] = []
+  const directories: { readonly id: string; readonly path: string }[] = []
+  for (const output of job.outputs) {
+    if (output.kind === "directory") directories.push({ id: output.id, path: output.path })
+    else if (output.kind === "file") files.push({ id: output.id, path: output.path })
+    else {
+      studioRequire(job.render !== undefined, "Sequence requires a render interval.")
+      for (let frame = job.render.startFrame; frame < job.render.endFrameExclusive; frame++) files.push({ id: output.id, path: studioOutputPath(output, frame), frame })
+    }
+  }
+  studioRequire(files.length + directories.length <= job.limits.maximumOutputFiles, "Declared outputs exceed the output-file budget.")
+  assertDistinctPaths([...files, ...directories].map(item => item.path))
+  return { files, directories }
+}
+function requiredCapabilities(bundle: StudioSourceBundle, job: StudioJob): z.infer<typeof StudioCapabilityNameSchema>[] {
+  const values = new Set<z.infer<typeof StudioCapabilityNameSchema>>([bundle.entrypoint.kind === "blend" ? "blend-authoring" : "python-authoring", job.stage])
+  if (job.engine.engine === "blender" && job.engine.device === "gpu" && job.stage === "render") values.add("gpu-render")
+  for (const output of job.outputs) {
+    if (output.kind === "sequence") values.add("image-sequence")
+    if (output.role === "beauty" && ["mov", "mp4", "webm"].includes(output.format)) values.add("beauty-video")
+    if (output.role === "model") values.add("model-export")
+    if (output.role === "auxiliary") values.add("auxiliary-passes")
+    if (output.role === "simulation-cache") values.add("native-cache")
+    if (output.role === "audio") values.add("audio-output")
+  }
+  return [...values].sort(studioCompare)
+}
+function derivePlan(input: { readonly bundle: StudioSourceBundle; readonly job: StudioJob; readonly runtime?: StudioRuntimeIdentity | undefined }) {
+  const { bundle, job, runtime } = input
+  const bundleSha256 = studioSourceBundleSha256(bundle), jobSha256 = studioJobSha256(job)
+  studioRequire(bundleSha256 === job.bundleSha256, "Job does not bind the exact source bundle.")
+  studioRequire(bundle.engine === job.engine.engine && (runtime === undefined || runtime.engine === bundle.engine), "Bundle, job, and runtime must use one engine.")
+  studioRequire(bundle.entrypoint.kind !== "blend" || job.stage === "render", "Blend entrypoints support render stage only; explicit Python authoring owns builds and bakes.")
+  const declared = declaration(job), required = requiredCapabilities(bundle, job)
+  const capabilityChecks = required.map(name => ({ name, support: runtime === undefined ? "unbound" as const : runtime.capabilities.find(item => item.name === name)?.support ?? "unverified" as const }))
+  const readiness = runtime === undefined ? "runtime-unbound" as const
+    : capabilityChecks.some(item => item.support === "unavailable") ? "capability-unavailable" as const
+    : capabilityChecks.some(item => item.support === "unverified") ? "capability-unverified" as const : "authorization-required" as const
+  const body = {
+    kind: "slopcamera.studio-plan" as const, schemaVersion: 1 as const, bundle, job, ...(runtime === undefined ? {} : { runtime, runtimeSha256: studioRuntimeSha256(runtime) }),
+    bundleSha256, jobSha256, sourceBytes: bundle.files.reduce((total, file) => total + file.bytes, 0),
+    frameCount: job.render === undefined ? 0 : job.render.endFrameExclusive - job.render.startFrame,
+    outputCount: { minimum: declared.files.length + declared.directories.length, maximum: declared.directories.length === 0 ? declared.files.length : job.limits.maximumOutputFiles },
+    requiredCapabilities: required, capabilityChecks, readiness,
+  }
+  return { ...body, planSha256: studioHash("slopcamera.studio-plan/v1", body) }
+}
+const plan = z.strictObject({
+  kind: z.literal("slopcamera.studio-plan"), schemaVersion: z.literal(1), bundle: StudioSourceBundleSchema, job: StudioJobSchema,
+  runtime: StudioRuntimeIdentitySchema.optional(), runtimeSha256: StudioDigestSchema.optional(), bundleSha256: StudioDigestSchema, jobSha256: StudioDigestSchema, planSha256: StudioDigestSchema,
+  sourceBytes: z.number().int().safe().nonnegative().max(STUDIO_LIMITS.sourceBytes), frameCount: z.number().int().nonnegative().max(STUDIO_LIMITS.frames),
+  outputCount: z.strictObject({ minimum: z.number().int().positive().max(STUDIO_LIMITS.outputFiles), maximum: z.number().int().positive().max(STUDIO_LIMITS.outputFiles) }),
+  requiredCapabilities: z.array(StudioCapabilityNameSchema).min(1).max(12),
+  capabilityChecks: z.array(z.strictObject({ name: StudioCapabilityNameSchema, support: z.enum(["available", "unavailable", "unverified", "unbound"]) })).min(1).max(12),
+  readiness: z.enum(["runtime-unbound", "capability-unavailable", "capability-unverified", "authorization-required"]),
+}).superRefine((value, context) => {
+  try {
+    const derived = derivePlan({ bundle: value.bundle, job: value.job, ...(value.runtime === undefined ? {} : { runtime: value.runtime }) })
+    if (canonicalJson(derived) !== canonicalJson(value)) context.addIssue({ code: "custom", message: "Studio plan differs from its canonical source, job, runtime, or admission derivation." })
+  } catch (error) { context.addIssue({ code: "custom", message: error instanceof Error ? error.message : "Invalid studio plan." }) }
+})
+export const StudioPlanSchema = studioDocument(plan, "studio plan")
+export type StudioPlan = StudioReadonly<z.infer<typeof StudioPlanSchema>>
+export const parseStudioPlan = (input: unknown): StudioPlan => parseStudioValue(StudioPlanSchema, input)
+export function planStudioJob(input: { readonly bundle: unknown; readonly job: unknown; readonly runtime?: unknown }): StudioPlan {
+  const captured = parseStudioValue(studioDocument(z.strictObject({ bundle: StudioSourceBundleSchema, job: StudioJobSchema, runtime: StudioRuntimeIdentitySchema.optional() }), "studio planning input"), input)
+  return parseStudioPlan(derivePlan(captured))
+}
+
+const failure = z.strictObject({ code: z.enum(["subprocess", "cancelled", "deadline", "validation", "custody", "publication", "unavailable"]), message: z.string().min(1).max(2048) })
+const receiptCommon = {
+  kind: z.literal("slopcamera.studio-receipt"), schemaVersion: z.literal(1), jobId: z.string().regex(/^studio_[a-zA-Z0-9][a-zA-Z0-9_-]{0,120}$/u), attemptId: z.string().regex(/^attempt_[a-zA-Z0-9][a-zA-Z0-9_-]{0,120}$/u),
+  planSha256: StudioDigestSchema, bundleSha256: StudioDigestSchema, jobSha256: StudioDigestSchema, runtime: StudioRuntimeIdentitySchema, runtimeSha256: StudioDigestSchema,
+  startedAt: z.iso.datetime({ offset: true }), finishedAt: z.iso.datetime({ offset: true }), outputs: z.array(StudioOutputArtifactSchema).max(STUDIO_LIMITS.outputFiles),
+}
+const receiptShape = z.discriminatedUnion("state", [
+  z.strictObject({ ...receiptCommon, state: z.literal("succeeded"), custody: z.literal("closed"), exitCode: z.literal(0) }),
+  z.strictObject({ ...receiptCommon, state: z.literal("failed"), custody: z.literal("closed"), exitCode: z.number().int().min(-255).max(255).nullable(), failure }),
+  z.strictObject({ ...receiptCommon, state: z.literal("unknown-custody"), custody: z.literal("unknown"), exitCode: z.number().int().min(-255).max(255).nullable(), failure }),
+]).superRefine((value, context) => {
+  if (studioRuntimeSha256(value.runtime) !== value.runtimeSha256) context.addIssue({ code: "custom", message: "Receipt runtime digest differs from its evidence." })
+  if (Date.parse(value.finishedAt) < Date.parse(value.startedAt)) context.addIssue({ code: "custom", message: "Receipt finishes before it starts." })
+  try { assertDistinctPaths(value.outputs.map(item => item.path)) } catch { context.addIssue({ code: "custom", message: "Receipt output paths collide." }) }
+  if (value.outputs.reduce((sum, item) => sum + item.bytes, 0) > STUDIO_LIMITS.outputBytes) context.addIssue({ code: "custom", message: "Receipt exceeds the global output byte bound." })
+})
+const receipt = receiptShape.transform((value): z.input<typeof receiptShape> => ({ ...value, outputs: [...value.outputs].sort((a, b) => studioCompare(a.path, b.path)) })).pipe(receiptShape)
+export const StudioReceiptSchema = studioDocument(receipt, "studio receipt")
+export type StudioReceipt = StudioReadonly<z.infer<typeof StudioReceiptSchema>>
+export const parseStudioReceipt = (input: unknown): StudioReceipt => parseStudioValue(StudioReceiptSchema, input)
+
+/** Validates retained declarations and provenance; host code must verify actual files and native custody. */
+export function validateStudioReceipt(input: { readonly plan: unknown; readonly receipt: unknown }): StudioReceipt {
+  const captured = parseStudioValue(studioDocument(z.strictObject({ plan: StudioPlanSchema, receipt: StudioReceiptSchema }), "studio receipt validation input"), input)
+  const { plan, receipt } = captured
+  studioRequire(receipt.jobId === plan.job.jobId && receipt.planSha256 === plan.planSha256 && receipt.jobSha256 === plan.jobSha256 && receipt.bundleSha256 === plan.bundleSha256, "Receipt identity differs from the exact planned job.")
+  studioRequire(plan.runtime !== undefined && receipt.runtimeSha256 === plan.runtimeSha256 && canonicalJson(receipt.runtime) === canonicalJson(plan.runtime), "Execution receipt requires the exact planned runtime binding.")
+  if (receipt.state === "succeeded") studioRequire(plan.readiness === "authorization-required", "A successful receipt requires available observed runtime capabilities; consent remains host-owned.")
+  studioRequire(receipt.outputs.length <= plan.job.limits.maximumOutputFiles && receipt.outputs.reduce((total, output) => total + output.bytes, 0) <= plan.job.limits.maximumOutputBytes, "Receipt exceeds the planned output budget.")
+  const declared = declaration(plan.job), expected = new Map(declared.files.map(file => [file.path, file]))
+  const counts = new Map<string, number>()
+  for (const artifact of receipt.outputs) {
+    const specification = plan.job.outputs.find(output => output.id === artifact.outputId)
+    studioRequire(specification !== undefined, "Receipt contains an undeclared output ID.")
+    studioRequire(artifact.role === specification.role && artifact.format === specification.format, "Receipt output role or format differs from its declaration.")
+    if (specification.kind === "directory") {
+      studioRequire(artifact.path.startsWith(`${specification.path}/`) && artifact.frame === undefined, "Cache artifact must be a file inside its declared directory.")
+    } else {
+      const wanted = expected.get(artifact.path)
+      studioRequire(wanted !== undefined && wanted.id === artifact.outputId && artifact.frame === wanted.frame, "Receipt contains an undeclared file or incorrect frame index.")
+      expected.delete(artifact.path)
+    }
+    counts.set(artifact.outputId, (counts.get(artifact.outputId) ?? 0) + 1)
+  }
+  if (receipt.state === "succeeded") {
+    studioRequire(expected.size === 0 && declared.directories.every(directory => (counts.get(directory.id) ?? 0) > 0), "Successful receipt must cover every declared file, frame, and cache directory.")
+  }
+  return deepFreezeJson(receipt)
+}
+
+export function inspectStudioBundle(input: unknown) {
+  const bundle = parseStudioSourceBundle(input)
+  return deepFreezeJson({ engine: bundle.engine, entrypoint: bundle.entrypoint, bundleSha256: studioSourceBundleSha256(bundle), files: bundle.files.length,
+    sourceBytes: bundle.files.reduce((total, file) => total + file.bytes, 0), executed: false as const, dependencyDiscovery: "explicit-files-only" as const })
+}
+export function inspectStudioPlan(input: unknown) {
+  const plan = parseStudioPlan(input)
+  return deepFreezeJson({ jobId: plan.job.jobId, stage: plan.job.stage, engine: plan.job.engine.engine, planSha256: plan.planSha256,
+    sourceBytes: plan.sourceBytes, frameCount: plan.frameCount, outputCount: plan.outputCount, readiness: plan.readiness,
+    capabilityChecks: plan.capabilityChecks, execution: plan.job.execution, limits: plan.job.limits, executed: false as const,
+    outputs: plan.job.outputs.map(output => ({ id: output.id, role: output.role, format: output.format, kind: output.kind, path: output.kind === "sequence" ? output.pathPattern : output.path })) })
+}

package/src/studio/shared.ts

@@ -0,0 +1,41 @@
+import { z } from "zod"
+import { boundedCanonicalJsonSha256, compareUtf16Strings } from "../code/canonical-json.js"
+import { SlopcameraCodeError } from "../code/errors.js"
+import { createBoundedJsonValueSnapshot, deepFreezeJson } from "../code/json-snapshot.js"
+
+export const STUDIO_LIMITS = Object.freeze({
+  documentBytes: 32 * 1024 * 1024, documentDepth: 32, documentValues: 500_000,
+  sourceFiles: 512, sourceBytes: 4 * 1024 ** 3, outputSpecifications: 32,
+  outputFiles: 25_000, outputBytes: 64 * 1024 ** 3, timeoutSeconds: 6 * 60 * 60,
+  frames: 25_000, frameIndexExclusive: 1_000_000, dimension: 8192, pixels: 33_554_432,
+  parameterBytes: 256 * 1024, parameterDepth: 16, parameterValues: 20_000,
+})
+export type StudioReadonly<T> = T extends object ? { readonly [Key in keyof T]: StudioReadonly<T[Key]> } : T
+export function studioDocument<Schema extends z.ZodType>(schema: Schema, name: string) {
+  return z.preprocess(value => value === undefined ? undefined : createBoundedJsonValueSnapshot(value, STUDIO_LIMITS.documentBytes, name,
+    { maximumDepth: STUDIO_LIMITS.documentDepth, maximumValues: STUDIO_LIMITS.documentValues }).value, schema)
+}
+export function parseStudioValue<Schema extends z.ZodType>(schema: Schema, input: unknown): StudioReadonly<z.infer<Schema>> {
+  try { return deepFreezeJson(schema.parse(input)) as StudioReadonly<z.infer<Schema>> }
+  catch (error) {
+    if (error instanceof SlopcameraCodeError) throw error
+    throw new SlopcameraCodeError("invalid-data", error instanceof z.ZodError ? error.issues[0]?.message ?? "Invalid studio document." : "Invalid studio document.")
+  }
+}
+export function studioHash(domain: string, value: unknown): string {
+  return boundedCanonicalJsonSha256({ domain, value }, { maximumBytes: STUDIO_LIMITS.documentBytes, maximumDepth: STUDIO_LIMITS.documentDepth + 2, maximumValues: STUDIO_LIMITS.documentValues + 4 })
+}
+export const studioCompare = compareUtf16Strings
+export function studioRequire(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new SlopcameraCodeError("invalid-data", message)
+}
+export function pathKey(path: string): string { return path.toLowerCase() }
+export function assertDistinctPaths(paths: readonly string[]): void {
+  const names = new Set(paths.map(pathKey))
+  studioRequire(names.size === paths.length, "Studio paths collide.")
+  for (const name of names) {
+    for (let offset = name.indexOf("/"); offset !== -1; offset = name.indexOf("/", offset + 1)) {
+      studioRequire(!names.has(name.slice(0, offset)), "Studio paths use a file as an ancestor.")
+    }
+  }
+}

package/src/theme.ts

@@ -0,0 +1,68 @@
+import type { ColorMode, DiagramConfig, PartialTheme, ThemeColors, Tone } from "./types.js"
+
+const tones: readonly Tone[] = [
+  "neutral",
+  "blue",
+  "orange",
+  "green",
+  "red",
+  "purple",
+  "yellow",
+]
+
+const defaults: Readonly<Record<ColorMode, ThemeColors>> = {
+  light: {
+    background: "#ffffff",
+    foreground: "#18181b",
+    muted: "#71717a",
+    stroke: "#27272a",
+    tones: {
+      neutral: { fill: "#f4f4f5", stroke: "#52525b", text: "#18181b" },
+      blue: { fill: "#dbeafe", stroke: "#2563eb", text: "#1e3a8a" },
+      orange: { fill: "#ffedd5", stroke: "#ea580c", text: "#7c2d12" },
+      green: { fill: "#dcfce7", stroke: "#16a34a", text: "#14532d" },
+      red: { fill: "#fee2e2", stroke: "#dc2626", text: "#7f1d1d" },
+      purple: { fill: "#f3e8ff", stroke: "#9333ea", text: "#581c87" },
+      yellow: { fill: "#fef9c3", stroke: "#ca8a04", text: "#713f12" },
+    },
+  },
+  dark: {
+    background: "#09090b",
+    foreground: "#fafafa",
+    muted: "#a1a1aa",
+    stroke: "#d4d4d8",
+    tones: {
+      neutral: { fill: "#27272a", stroke: "#a1a1aa", text: "#fafafa" },
+      blue: { fill: "#172554", stroke: "#60a5fa", text: "#dbeafe" },
+      orange: { fill: "#431407", stroke: "#fb923c", text: "#ffedd5" },
+      green: { fill: "#052e16", stroke: "#4ade80", text: "#dcfce7" },
+      red: { fill: "#450a0a", stroke: "#f87171", text: "#fee2e2" },
+      purple: { fill: "#3b0764", stroke: "#c084fc", text: "#f3e8ff" },
+      yellow: { fill: "#422006", stroke: "#facc15", text: "#fef9c3" },
+    },
+  },
+}
+
+function mergeTheme(base: ThemeColors, override: PartialTheme | undefined): ThemeColors {
+  if (override === undefined) return base
+  return {
+    background: override.background ?? base.background,
+    foreground: override.foreground ?? base.foreground,
+    muted: override.muted ?? base.muted,
+    stroke: override.stroke ?? base.stroke,
+    tones: Object.fromEntries(
+      tones.map((tone) => [
+        tone,
+        {
+          fill: override.tones?.[tone]?.fill ?? base.tones[tone].fill,
+          stroke: override.tones?.[tone]?.stroke ?? base.tones[tone].stroke,
+          text: override.tones?.[tone]?.text ?? base.tones[tone].text,
+        },
+      ]),
+    ) as ThemeColors["tones"],
+  }
+}
+
+export function resolveTheme(mode: ColorMode, config: DiagramConfig): ThemeColors {
+  return mergeTheme(defaults[mode], config.theme?.[mode])
+}