@hraness/slopcamera 3.2.7 → 3.3.1

package/apps/desktop/cli/spatial-design-service.ts

@@ -0,0 +1,237 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath, unlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { z } from "zod";
+import { createSha256HexHasher } from "../../../src/code/sha256";
+import { SlopcameraCodeError } from "../../../src/code/errors";
+import { compileSpatialDesign, editSpatialDesignParameters, inspectSpatialDesign } from "../../../src/spatial-scene/design";
+import { createSpatialDesignStarter, listSpatialDesignTemplates } from "../../../src/spatial-scene/design-templates";
+import { parseSpatialScene, parseSpatialValue, spatialSceneSha256, spatialValueSha256 } from "../../../src/spatial-scene/identity";
+import type { SpatialSceneV1 } from "../../../src/spatial-scene/contracts";
+import type { ApplicationContext } from "../application/context";
+import { createNodeBundleFileSystem } from "../core/storage";
+import type { SpatialDesignCommand } from "./args";
+import { CliError } from "./errors";
+import { ensurePhysicalPrivateDirectoryWithin, resolveSafePath } from "./paths";
+import { publishSpatialSource, readSpatialJson } from "./spatial-scene-service";
+
+const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
+const MAX_GALLERY_BYTES = 128 * 1024 * 1024;
+const ParametersSchema = z.record(z.string().min(1).max(64), z.number().finite()).refine(value => Object.keys(value).length <= 128, "At most 128 parameter updates are allowed.");
+export const SpatialDesignVariantsSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-design-variants"), schemaVersion: z.literal(1),
+  variants: z.array(z.strictObject({
+    id: z.string().min(1).max(48).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u),
+    label: z.string().min(1).max(120), parameters: ParametersSchema,
+  })).min(1).max(6),
+}).superRefine((value, context) => {
+  if (new Set(value.variants.map(variant => variant.id)).size !== value.variants.length) context.addIssue({ code: "custom", message: "Variant IDs must be unique." });
+});
+
+type Compilation = ReturnType<typeof compileSpatialDesign>;
+type CapturedAsset = Readonly<{ path: string; bytes: Uint8Array }>;
+
+function inspectionSummary(input: unknown): unknown {
+  const report = inspectSpatialDesign(input);
+  return { designId: report.design.designId, name: report.design.name, designSha256: report.designSha256,
+    parameters: report.design.parameters, values: report.values, valueOrder: report.valueOrder,
+    constraints: report.constraints, estimate: report.estimate,
+    stages: report.stages.map(({ spec: _spec, ...stage }) => stage) };
+}
+
+function digest(bytes: Uint8Array): string {
+  const hasher = createSha256HexHasher(); hasher.update(bytes); return hasher.digestHex();
+}
+
+async function captureAsset(sourceRoot: string, path: string, expected: { bytes: number; sha256: string }): Promise<CapturedAsset> {
+  const absolute = resolve(sourceRoot, path);
+  if (absolute !== await realpath(absolute)) throw new CliError("unsafe-path", "Design assets must have physical paths without symlinks.");
+  const handle = await open(absolute, 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) || expected.bytes > MAX_BUNDLE_BYTES) throw new CliError("invalid-data", `Design asset size differs: ${path}`);
+    const bytes = new Uint8Array(expected.bytes);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const result = await handle.read(bytes, offset, Math.min(262144, bytes.length - offset), offset);
+      if (result.bytesRead === 0) throw new CliError("conflict", `Design asset changed: ${path}`);
+      offset += result.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    if (before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs || digest(bytes) !== expected.sha256) throw new CliError("conflict", `Design asset identity differs: ${path}`);
+    return { path, bytes };
+  } finally { await handle.close(); }
+}
+
+/** Capture only the assets still referenced by the compiled scene, including base-scene dependencies. */
+async function captureCompilation(compilation: Compilation, sourceRoot: string | undefined): Promise<readonly CapturedAsset[]> {
+  const emitted = new Map(compilation.outputs.flatMap(output => output.artifacts).map(artifact => [artifact.assetId, artifact]));
+  const seen = new Map<string, { path: string; sha256: string; bytes: number }>();
+  let total = 0;
+  const assets: CapturedAsset[] = [];
+  for (const asset of compilation.scene.assets) {
+    const { path, bytes, sha256 } = asset.payload;
+    const pathKey = path.normalize("NFC").toLowerCase();
+    if (["design.json", "scene.json", "receipt.json", "render.json", "gallery.json", "base.scene.json"].some(reserved => pathKey === reserved || pathKey.startsWith(`${reserved}/`))) throw new CliError("conflict", `Asset uses a reserved bundle path: ${path}`);
+    const prior = seen.get(pathKey);
+    if (prior !== undefined) {
+      if (prior.sha256 !== sha256 || prior.bytes !== bytes || prior.path !== path) throw new CliError("conflict", `Asset paths have conflicting identities: ${path}`);
+      continue;
+    }
+    for (const existing of seen.keys()) if (pathKey.startsWith(`${existing}/`) || existing.startsWith(`${pathKey}/`)) throw new CliError("conflict", `Asset file and directory paths collide: ${path}`);
+    seen.set(pathKey, { path, sha256, bytes });
+    total += bytes;
+    if (total > MAX_BUNDLE_BYTES) throw new CliError("invalid-data", "Design bundle exceeds 64 MiB.");
+    const generated = emitted.get(asset.assetId);
+    if (generated !== undefined) {
+      if (generated.path !== path || generated.bytes.byteLength !== bytes || digest(generated.bytes) !== sha256) throw new CliError("invalid-data", "Generated design asset identity differs.");
+      assets.push({ path, bytes: generated.bytes });
+    } else {
+      if (sourceRoot === undefined) throw new CliError("invalid-data", "A base scene with retained assets requires --scene.");
+      assets.push(await captureAsset(sourceRoot, path, asset.payload));
+    }
+  }
+  return assets;
+}
+
+async function reserveDirectory(root: string, requested: string, fence: () => Promise<void>): Promise<string> {
+  const target = await resolveSafePath(root, requested);
+  if (target === root) throw new CliError("unsafe-path", "Design output must be a new directory below the workspace.");
+  const parent = relative(root, dirname(target));
+  if (parent !== "") await ensurePhysicalPrivateDirectoryWithin(root, parent);
+  await fence();
+  // The custody callback may yield; validate physical parents again afterwards.
+  await resolveSafePath(root, requested);
+  if (parent !== "") await ensurePhysicalPrivateDirectoryWithin(root, parent);
+  try { await mkdir(target, { mode: 0o700 }); }
+  catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "EEXIST") throw new CliError("conflict", "Design output already exists. Choose a new directory to preserve all revisions.");
+    throw error;
+  }
+  return target;
+}
+
+async function publishBytes(root: string, asset: CapturedAsset, fence: () => Promise<void>): Promise<void> {
+  const folder = dirname(asset.path);
+  const directory = folder === "." ? root : await ensurePhysicalPrivateDirectoryWithin(root, folder);
+  const path = join(directory, basename(asset.path));
+  const temporary = join(directory, `.design-${randomUUID()}.tmp`);
+  const handle = await open(temporary, "wx", 0o600);
+  try {
+    await handle.writeFile(asset.bytes); await handle.sync();
+  } finally { await handle.close(); }
+  try {
+    const fileSystem = createNodeBundleFileSystem(root);
+    // The storage boundary rechecks staging bytes and physical parents after
+    // the custody callback and publishes by a guarded no-replace hard link.
+    const result = await fileSystem.copyFileNoReplace!(relative(root, temporary), relative(root, path),
+      { bytes: asset.bytes.byteLength, sha256: digest(asset.bytes) }, fence).catch((error: unknown) => {
+        if (error instanceof Error && !(error instanceof CliError) && !("code" in error)) throw new CliError("conflict", error.message);
+        throw error;
+      });
+    if (result !== "created") throw new CliError("conflict", "Design asset output already exists.");
+  } finally { await unlink(temporary); }
+}
+
+async function publishCompilation(root: string, compilation: Compilation, assets: readonly CapturedAsset[], fence: () => Promise<void>): Promise<unknown> {
+  for (const asset of assets) await publishBytes(root, asset, fence);
+  await publishSpatialSource(join(root, "design.json"), compilation.design, fence);
+  await publishSpatialSource(join(root, "scene.json"), compilation.scene, fence);
+  const cameraId = compilation.scene.cameras.find(camera => camera.cameraId === "camera_hero")?.cameraId ?? compilation.scene.cameras[0]?.cameraId;
+  if (cameraId !== undefined) await publishSpatialSource(join(root, "render.json"), { cameraId, selection: { kind: "frame", timeUs: 0 }, mode: { kind: "beauty" } }, fence);
+  const receipt = {
+    kind: "slopcamera.spatial-design-bundle", schemaVersion: 1,
+    compilation: compilation.receipt, compilationSha256: compilation.receiptSha256,
+    stages: compilation.outputs.map(output => ({ receipt: output.receipt, receiptSha256: output.receiptSha256 })),
+    sceneSha256: spatialSceneSha256(compilation.scene),
+    files: assets.map(asset => ({ path: asset.path, bytes: asset.bytes.byteLength, sha256: digest(asset.bytes) })),
+  };
+  await publishSpatialSource(join(root, "receipt.json"), receipt, fence);
+  return { directory: root, scene: join(root, "scene.json"), design: join(root, "design.json"), receipt: join(root, "receipt.json"),
+    receiptSha256: spatialValueSha256(receipt), sceneSha256: receipt.sceneSha256,
+    ...(cameraId === undefined ? {} : { renderRequest: join(root, "render.json") }),
+    stages: compilation.outputs.length, assets: assets.length };
+}
+
+async function executeDesign(application: ApplicationContext, command: SpatialDesignCommand, signal?: AbortSignal): Promise<unknown> {
+  const root = application.paths.repositoryRoot;
+  const fence = async () => { signal?.throwIfAborted(); await application.hostResourceLease?.assertOwned(); signal?.throwIfAborted(); };
+  await fence();
+  if (command.action === "catalog") return { templates: listSpatialDesignTemplates() };
+  if (command.action === "init") {
+    const starter = createSpatialDesignStarter(command.template);
+    inspectSpatialDesign(starter.design);
+    const directory = await reserveDirectory(root, command.directory, fence);
+    await publishSpatialSource(join(directory, "design.json"), starter.design, fence);
+    await publishSpatialSource(join(directory, "base.scene.json"), starter.scene, fence);
+    return { directory, design: join(directory, "design.json"), scene: join(directory, "base.scene.json"), template: command.template };
+  }
+  const design = await readSpatialJson(resolve(root, command.path));
+  if (command.action === "inspect") return inspectionSummary(design);
+  if (command.action === "set") {
+    const parameters = parseSpatialValue(ParametersSchema, await readSpatialJson(resolve(root, command.parameters), 65536), "design parameter updates");
+    const edited = editSpatialDesignParameters(design, parameters);
+    const output = await resolveSafePath(root, command.output);
+    const folder = relative(root, dirname(output));
+    if (folder !== "") await ensurePhysicalPrivateDirectoryWithin(root, folder);
+    await publishSpatialSource(output, edited, fence);
+    return { path: output, inspection: inspectionSummary(edited) };
+  }
+  const scenePath = command.scene === undefined ? undefined : resolve(root, command.scene);
+  const scene: SpatialSceneV1 | undefined = scenePath === undefined ? undefined : parseSpatialScene(await readSpatialJson(scenePath));
+  const options = scene === undefined ? {} : { scene };
+  const sourceRoot = scenePath === undefined ? undefined : await realpath(dirname(scenePath));
+  if (command.action === "compile") {
+    const compilation = compileSpatialDesign(design, options);
+    const assets = await captureCompilation(compilation, sourceRoot);
+    const directory = await reserveDirectory(root, command.outputDir, fence);
+    return await publishCompilation(directory, compilation, assets, fence);
+  }
+  const variants = parseSpatialValue(SpatialDesignVariantsSchema, await readSpatialJson(resolve(root, command.variants), 65536), "design variants");
+  // Inspect every candidate before emitting any geometry or publishing a directory.
+  const designs = variants.variants.map(variant => editSpatialDesignParameters(design, variant.parameters));
+  let estimatedBytes = 0;
+  for (const candidate of designs) {
+    const inspection = inspectSpatialDesign(candidate);
+    estimatedBytes += inspection.estimate.bytes;
+    if (estimatedBytes > MAX_GALLERY_BYTES) throw new CliError("invalid-data", "Design gallery exceeds 128 MiB of estimated output.");
+  }
+  const compiled = [];
+  let total = 0;
+  for (let index = 0; index < designs.length; index++) {
+    await fence();
+    const compilation = compileSpatialDesign(designs[index], options);
+    const assets = await captureCompilation(compilation, sourceRoot);
+    total += assets.reduce((sum, asset) => sum + asset.bytes.byteLength, 0);
+    if (total > MAX_GALLERY_BYTES) throw new CliError("invalid-data", "Design gallery exceeds 128 MiB.");
+    compiled.push({ variant: variants.variants[index]!, compilation, assets });
+  }
+  const directory = await reserveDirectory(root, command.outputDir, fence);
+  const rows = [];
+  for (const { variant, compilation, assets } of compiled) {
+    const child = await reserveDirectory(directory, variant.id, fence);
+    const bundle = await publishCompilation(child, compilation, assets, fence);
+    rows.push({ ...variant, bundle });
+  }
+  const gallery = { kind: "slopcamera.spatial-design-gallery", schemaVersion: 1, rendered: false, variants: rows };
+  await publishSpatialSource(join(directory, "gallery.json"), gallery, fence);
+  return { directory, gallery: join(directory, "gallery.json"), variants: rows, rendered: false,
+    sourceSha256: spatialValueSha256(design) };
+}
+
+export async function executeSpatialDesignCommand(application: ApplicationContext, command: SpatialDesignCommand, signal?: AbortSignal): Promise<unknown> {
+  try { return await executeDesign(application, command, signal); }
+  catch (error) {
+    if (error instanceof CliError) throw error;
+    if (signal?.aborted) throw new CliError("cancelled", "Design command was cancelled; retain any partial bundle.");
+    if (error instanceof SlopcameraCodeError) throw new CliError(error.code, error.message, error.details);
+    if (error instanceof SyntaxError) throw new CliError("invalid-data", "Design input must be valid UTF-8 JSON.");
+    if (error instanceof Error && "code" in error) {
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") throw new CliError("not-found", "Design source, asset, or output parent does not exist.");
+      if (error.code === "ELOOP") throw new CliError("unsafe-path", "Design inputs and outputs must use physical paths without symlinks.");
+      if (error.code === "EEXIST") throw new CliError("conflict", "Design output already exists; choose a new path.");
+    }
+    throw error;
+  }
+}

