@hraness/slopcamera 3.2.8 → 3.3.1

package/apps/desktop/application/operations/spatial-rendered-audit.ts

@@ -0,0 +1,174 @@
+import { constants } from "node:fs";
+import { mkdtemp, open, rm } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+
+import { z } from "zod";
+
+import { createBoundedJsonValueSnapshot } from "../../../../src/code/json-snapshot";
+import { SPATIAL_SCENE_LIMITS, SpatialAssetIdSchema, SpatialDigestSchema } from "../../../../src/spatial-scene/contracts";
+import { parseSpatialScene, spatialSceneSha256 } from "../../../../src/spatial-scene/identity";
+import { SpatialRenderedAuditReportSchema } from "../../../../src/spatial-scene/audit-rendered";
+import { ensurePhysicalPrivateDirectoryWithin } from "../../cli/paths";
+import { canonicalJson } from "../../core/canonical-json";
+import { exactCapabilityByName } from "../capability-binding";
+import type { ApplicationContext } from "../context";
+import { ApplicationError } from "../errors";
+import { bindHtmlOverlayBrowserRuntime, HtmlOverlayBrowserRuntimeBindingSchema } from "../html-overlay-browser-runtime";
+import type { OperationDefinition, OperationExecutionContext } from "../operation";
+import {
+  auditSpatialSceneRenderedHost, planSpatialRenderedAudit, spatialRenderedAuditCapabilityNames,
+  SpatialRenderedAuditRequestSchema, type SpatialRenderedAuditDependencies,
+} from "../spatial-rendered-audit";
+import { MediaCapabilityBindingsSchema, bindExpectedMediaCapabilities } from "./media/capabilities";
+import {
+  MediaArtifactReferenceSchema, MediaArtifactRequestSchema, bindRepositoryMedia, loadRepositoryMedia,
+  createMediaOperationWorkspace,
+} from "./media/shared";
+
+const MAXIMUM_ASSET_BYTES = 256 * 1024 * 1024;
+const AssetBindingSchema = z.strictObject({ assetId: SpatialAssetIdSchema, artifact: MediaArtifactReferenceSchema });
+const requestShape = z.strictObject({
+  source: MediaArtifactRequestSchema,
+  assets: z.array(AssetBindingSchema).max(SPATIAL_SCENE_LIMITS.assets).optional(),
+  request: SpatialRenderedAuditRequestSchema,
+  sceneSha256: SpatialDigestSchema.optional(),
+  capabilityBindings: MediaCapabilityBindingsSchema.optional(),
+  browserRuntime: HtmlOverlayBrowserRuntimeBindingSchema.optional(),
+});
+const captured = (input: unknown) => createBoundedJsonValueSnapshot(input, 16 * 1024 * 1024, "spatial rendered audit request", { maximumDepth: 48, maximumValues: 500_000 }).value;
+export const SpatialRenderedAuditInputSchema = z.preprocess(captured, requestShape);
+export const BoundSpatialRenderedAuditInputSchema = z.preprocess(captured, requestShape.extend({
+  source: MediaArtifactReferenceSchema,
+  assets: z.array(AssetBindingSchema).max(SPATIAL_SCENE_LIMITS.assets),
+  sceneSha256: SpatialDigestSchema,
+  capabilityBindings: MediaCapabilityBindingsSchema,
+  browserRuntime: HtmlOverlayBrowserRuntimeBindingSchema,
+}));
+/** The output is the report itself, matching scene.audit; nothing is published. */
+export const SpatialRenderedAuditOutputSchema = SpatialRenderedAuditReportSchema;
+export type SpatialRenderedAuditInput = z.infer<typeof SpatialRenderedAuditInputSchema>;
+export type BoundSpatialRenderedAuditInput = z.infer<typeof BoundSpatialRenderedAuditInputSchema>;
+export type SpatialRenderedAuditOutput = z.infer<typeof SpatialRenderedAuditOutputSchema>;
+
+function sourceDocument(data: Uint8Array) {
+  try { return parseSpatialScene(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data))); }
+  catch (error) { throw new ApplicationError("invalid-data", `Invalid spatial source: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+/**
+ * The source grants access only to its bounded, root-contained declared
+ * closure. Capability and browser-runtime identity are bound at admission and
+ * re-verified inside the host service, exactly like scene.render.
+ */
+export async function bindSpatialRenderedAuditInput(
+  application: ApplicationContext,
+  input: unknown,
+  signal = new AbortController().signal,
+  bindRuntime: typeof bindHtmlOverlayBrowserRuntime = bindHtmlOverlayBrowserRuntime,
+): Promise<BoundSpatialRenderedAuditInput> {
+  const parsed = SpatialRenderedAuditInputSchema.parse(input);
+  const source = await loadRepositoryMedia(application, parsed.source, signal, SPATIAL_SCENE_LIMITS.sourceBytes);
+  const scene = sourceDocument(source.data);
+  planSpatialRenderedAudit(scene, parsed.request);
+  const sceneSha256 = spatialSceneSha256(scene);
+  if (parsed.sceneSha256 !== undefined && parsed.sceneSha256 !== sceneSha256) throw new ApplicationError("conflict", "Scene source changed after planning.");
+  if (scene.assets.reduce((sum, asset) => sum + asset.payload.bytes, 0) > MAXIMUM_ASSET_BYTES) throw new ApplicationError("invalid-data", "Scene asset closure exceeds 256 MiB.");
+  const supplied = parsed.assets === undefined ? undefined : new Map(parsed.assets.map(item => [item.assetId, item.artifact]));
+  if (supplied !== undefined && (supplied.size !== parsed.assets!.length || supplied.size !== scene.assets.length || scene.assets.some(asset => !supplied.has(asset.assetId)))) throw new ApplicationError("invalid-data", "Asset bindings must name every declared asset exactly once.");
+  const assets: z.infer<typeof AssetBindingSchema>[] = [];
+  for (const asset of scene.assets) {
+    const request = supplied?.get(asset.assetId) ?? {
+      ...asset.payload, path: posix.join(posix.dirname(source.artifact.path), asset.payload.path),
+    };
+    if (request.sha256 !== asset.payload.sha256 || request.bytes !== asset.payload.bytes) throw new ApplicationError("conflict", `Asset ${asset.assetId} does not match its source manifest.`);
+    const bound = await bindRepositoryMedia(application, request, signal, asset.payload.bytes);
+    assets.push({ assetId: asset.assetId, artifact: bound.artifact });
+  }
+  const capabilityBindings = await bindExpectedMediaCapabilities(application, spatialRenderedAuditCapabilityNames(scene), parsed.capabilityBindings);
+  const browserRuntime = await bindRuntime(exactCapabilityByName(capabilityBindings, "html-browser"), signal);
+  if (parsed.browserRuntime !== undefined && canonicalJson(parsed.browserRuntime) !== canonicalJson(browserRuntime)) throw new ApplicationError("conflict", "Browser runtime changed after rendered audit planning.");
+  return BoundSpatialRenderedAuditInputSchema.parse({ ...parsed, source: source.artifact, assets, sceneSha256, capabilityBindings, browserRuntime });
+}
+
+async function writePrivateFile(path: string, bytes: Uint8Array): Promise<void> {
+  const handle = await open(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+}
+
+/** Trusted test ports are never part of a serialized audit request. */
+export interface SpatialRenderedAuditOperationDependencies extends SpatialRenderedAuditDependencies {
+  readonly createWorkspace?: typeof createMediaOperationWorkspace;
+  readonly createDirectory?: typeof mkdtemp;
+  readonly removeDirectory?: (path: string) => Promise<void>;
+}
+
+export async function executeSpatialRenderedAudit(
+  context: OperationExecutionContext,
+  input: SpatialRenderedAuditInput,
+  dependencies: SpatialRenderedAuditOperationDependencies = {},
+): Promise<SpatialRenderedAuditOutput> {
+  if (context.workflow !== undefined) BoundSpatialRenderedAuditInputSchema.parse(input);
+  const bound = await bindSpatialRenderedAuditInput(context.application, input, context.abortSignal, dependencies.bindBrowserRuntime);
+  const source = await loadRepositoryMedia(context.application, bound.source, context.abortSignal, SPATIAL_SCENE_LIMITS.sourceBytes);
+  const scene = sourceDocument(source.data);
+  const workspace = await (dependencies.createWorkspace ?? createMediaOperationWorkspace)(context);
+  let directory: string | undefined;
+  const cleanupErrors: unknown[] = [];
+  let completed: SpatialRenderedAuditOutput | undefined, failure: unknown, failed = false;
+  try {
+    directory = await (dependencies.createDirectory ?? mkdtemp)(join(workspace.path, "spatial-audit-source-"));
+    const assetRoot = await ensurePhysicalPrivateDirectoryWithin(directory, "assets");
+    const writtenPaths = new Map<string, string>();
+    for (const asset of scene.assets) {
+      const artifact = bound.assets.find(item => item.assetId === asset.assetId)!.artifact;
+      const loaded = await loadRepositoryMedia(context.application, artifact, context.abortSignal, asset.payload.bytes);
+      const previous = writtenPaths.get(asset.payload.path);
+      if (previous !== undefined) {
+        if (previous !== artifact.sha256) throw new ApplicationError("conflict", "Two scene assets declare different bytes at one path.");
+        continue;
+      }
+      const parent = dirname(asset.payload.path);
+      if (parent !== ".") await ensurePhysicalPrivateDirectoryWithin(assetRoot, parent);
+      await writePrivateFile(join(assetRoot, asset.payload.path), loaded.data);
+      writtenPaths.set(asset.payload.path, artifact.sha256);
+    }
+    const report = await auditSpatialSceneRenderedHost(context, {
+      scene, assetRoot, request: bound.request,
+      capabilityBindings: bound.capabilityBindings, browserRuntime: bound.browserRuntime,
+    }, dependencies);
+    completed = SpatialRenderedAuditOutputSchema.parse(report);
+  } catch (error) { failure = error; failed = true; }
+  finally {
+    if (directory !== undefined) try { await (dependencies.removeDirectory ?? (async path => { await rm(path, { recursive: true, force: true }); }))(directory); } catch (error) { cleanupErrors.push(error); }
+    try { await workspace.dispose(); } catch (error) { cleanupErrors.push(error); }
+  }
+  if (failed || cleanupErrors.length > 0) {
+    const cause = cleanupErrors.length === 0 ? failure : new AggregateError([...(failed ? [failure] : []), ...cleanupErrors], "Rendered scene audit failed during execution or cleanup.");
+    const error = new ApplicationError(failure instanceof ApplicationError ? failure.code : "internal",
+      cause instanceof Error ? cause.message : "Rendered scene audit failed.",
+      { cleanupErrors: cleanupErrors.map(error => error instanceof Error ? error.message : String(error)) });
+    error.cause = cause;
+    throw error;
+  }
+  if (completed === undefined) throw new ApplicationError("internal", "Rendered scene audit completed without a report.");
+  return completed;
+}
+
+export const spatialRenderedAuditOperationDefinition = {
+  kind: "scene.render-audit", version: 1,
+  inputSchema: SpatialRenderedAuditInputSchema, inputSchemaId: "slopcamera.operation.scene.render-audit.input/v1",
+  outputSchema: SpatialRenderedAuditOutputSchema, outputSchemaId: "slopcamera.operation.scene.render-audit.output/v1",
+  lifecycle: { kind: "local-artifact", execute: executeSpatialRenderedAudit },
+  policy: {
+    cache: "none", cancellable: true, effect: "local-derived-write", maxDurationMs: 300_000,
+    maxFanOut: 0, maxInputBytes: 16 * 1024 * 1024, maxOutputBytes: 34 * 1024 * 1024,
+    preparation: ["local-media"], resources: [
+      { amount: 1, resource: "cpu" }, { amount: 1, resource: "local-io" }, { amount: 1, resource: "browser" },
+      { amount: 1, resource: "ffmpeg" },
+    ], resume: "deterministic",
+  },
+  summarize: output => ({ kind: "scene.render-audit", fields: {
+    sceneSha256: output.sceneSha256, cameraId: output.cameraId, samples: output.timesUs.length,
+    entities: output.summary.entities.total, neverRendered: output.summary.entitiesNeverRendered.length, findings: output.findings.length,
+  } }),
+} satisfies OperationDefinition<"scene.render-audit", SpatialRenderedAuditInput, SpatialRenderedAuditOutput>;

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

@@ -0,0 +1,194 @@
+import { constants } from "node:fs";
+import { mkdtemp, open, rm } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+
+import { z } from "zod";
+
+import { createBoundedJsonValueSnapshot } from "../../../../src/code/json-snapshot";
+import { SPATIAL_SCENE_LIMITS, SpatialAssetIdSchema, SpatialDigestSchema } from "../../../../src/spatial-scene/contracts";
+import { parseSpatialScene } from "../../../../src/spatial-scene/identity";
+import { SPATIAL_REVIEW_LIMITS, SpatialReviewReportSchema } from "../../../../src/spatial-scene/review";
+import { ensurePhysicalPrivateDirectoryWithin } from "../../cli/paths";
+import { canonicalJson } from "../../core/canonical-json";
+import { exactCapabilityByName } from "../capability-binding";
+import type { ApplicationContext } from "../context";
+import { ApplicationError } from "../errors";
+import { bindHtmlOverlayBrowserRuntime, HtmlOverlayBrowserRuntimeBindingSchema } from "../html-overlay-browser-runtime";
+import type { OperationDefinition, OperationExecutionContext } from "../operation";
+import {
+  planSpatialReview, reviewSpatialSceneHost, spatialReviewCapabilityNames,
+  SpatialReviewRequestSchema, type SpatialReviewDependencies, type SpatialReviewGrant,
+} from "../spatial-review";
+import { MediaCapabilityBindingsSchema, bindExpectedMediaCapabilities } from "./media/capabilities";
+import {
+  MediaArtifactReferenceSchema, MediaArtifactRequestSchema, bindRepositoryMedia, loadRepositoryMedia,
+  createMediaOperationWorkspace,
+} from "./media/shared";
+
+const MAXIMUM_ASSET_BYTES = 256 * 1024 * 1024;
+const AssetBindingSchema = z.strictObject({ assetId: SpatialAssetIdSchema, artifact: MediaArtifactReferenceSchema });
+const requestShape = z.strictObject({
+  source: MediaArtifactRequestSchema,
+  assets: z.array(AssetBindingSchema).max(SPATIAL_SCENE_LIMITS.assets).optional(),
+  request: SpatialReviewRequestSchema,
+  sceneSha256: SpatialDigestSchema.optional(),
+  capabilityBindings: MediaCapabilityBindingsSchema.optional(),
+  browserRuntime: HtmlOverlayBrowserRuntimeBindingSchema.optional(),
+});
+const captured = (input: unknown) => createBoundedJsonValueSnapshot(input, 16 * 1024 * 1024, "spatial review request", { maximumDepth: 48, maximumValues: 500_000 }).value;
+export const SpatialReviewInputSchema = z.preprocess(captured, requestShape);
+export const BoundSpatialReviewInputSchema = z.preprocess(captured, requestShape.extend({
+  source: MediaArtifactReferenceSchema,
+  assets: z.array(AssetBindingSchema).max(SPATIAL_SCENE_LIMITS.assets),
+  sceneSha256: SpatialDigestSchema,
+  capabilityBindings: MediaCapabilityBindingsSchema,
+  browserRuntime: HtmlOverlayBrowserRuntimeBindingSchema,
+}));
+/** The output is the advisory report itself, matching scene.render-audit; nothing is published. */
+export const SpatialReviewOutputSchema = SpatialReviewReportSchema;
+export type SpatialReviewInput = z.infer<typeof SpatialReviewInputSchema>;
+export type BoundSpatialReviewInput = z.infer<typeof BoundSpatialReviewInputSchema>;
+export type SpatialReviewOutput = z.infer<typeof SpatialReviewOutputSchema>;
+
+function sourceDocument(data: Uint8Array) {
+  try { return parseSpatialScene(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(data))); }
+  catch (error) { throw new ApplicationError("invalid-data", `Invalid spatial source: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+/**
+ * The source grants access only to its bounded, root-contained declared
+ * closure. Consent is checked against the exact planned upload before any
+ * capability probe, browser binding, render, or provider dispatch: without an
+ * invocation-scoped grant this fails closed with `authorization-required`.
+ * Capability and browser-runtime identity are bound at admission and
+ * re-verified inside the host service, exactly like scene.render-audit.
+ */
+export async function bindSpatialReviewInput(
+  application: ApplicationContext,
+  input: unknown,
+  signal = new AbortController().signal,
+  bindRuntime: typeof bindHtmlOverlayBrowserRuntime = bindHtmlOverlayBrowserRuntime,
+): Promise<Readonly<{ bound: BoundSpatialReviewInput; grant: SpatialReviewGrant }>> {
+  const parsed = SpatialReviewInputSchema.parse(input);
+  const source = await loadRepositoryMedia(application, parsed.source, signal, SPATIAL_SCENE_LIMITS.sourceBytes);
+  const scene = sourceDocument(source.data);
+  const plan = planSpatialReview(scene, parsed.request);
+  const sceneSha256 = plan.sceneSha256;
+  if (parsed.sceneSha256 !== undefined && parsed.sceneSha256 !== sceneSha256) throw new ApplicationError("conflict", "Scene source changed after planning.");
+  const authorization = application.spatialReviewAuthorization;
+  const grant = authorization === undefined ? undefined : await authorization.authorize({
+    sceneSha256,
+    cameraId: plan.request.cameraId,
+    timesUs: plan.timesUs,
+    maximumFrames: plan.timesUs.length,
+    maximumFrameBytes: SPATIAL_REVIEW_LIMITS.pngBytes,
+    maximumUploadBytes: SPATIAL_REVIEW_LIMITS.uploadBytes,
+  });
+  if (grant === undefined) {
+    throw new ApplicationError("authorization-required", "Scene review uploads the selected bounded rendered beauty frames to a vision model and requires an explicit cloud-upload grant for this invocation.");
+  }
+  if (scene.assets.reduce((sum, asset) => sum + asset.payload.bytes, 0) > MAXIMUM_ASSET_BYTES) throw new ApplicationError("invalid-data", "Scene asset closure exceeds 256 MiB.");
+  const supplied = parsed.assets === undefined ? undefined : new Map(parsed.assets.map(item => [item.assetId, item.artifact]));
+  if (supplied !== undefined && (supplied.size !== parsed.assets!.length || supplied.size !== scene.assets.length || scene.assets.some(asset => !supplied.has(asset.assetId)))) throw new ApplicationError("invalid-data", "Asset bindings must name every declared asset exactly once.");
+  const assets: z.infer<typeof AssetBindingSchema>[] = [];
+  for (const asset of scene.assets) {
+    const request = supplied?.get(asset.assetId) ?? {
+      ...asset.payload, path: posix.join(posix.dirname(source.artifact.path), asset.payload.path),
+    };
+    if (request.sha256 !== asset.payload.sha256 || request.bytes !== asset.payload.bytes) throw new ApplicationError("conflict", `Asset ${asset.assetId} does not match its source manifest.`);
+    const bound = await bindRepositoryMedia(application, request, signal, asset.payload.bytes);
+    assets.push({ assetId: asset.assetId, artifact: bound.artifact });
+  }
+  const capabilityBindings = await bindExpectedMediaCapabilities(application, spatialReviewCapabilityNames(scene), parsed.capabilityBindings);
+  const browserRuntime = await bindRuntime(exactCapabilityByName(capabilityBindings, "html-browser"), signal);
+  if (parsed.browserRuntime !== undefined && canonicalJson(parsed.browserRuntime) !== canonicalJson(browserRuntime)) throw new ApplicationError("conflict", "Browser runtime changed after review planning.");
+  return {
+    bound: BoundSpatialReviewInputSchema.parse({ ...parsed, source: source.artifact, assets, sceneSha256, capabilityBindings, browserRuntime }),
+    grant,
+  };
+}
+
+async function writePrivateFile(path: string, bytes: Uint8Array): Promise<void> {
+  const handle = await open(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+}
+
+/** Trusted test ports are never part of a serialized review request. */
+export interface SpatialReviewOperationDependencies extends SpatialReviewDependencies {
+  readonly createWorkspace?: typeof createMediaOperationWorkspace;
+  readonly createDirectory?: typeof mkdtemp;
+  readonly removeDirectory?: (path: string) => Promise<void>;
+}
+
+export async function executeSpatialReview(
+  context: OperationExecutionContext,
+  input: SpatialReviewInput,
+  dependencies: SpatialReviewOperationDependencies = {},
+): Promise<SpatialReviewOutput> {
+  if (context.workflow !== undefined) BoundSpatialReviewInputSchema.parse(input);
+  const { bound, grant } = await bindSpatialReviewInput(context.application, input, context.abortSignal, dependencies.bindBrowserRuntime);
+  const source = await loadRepositoryMedia(context.application, bound.source, context.abortSignal, SPATIAL_SCENE_LIMITS.sourceBytes);
+  const scene = sourceDocument(source.data);
+  const workspace = await (dependencies.createWorkspace ?? createMediaOperationWorkspace)(context);
+  let directory: string | undefined;
+  const cleanupErrors: unknown[] = [];
+  let completed: SpatialReviewOutput | undefined, failure: unknown, failed = false;
+  try {
+    directory = await (dependencies.createDirectory ?? mkdtemp)(join(workspace.path, "spatial-review-source-"));
+    const assetRoot = await ensurePhysicalPrivateDirectoryWithin(directory, "assets");
+    const writtenPaths = new Map<string, string>();
+    for (const asset of scene.assets) {
+      const artifact = bound.assets.find(item => item.assetId === asset.assetId)!.artifact;
+      const loaded = await loadRepositoryMedia(context.application, artifact, context.abortSignal, asset.payload.bytes);
+      const previous = writtenPaths.get(asset.payload.path);
+      if (previous !== undefined) {
+        if (previous !== artifact.sha256) throw new ApplicationError("conflict", "Two scene assets declare different bytes at one path.");
+        continue;
+      }
+      const parent = dirname(asset.payload.path);
+      if (parent !== ".") await ensurePhysicalPrivateDirectoryWithin(assetRoot, parent);
+      await writePrivateFile(join(assetRoot, asset.payload.path), loaded.data);
+      writtenPaths.set(asset.payload.path, artifact.sha256);
+    }
+    const report = await reviewSpatialSceneHost(context, {
+      scene, assetRoot, request: bound.request, grant,
+      capabilityBindings: bound.capabilityBindings, browserRuntime: bound.browserRuntime,
+    }, dependencies);
+    completed = SpatialReviewOutputSchema.parse(report);
+  } catch (error) { failure = error; failed = true; }
+  finally {
+    if (directory !== undefined) try { await (dependencies.removeDirectory ?? (async path => { await rm(path, { recursive: true, force: true }); }))(directory); } catch (error) { cleanupErrors.push(error); }
+    try { await workspace.dispose(); } catch (error) { cleanupErrors.push(error); }
+  }
+  if (failed || cleanupErrors.length > 0) {
+    const cause = cleanupErrors.length === 0 ? failure : new AggregateError([...(failed ? [failure] : []), ...cleanupErrors], "Scene review failed during execution or cleanup.");
+    const error = new ApplicationError(failure instanceof ApplicationError ? failure.code : "internal",
+      cause instanceof Error ? cause.message : "Scene review failed.",
+      { cleanupErrors: cleanupErrors.map(error => error instanceof Error ? error.message : String(error)) });
+    error.cause = cause;
+    throw error;
+  }
+  if (completed === undefined) throw new ApplicationError("internal", "Scene review completed without a report.");
+  return completed;
+}
+
+export const spatialReviewOperationDefinition = {
+  kind: "scene.review", version: 1,
+  inputSchema: SpatialReviewInputSchema, inputSchemaId: "slopcamera.operation.scene.review.input/v1",
+  outputSchema: SpatialReviewOutputSchema, outputSchemaId: "slopcamera.operation.scene.review.output/v1",
+  lifecycle: { kind: "paid-dispatch", execute: executeSpatialReview },
+  policy: {
+    cache: "exact-run", cancellable: true, effect: "paid-cloud", maxDurationMs: 600_000,
+    maxFanOut: 0, maxInputBytes: 16 * 1024 * 1024, maxOutputBytes: 4 * 1024 * 1024,
+    preparation: ["local-media"], resources: [
+      { amount: 1, resource: "cpu" }, { amount: 1, resource: "local-io" }, { amount: 1, resource: "browser" },
+      { amount: 1, resource: "ffmpeg" }, { amount: 1, resource: "network" }, { amount: 1, resource: "paid-call" },
+    ], resume: "ambiguous-after-dispatch",
+  },
+  summarize: output => ({ kind: "scene.review", fields: {
+    sceneSha256: output.sceneSha256, cameraId: output.cameraId, frames: output.frames.length,
+    findings: output.findings.scene.length + output.findings.frames.reduce((sum, frame) => sum + frame.findings.length, 0),
+    model: output.model.requestedModel,
+    ...(output.model.resolvedModel === null ? {} : { resolvedModel: output.model.resolvedModel }),
+  } }),
+} satisfies OperationDefinition<"scene.review", SpatialReviewInput, SpatialReviewOutput>;

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { createBoundedJsonValueSnapshot } from "../../../../src/code/json-snapshot";
+import { SpatialAuditReportSchema, auditSpatialScene } from "../../../../src/spatial-scene/audit";
 import {
   EvaluatedSpatialSceneSchema, SpatialAssetManifestSchema, SpatialCameraSchema,
   SpatialDigestSchema, SpatialEntityIdSchema, SpatialGeneratorSchema,
@@ -17,7 +18,7 @@ export const SpatialSceneInspectionOutputSchema = z.strictObject({
     entityId: SpatialEntityIdSchema, name: z.string(),
     kind: z.enum(["group", "mesh", "image", "diagram", "video", "text", "light", "splat"]),
     origin: SpatialOriginSchema, parentId: SpatialEntityIdSchema.nullable(), placement: SpatialPlacementSchema,
-    editableControls: z.array(z.enum(["color", "opacity", "transform"])),
+    editableControls: z.array(z.enum(["color", "opacity", "transform", "emissive", "instances", "castShadow", "receiveShadow", "spot", "shadow"])),
     animatedProperties: z.array(z.string()), assetIds: z.array(z.string()),
     bounds: z.discriminatedUnion("status", [
       z.strictObject({ status: z.literal("authored-enclosure"), coordinateDomain: SpatialPlacementSchema,
@@ -44,12 +45,19 @@ export const SpatialEvaluateInputSchema = z.preprocess(capture, z.strictObject({
   scene: SpatialSceneV1Schema, timeUs: SpatialTimeUsSchema, cameraId: z.string(),
   cameraPoseOverride: SpatialPoseSchema.optional(),
 }));
+export const SpatialAuditInputSchema = z.preprocess(capture, z.strictObject({
+  scene: SpatialSceneV1Schema, cameraId: z.string(),
+  timesUs: z.array(SpatialTimeUsSchema).max(64).optional(),
+  assetBounds: z.record(z.string(), z.strictObject({ min: boundedVector, max: boundedVector })).optional(),
+}));
 export type SpatialInspectInput = z.infer<typeof SpatialInspectInputSchema>;
 export type SpatialInspectOutput = z.infer<typeof SpatialSceneInspectionOutputSchema>;
 export type SpatialPatchInput = z.infer<typeof SpatialPatchInputSchema>;
 export type SpatialPatchOutput = z.infer<typeof SpatialPatchOutputSchema>;
 export type SpatialEvaluateInput = z.infer<typeof SpatialEvaluateInputSchema>;
 export type SpatialEvaluateOutput = z.infer<typeof EvaluatedSpatialSceneSchema>;
+export type SpatialAuditInput = z.infer<typeof SpatialAuditInputSchema>;
+export type SpatialAuditOutput = z.infer<typeof SpatialAuditReportSchema>;
 
 const purePolicy = Object.freeze({
   cache: "content-addressed", cancellable: true, effect: "pure", maxDurationMs: 10_000,
@@ -95,3 +103,19 @@ export const spatialEvaluateOperationDefinition = {
   } },
   summarize: output => ({ kind: "scene.evaluate", fields: { sceneSha256: output.sceneSha256, viewSha256: output.viewSha256, timeUs: output.timeUs } }),
 } satisfies OperationDefinition<"scene.evaluate", SpatialEvaluateInput, SpatialEvaluateOutput>;
+
+export const spatialAuditOperationDefinition = {
+  kind: "scene.audit", version: 1,
+  inputSchema: SpatialAuditInputSchema, inputSchemaId: "slopcamera.operation.scene.audit.input/v1",
+  outputSchema: SpatialAuditReportSchema, outputSchemaId: "slopcamera.operation.scene.audit.output/v1",
+  policy: purePolicy,
+  lifecycle: { kind: "pure", execute: (context, input) => {
+    throwIfAborted(context.abortSignal);
+    return Promise.resolve(SpatialAuditReportSchema.parse(auditSpatialScene(input.scene, {
+      cameraId: input.cameraId,
+      ...(input.timesUs === undefined ? {} : { timesUs: input.timesUs }),
+      ...(input.assetBounds === undefined ? {} : { assetBounds: input.assetBounds }),
+    })));
+  } },
+  summarize: output => ({ kind: "scene.audit", fields: { sceneSha256: output.sceneSha256, cameraId: output.cameraId, samples: output.timesUs.length, findings: output.findings.length } }),
+} satisfies OperationDefinition<"scene.audit", SpatialAuditInput, SpatialAuditOutput>;

package/apps/desktop/application/registry.ts

@@ -125,11 +125,11 @@ function eraseDefinition<Input, Output>(
     describe: (): OperationDescription => ({
       ...discovery,
       inputJsonSchema: {
-        ...z.toJSONSchema(definition.inputSchema),
+        ...z.toJSONSchema(definition.inputSchema, { io: "input" }),
         $id: definition.inputSchemaId,
       },
       outputJsonSchema: {
-        ...z.toJSONSchema(definition.outputSchema),
+        ...z.toJSONSchema(definition.outputSchema, { io: "input" }),
         $id: definition.outputSchemaId,
       },
     }),

package/apps/desktop/application/spatial-asset-admission.ts

@@ -0,0 +1,201 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdtemp, open, realpath, rm, writeFile } from "node:fs/promises";
+import { basename, extname, isAbsolute, join, relative } from "node:path";
+
+import { z } from "zod";
+import { canonicalJson } from "../core/canonical-json";
+import { createNodeSpatialDurability } from "../core/spatial-durability";
+import { createNodeBundleFileSystem } from "../core/storage";
+import { SpatialAssetFactsV1Schema, type SpatialAssetFactsV1, type SpatialPublishedArtifact } from "../contracts/spatial-asset";
+import {
+  SpatialAssetIdSchema, SpatialAssetManifestSchema, SpatialEntitySchema,
+  type SpatialAssetManifest, type SpatialEntity, type SpatialPatchOperation,
+} from "../../../src/spatial-scene/contracts";
+import { evaluateSpatialGlb, parseSpatialGlb, spatialGlbBounds, SPATIAL_GLB_LIMITS } from "../../../src/spatial-scene/gltf";
+import { spatialAssetManifestSha256 } from "../../../src/spatial-scene/identity";
+import type { Bounds } from "../../../src/spatial-scene/math";
+
+/** Bounded data half of one admission request; effect handles stay host-side. */
+const requestSchema = z.strictObject({
+  filePath: z.string().min(1).max(4_096),
+  assetRoot: z.string().min(1).max(4_096),
+  assetId: SpatialAssetIdSchema.optional(),
+  metersPerUnit: z.number().finite().min(0.000001).max(1_000_000),
+  sourceUp: z.enum(["x", "y", "z"]),
+});
+export interface SpatialAssetAdmissionRequest {
+  readonly filePath: string;
+  readonly assetRoot: string;
+  readonly assetId?: string;
+  readonly metersPerUnit: number;
+  readonly sourceUp: "x" | "y" | "z";
+  readonly signal: AbortSignal;
+  readonly beforePublication?: () => Promise<void>;
+}
+export interface SpatialAssetAdmissionResult {
+  readonly manifest: SpatialAssetManifest;
+  readonly factsManifest: SpatialAssetManifest;
+  readonly facts: SpatialAssetFactsV1;
+  readonly bounds: { readonly modelSpace: Bounds; readonly sceneSpace: Bounds };
+  readonly entity: SpatialEntity;
+  readonly artifacts: { readonly payload: SpatialPublishedArtifact; readonly facts: SpatialPublishedArtifact };
+  readonly operations: readonly SpatialPatchOperation[];
+}
+
+/** Retained evidence survives cancellation and publication/cleanup uncertainty. */
+export class SpatialAssetAdmissionError extends Error {
+  readonly published: readonly SpatialPublishedArtifact[];
+  readonly attempted: readonly SpatialPublishedArtifact[];
+  constructor(cause: unknown, published: readonly SpatialPublishedArtifact[], attempted: readonly SpatialPublishedArtifact[] = published) {
+    super("Scene asset admission did not complete; retain its exact source and publication evidence.", { cause });
+    this.name = "SpatialAssetAdmissionError";
+    this.published = Object.freeze([...published]);
+    this.attempted = Object.freeze([...attempted]);
+  }
+}
+
+async function physicalRoot(path: string): Promise<string> {
+  if (!isAbsolute(path) || await realpath(path) !== path || !(await lstat(path)).isDirectory()) {
+    throw new RangeError("Scene asset roots must be absolute physical directories without symlinks.");
+  }
+  return path;
+}
+
+/**
+ * Capture one explicit local file exactly once: a bounded physical regular
+ * file with no symlink components, a stable inode identity across the read,
+ * and a sha256 over precisely the captured bytes.
+ */
+async function readAdmittedAssetFile(path: string, signal: AbortSignal): Promise<{ readonly bytes: Uint8Array; readonly sha256: string }> {
+  signal.throwIfAborted();
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || before.size < 1 || before.size > SPATIAL_GLB_LIMITS.bytes || await realpath(path) !== path) {
+      throw new RangeError("Admitted asset must be a bounded physical regular file without symlink components.");
+    }
+    const bytes = new Uint8Array(before.size);
+    let offset = 0;
+    while (offset < bytes.length) {
+      signal.throwIfAborted();
+      const read = await handle.read(bytes, offset, Math.min(1024 * 1024, bytes.length - offset), offset);
+      if (read.bytesRead === 0) throw new RangeError("Admitted asset was truncated while it was being read.");
+      offset += read.bytesRead;
+    }
+    const after = await handle.stat(), leaf = await lstat(path);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || before.mode !== after.mode
+      || leaf.isSymbolicLink() || leaf.dev !== after.dev || leaf.ino !== after.ino || await realpath(path) !== path) {
+      throw new RangeError("Admitted asset changed while it was captured.");
+    }
+    signal.throwIfAborted();
+    return { bytes, sha256: createHash("sha256").update(bytes).digest("hex") };
+  } finally { await handle.close(); }
+}
+
+function isGlbPayload(path: string, bytes: Uint8Array): boolean {
+  return extname(path).toLowerCase() === ".glb"
+    || (bytes.length >= 4 && bytes[0] === 0x67 && bytes[1] === 0x6c && bytes[2] === 0x54 && bytes[3] === 0x46);
+}
+
+function entityName(path: string): string {
+  const name = basename(path).replace(/\.[^.]*$/u, "").trim();
+  return name === "" ? "Admitted model" : name.slice(0, 256);
+}
+
+/**
+ * Admit one local GLB file as a scene asset. Exact source bytes are copied
+ * into the caller's content-addressed asset root, model- and scene-space
+ * bounds are derived from decoded vertex data, and the result is a subject
+ * `gltf` manifest, a sibling `metadata` facts manifest, a mesh entity, and a
+ * ready-to-apply patch fragment. Publication is atomic and no-replace:
+ * identical content-addressed bytes settle as "exists" so an interrupted
+ * admit retries deterministically, while different bytes conflict.
+ */
+export async function admitSpatialAssetFile(options: SpatialAssetAdmissionRequest): Promise<SpatialAssetAdmissionResult> {
+  const parsed = requestSchema.safeParse({
+    filePath: options.filePath, assetRoot: options.assetRoot, assetId: options.assetId,
+    metersPerUnit: options.metersPerUnit, sourceUp: options.sourceUp,
+  });
+  if (!parsed.success) throw new RangeError("Scene asset admission request is invalid.");
+  const request = parsed.data;
+  options.signal.throwIfAborted();
+  if (!isAbsolute(request.filePath)) throw new RangeError("Admitted asset paths must resolve to absolute local files.");
+  const root = await physicalRoot(request.assetRoot);
+  const { bytes, sha256 } = await readAdmittedAssetFile(request.filePath, options.signal);
+  if (!isGlbPayload(request.filePath, bytes)) {
+    throw new RangeError(`scene asset admit currently admits GLB 2.0 payloads: ${basename(request.filePath)} is not a .glb file and lacks the glTF magic.`);
+  }
+  const model = parseSpatialGlb(bytes);
+  const modelSpace = spatialGlbBounds(model);
+  const sceneSpace = evaluateSpatialGlb(model, { metersPerUnit: request.metersPerUnit, sourceUp: request.sourceUp, timeUs: 0 }).bounds;
+  const assetId = request.assetId ?? `asset_admitted_${sha256}`;
+  const entityId = `entity_admitted_${sha256}`;
+  const payload = { path: `assets/${sha256}.glb`, sha256, bytes: bytes.byteLength };
+  const manifest = SpatialAssetManifestSchema.parse({
+    assetId, payload,
+    interpretation: { kind: "gltf", format: "glb", metersPerUnit: request.metersPerUnit, sourceUp: request.sourceUp },
+    dependencies: [],
+    provenance: { source: "imported", description: `Admitted local GLB payload ${basename(request.filePath)}.` },
+  });
+  const facts = SpatialAssetFactsV1Schema.parse({
+    kind: "slopcamera.spatial-asset-facts", schemaVersion: 1,
+    subject: payload, subjectManifestSha256: spatialAssetManifestSha256(manifest),
+    profile: model.profile, nodeCount: model.nodeCount, clipDurationsSeconds: [...model.clipDurationsSeconds],
+    bounds: { modelSpace, sceneSpace },
+    materials: model.materialFacts.map(fact => ({ ...fact })),
+    ...(model.rigFacts === undefined ? {} : { rig: model.rigFacts }),
+  });
+  const factsText = `${canonicalJson(facts)}\n`, factsSha256 = createHash("sha256").update(factsText).digest("hex");
+  const factsPayload = { path: `assets/${factsSha256}.json`, sha256: factsSha256, bytes: Buffer.byteLength(factsText) };
+  const factsManifest = SpatialAssetManifestSchema.parse({
+    assetId: `asset_facts_${factsSha256}`, payload: factsPayload,
+    interpretation: { kind: "metadata", format: "json", schema: "slopcamera.spatial-asset-facts" },
+    dependencies: [assetId],
+    provenance: { source: "derived", description: `Derived bounds and profile facts for ${assetId}.` },
+  });
+  if (factsManifest.assetId === assetId) throw new RangeError("Requested asset identity conflicts with the derived facts asset.");
+  const entity = SpatialEntitySchema.parse({
+    entityId, kind: "mesh", name: entityName(request.filePath), parentId: null,
+    transform: { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] },
+    placement: { kind: "world" }, origin: { kind: "authored" }, visible: true,
+    geometry: { kind: "asset", assetId },
+    material: { kind: "standard", color: "#cccccc", opacity: 1, roughness: 1, metalness: 0 },
+  });
+  const fileSystem = createNodeBundleFileSystem(root), durability = createNodeSpatialDurability(root);
+  const published: SpatialPublishedArtifact[] = [];
+  const attempted: SpatialPublishedArtifact[] = [];
+  const fence = async () => { options.signal.throwIfAborted(); await options.beforePublication?.(); options.signal.throwIfAborted(); };
+  await fence();
+  const workspace = await mkdtemp(join(root, ".slopcamera-asset-admit-"));
+  let result: SpatialAssetAdmissionResult | undefined, failure: { error: unknown } | undefined;
+  try {
+    const staged = join(workspace, `${sha256}.glb`);
+    await writeFile(staged, bytes, { flag: "wx", mode: 0o600 });
+    attempted.push({ ...payload, disposition: "created" });
+    const payloadDisposition = await fileSystem.copyFileNoReplace!(relative(root, staged), payload.path, payload, fence);
+    published.push({ ...payload, disposition: payloadDisposition });
+    await durability.syncExactFile(payload.path, payload);
+    attempted.push({ ...factsPayload, disposition: "created" });
+    const factsDisposition = await fileSystem.writeTextNoReplace!(factsPayload.path, factsText, fence);
+    published.push({ ...factsPayload, disposition: factsDisposition });
+    await durability.syncExactFile(factsPayload.path, factsPayload);
+    const operations: SpatialPatchOperation[] = [
+      { kind: "add-asset", asset: manifest },
+      { kind: "add-asset", asset: factsManifest },
+      { kind: "add-entity", entity },
+    ];
+    result = {
+      manifest, factsManifest, facts, entity, operations,
+      bounds: { modelSpace, sceneSpace },
+      artifacts: { payload: published[0]!, facts: published[1]! },
+    };
+  } catch (error) { failure = { error }; }
+  finally {
+    try { await rm(workspace, { recursive: true, force: true }); }
+    catch (error) { failure = { error: failure === undefined ? error : new AggregateError([failure.error, error], "Scene asset admission and workspace cleanup failed.") }; }
+  }
+  if (failure !== undefined) throw new SpatialAssetAdmissionError(failure.error, published, attempted);
+  if (result === undefined) throw new SpatialAssetAdmissionError(new Error("Scene asset admission did not settle."), published, attempted);
+  return result;
+}