package/apps/desktop/cli/spatial-generate-service.ts

@@ -0,0 +1,370 @@
+import { constants } from "node:fs";
+import { mkdir, open, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createSha256HexHasher } from "../../../src/code/sha256";
+import {
+  buildSpatialGeneratorRecord,
+  deriveSpatialGeneratorSeed,
+  generatedSpatialEntityId,
+  mergeSpatialGeneratorOutput,
+  parseSpatialGeneratorParameters,
+  parseSpatialScene,
+  SPATIAL_GENERATOR_LIMITS,
+  spatialGeneratorParametersSha256,
+  spatialSceneSha256,
+  SpatialGeneratorIdSchema,
+  validateSpatialGeneratorOutput,
+} from "../../../src/spatial-scene/index";
+import { canonicalJsonSha256, sha256Hex } from "../core/canonical-json";
+import type { ApplicationContext } from "../application/context";
+import type { SpatialSceneCommand } from "./args";
+import { CliError, errorMessage } from "./errors";
+import { publishSpatialSource, readSpatialJson } from "./spatial-scene-service";
+
+/**
+ * Capture an explicit local generator file once: a bounded regular file
+ * pinned by descriptor stat before and after the read, never a symlink leaf.
+ */
+async function readGeneratorModuleBytes(path: string, label: string): Promise<Uint8Array> {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK)
+    .catch((error: NodeJS.ErrnoException) => {
+      if (error.code === "ELOOP") throw new CliError("invalid-data", `${label} must be a real file, not a symlink.`);
+      if (error.code === "ENOENT" || error.code === "ENOTDIR") throw new CliError("not-found", `${label} does not exist.`);
+      throw error;
+    });
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.size === 0n || before.size > BigInt(SPATIAL_GENERATOR_LIMITS.moduleSourceBytes)) {
+      throw new CliError("invalid-data", `${label} must be a nonempty bounded regular file.`);
+    }
+    const bytes = new Uint8Array(Number(before.size));
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+      const read = await handle.read(bytes, offset, bytes.byteLength - offset, offset);
+      if (read.bytesRead === 0) throw new CliError("conflict", `${label} ended while it was being read.`);
+      offset += read.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    if (after.size !== before.size || after.ino !== before.ino || after.mtimeNs !== before.mtimeNs || after.ctimeNs !== before.ctimeNs) {
+      throw new CliError("conflict", `${label} changed while it was being read.`);
+    }
+    return bytes;
+  } finally { await handle.close(); }
+}
+
+/**
+ * One verified real file in the generator closure. realPath is the canonical
+ * dedupe and containment identity and the verified-read target; relativePath
+ * is the POSIX manifest key and the staged location below the module root.
+ */
+interface GeneratorClosureFile {
+  readonly realPath: string;
+  readonly relativePath: string;
+  readonly bytes: Uint8Array;
+}
+
+interface GeneratorModuleClosure {
+  readonly files: readonly GeneratorClosureFile[];
+  readonly entryRelativePath: string;
+  readonly sourceSha256: string;
+  readonly closureSha256: string;
+}
+
+/**
+ * Closure bounds: at most 64 real files whose verified bytes together stay
+ * inside the pre-existing per-module ceiling (1 MiB), so hashing, staging,
+ * and module loading remain cheap. A single-file module therefore keeps its
+ * exact prior acceptance range.
+ */
+const GENERATOR_MODULE_CLOSURE_LIMITS = Object.freeze({
+  files: 64,
+  totalBytes: SPATIAL_GENERATOR_LIMITS.moduleSourceBytes,
+});
+
+/** The transpiler loader for a scanned member, or undefined for data (.json) files that carry no imports. */
+function generatorModuleLoader(relativePath: string): "ts" | "js" | undefined {
+  if (relativePath.endsWith(".ts")) return "ts";
+  if (relativePath.endsWith(".js")) return "js";
+  return undefined;
+}
+
+function generatorModuleLabel(entry: GeneratorClosureFile, file: GeneratorClosureFile): string {
+  return file === entry ? "Generator module" : `Generator dependency "${file.relativePath}"`;
+}
+
+function decodeGeneratorModuleSource(file: GeneratorClosureFile, label: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(file.bytes);
+  } catch {
+    throw new CliError("invalid-data", `${label} must be UTF-8 TypeScript/JavaScript source.`);
+  }
+}
+
+function sha256BytesHex(bytes: Uint8Array): string {
+  const hasher = createSha256HexHasher();
+  hasher.update(bytes);
+  return hasher.digestHex();
+}
+
+/**
+ * Source forms the static closure cannot see are rejected in every file:
+ * require()/require.resolve(), dynamic import(), and the Bun import.meta
+ * facilities that mint module references at runtime.
+ */
+function assertClosureVisibleModuleForms(source: string, label: string): void {
+  if (/\brequire(?:\s*\.\s*resolve)?\s*\(/u.test(source)) {
+    throw new CliError("invalid-data", `${label} must be ESM; require() escapes the retained closure digest.`);
+  }
+  if (/(?<![\w$.])import\s*\(/u.test(source)) {
+    throw new CliError("invalid-data", `${label} uses dynamic import(), which escapes the retained closure digest.`);
+  }
+  if (/\bimport\s*\.\s*meta\s*\.\s*(?:glob|resolve|require)\b/u.test(source)) {
+    throw new CliError("invalid-data", `${label} uses import.meta glob/resolve/require, which escapes the retained closure digest.`);
+  }
+}
+
+function isRelativeModuleSpecifier(specifier: string): boolean {
+  return specifier === "." || specifier === ".." || specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+/** Absolute filesystem specifiers, including drive-letter, UNC, and file: URL forms. */
+function isAbsoluteModuleSpecifier(specifier: string): boolean {
+  return specifier.startsWith("/") || specifier.startsWith("\\")
+    || /^[a-zA-Z]:/u.test(specifier) || specifier.toLowerCase().startsWith("file:");
+}
+
+/**
+ * Resolution candidates mirroring Bun's file-then-index probing, restricted
+ * to the code/data extensions the closure admits; `.js` also probes the
+ * TypeScript `.ts` spelling because the runtime resolves that way.
+ */
+function generatorModuleSpecifierCandidates(resolved: string, specifier: string): readonly string[] {
+  if (resolved.endsWith(".ts") || resolved.endsWith(".json")) return [resolved];
+  if (resolved.endsWith(".js")) return [resolved, `${resolved.slice(0, -3)}.ts`];
+  if (extname(resolved) !== "") {
+    throw new CliError("invalid-data", `Generator import "${specifier}" must target a .ts, .js, or .json file inside the module directory.`);
+  }
+  if (specifier.endsWith("/") || specifier === "." || specifier === "..") {
+    return [join(resolved, "index.ts"), join(resolved, "index.js"), join(resolved, "index.json")];
+  }
+  return [`${resolved}.ts`, `${resolved}.js`, `${resolved}.json`,
+    join(resolved, "index.ts"), join(resolved, "index.js"), join(resolved, "index.json")];
+}
+
+async function realpathIfPresent(candidate: string, specifier: string): Promise<string | undefined> {
+  try {
+    return await realpath(candidate);
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+    if (code === "ELOOP") {
+      throw new CliError("invalid-data", `Generator import "${specifier}" resolves through a symlink; generator modules must be a real file tree.`);
+    }
+    throw error;
+  }
+}
+
+/**
+ * BFS over the transitive relative-import graph so the retained closureSha256
+ * covers the complete real file set. The module root is the entry file's real
+ * directory; every resolved file must stay inside it, must be a real
+ * (non-symlink) regular file, and gets the same verified read as the entry.
+ * Erased `import type`/`export type` entries carry no runtime dependency and
+ * are allowed; bare package specifiers (including node:/bun: builtins) resolve
+ * ambient dependencies the digests do not cover — a documented prototype gap
+ * unchanged from single-file mode.
+ */
+async function resolveGeneratorModuleClosure(modulePath: string): Promise<GeneratorModuleClosure> {
+  const entryBytes = await readGeneratorModuleBytes(modulePath, "Generator module");
+  let entryRealPath: string;
+  try {
+    entryRealPath = await realpath(modulePath);
+  } catch {
+    throw new CliError("not-found", "Generator module does not resolve to a real file.");
+  }
+  const rootReal = dirname(entryRealPath);
+  const entry: GeneratorClosureFile = { realPath: entryRealPath, relativePath: basename(entryRealPath), bytes: entryBytes };
+  if (generatorModuleLoader(entry.relativePath) === undefined) {
+    throw new CliError("invalid-data", "Generator module must be a .ts or .js file.");
+  }
+  const files: GeneratorClosureFile[] = [entry];
+  const seen = new Set([entry.realPath]);
+  const queue = [entry];
+  let totalBytes = entry.bytes.byteLength;
+
+  const resolveImport = async (importer: GeneratorClosureFile, specifier: string): Promise<string> => {
+    const resolved = resolve(dirname(importer.realPath), specifier);
+    for (const candidate of generatorModuleSpecifierCandidates(resolved, specifier)) {
+      const real = await realpathIfPresent(candidate, specifier);
+      if (real === undefined) continue;
+      const contained = relative(rootReal, real);
+      if (contained === "" || contained === ".." || contained.startsWith(`..${sep}`) || isAbsolute(contained)) {
+        throw new CliError("invalid-data", `Generator import "${specifier}" escapes the generator module directory.`);
+      }
+      if (real !== candidate && real.toLowerCase() !== candidate.toLowerCase()) {
+        throw new CliError("invalid-data", `Generator import "${specifier}" resolves through a symlink; generator modules must be a real file tree.`);
+      }
+      return real;
+    }
+    throw new CliError("not-found", `Generator import "${specifier}" does not resolve to a .ts, .js, or .json file below the module directory.`);
+  };
+
+  while (queue.length > 0) {
+    const importer = queue.shift()!;
+    const loader = generatorModuleLoader(importer.relativePath);
+    if (loader === undefined) continue; // data files carry no further imports
+    const label = generatorModuleLabel(entry, importer);
+    const source = decodeGeneratorModuleSource(importer, label);
+    assertClosureVisibleModuleForms(source, label);
+    for (const scanned of new Bun.Transpiler({ loader }).scan(source).imports) {
+      if (scanned.kind === "dynamic-import") {
+        throw new CliError("invalid-data", `${label} uses dynamic import(), which escapes the retained closure digest.`);
+      }
+      const specifier = scanned.path;
+      if (isAbsoluteModuleSpecifier(specifier)) {
+        throw new CliError("invalid-data", `Generator import "${specifier}" is absolute; only relative imports inside the module directory are allowed.`);
+      }
+      if (!isRelativeModuleSpecifier(specifier)) continue; // ambient bare specifier — documented gap
+      const real = await resolveImport(importer, specifier);
+      if (seen.has(real)) continue;
+      const relativePath = relative(rootReal, real).split(sep).join("/");
+      const bytes = await readGeneratorModuleBytes(real, `Generator dependency "${relativePath}"`);
+      const file: GeneratorClosureFile = { realPath: real, relativePath, bytes };
+      files.push(file);
+      seen.add(real);
+      queue.push(file);
+      totalBytes += bytes.byteLength;
+      if (files.length > GENERATOR_MODULE_CLOSURE_LIMITS.files) {
+        throw new CliError("invalid-data", `Generator module closure exceeds ${GENERATOR_MODULE_CLOSURE_LIMITS.files} files.`);
+      }
+      if (totalBytes > GENERATOR_MODULE_CLOSURE_LIMITS.totalBytes) {
+        throw new CliError("invalid-data", `Generator module closure exceeds ${GENERATOR_MODULE_CLOSURE_LIMITS.totalBytes} total bytes.`);
+      }
+    }
+  }
+
+  const manifest = files
+    .map(file => ({ relativePath: file.relativePath, sha256: sha256BytesHex(file.bytes) }))
+    .sort((left, right) => left.relativePath < right.relativePath ? -1 : left.relativePath > right.relativePath ? 1 : 0);
+  const sourceSha256 = sha256BytesHex(entry.bytes);
+  // Single-file modules keep closureSha256 == sourceSha256 exactly, so the
+  // retained record is byte-identical to the pre-closure behavior.
+  const closureSha256 = files.length === 1 ? sourceSha256 : canonicalJsonSha256(manifest);
+  return { files, entryRelativePath: entry.relativePath, sourceSha256, closureSha256 };
+}
+
+async function directoryExists(path: string): Promise<boolean> {
+  return stat(path).then(result => result.isDirectory()).catch(() => false);
+}
+
+/**
+ * The closure executes from a private content-addressed tree mirroring the
+ * module's relative structure, so the code that runs is exactly the bytes the
+ * retained digests describe. Plain-path imports would return stale modules
+ * from the in-process registry after any member file changed.
+ */
+async function stageGeneratorModuleTree(privateRoot: string, closure: GeneratorModuleClosure): Promise<string> {
+  const directory = join(privateRoot, "scene-generator-modules");
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const staged = join(directory, closure.closureSha256);
+  const stagedEntry = join(staged, ...closure.entryRelativePath.split("/"));
+  if (await directoryExists(staged)) return stagedEntry;
+  const temporary = join(directory, `.${closure.closureSha256}.${process.pid}.tmp`);
+  await rm(temporary, { recursive: true, force: true });
+  try {
+    for (const file of closure.files) {
+      const target = join(temporary, ...file.relativePath.split("/"));
+      await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+      await writeFile(target, file.bytes, { mode: 0o600 });
+    }
+    await rename(temporary, staged);
+  } catch (error) {
+    await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+    if (await directoryExists(staged)) return stagedEntry; // a concurrent invocation staged identical content
+    throw error;
+  }
+  return stagedEntry;
+}
+
+export type SpatialGenerateCommand = Extract<SpatialSceneCommand, { readonly action: "generate" }>;
+
+/**
+ * Executes a trusted current-user generator module — the same trust class as an
+ * explicitly imported workflow module, with no sandbox claim — then stamps
+ * generated identity, validates bounded output, records attempt provenance and
+ * merges through replace-generator-output semantics.
+ */
+export async function executeSpatialGenerateCommand(
+  application: ApplicationContext,
+  command: SpatialGenerateCommand,
+): Promise<unknown> {
+  const parsedGeneratorId = SpatialGeneratorIdSchema.safeParse(command.generatorId);
+  if (!parsedGeneratorId.success) {
+    throw new CliError("invalid-data", "--generator-id must match generator_<alphanumeric> (1–128 characters).");
+  }
+  const generatorId = parsedGeneratorId.data;
+  const modulePath = resolve(application.paths.repositoryRoot, command.module);
+  const closure = await resolveGeneratorModuleClosure(modulePath);
+  const { sourceSha256, closureSha256 } = closure;
+  const stagedPath = await stageGeneratorModuleTree(application.paths.privateRoot, closure);
+
+  const parameters = command.parameters === undefined
+    ? {}
+    : parseSpatialGeneratorParameters(
+      await readSpatialJson(resolve(application.paths.repositoryRoot, command.parameters), SPATIAL_GENERATOR_LIMITS.parametersBytes));
+  const parametersSha256 = spatialGeneratorParametersSha256(parameters);
+  const seed = command.seed ?? deriveSpatialGeneratorSeed(sourceSha256);
+
+  let loaded: unknown;
+  try {
+    loaded = await import(pathToFileURL(stagedPath).href);
+  } catch (error) {
+    throw new CliError("invalid-data", `Generator module failed to load: ${errorMessage(error)}`);
+  }
+  const generate = (loaded as Readonly<Record<string, unknown>>).generate;
+  if (typeof generate !== "function") {
+    throw new CliError("invalid-data", 'Generator module must export a "generate" function.');
+  }
+  const context = Object.freeze({
+    seed,
+    parameters,
+    lib: Object.freeze({ entityId: (key: string) => generatedSpatialEntityId(generatorId, key) }),
+  });
+  let raw: unknown;
+  try {
+    raw = await (generate as (context: unknown) => unknown)(context);
+  } catch (error) {
+    throw new CliError("invalid-data", `Generator module failed: ${errorMessage(error)}`);
+  }
+
+  const output = validateSpatialGeneratorOutput(generatorId, raw);
+  const runtimeSha256 = sha256Hex(Bun.version);
+  const generator = buildSpatialGeneratorRecord({
+    generatorId,
+    sourceSha256,
+    closureSha256,
+    parametersSha256,
+    seed,
+    runtimeSha256,
+    entities: output.entities,
+    editableKeys: output.editableKeys,
+  });
+  const into = command.into === undefined
+    ? undefined
+    : parseSpatialScene(await readSpatialJson(resolve(application.paths.repositoryRoot, command.into)));
+  const scene = mergeSpatialGeneratorOutput(into, generator, output.entities);
+  const outputPath = resolve(application.paths.repositoryRoot, command.output);
+  await publishSpatialSource(outputPath, scene);
+  return {
+    path: outputPath,
+    sceneSha256: spatialSceneSha256(scene),
+    generatorId,
+    seed,
+    entities: output.entities.length,
+    outputSha256: generator.outputSha256,
+    sourceSha256,
+    attemptId: generator.execution.kind === "attempt" ? generator.execution.attemptId : undefined,
+    merged: into !== undefined,
+  };
+}