@prismatic-io/lux 0.0.1

package/src/core/artifact-evidence.ts

@@ -0,0 +1,249 @@
+import type { Stats } from "node:fs";
+import { constants, lstat, open } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import type { Artifact } from "./driver.js";
+import type { Run } from "./run.js";
+
+const DEFAULT_ARTIFACT_READ_BYTES = 5 * 1024 * 1024;
+const MAX_ARTIFACT_READ_BYTES = 10 * 1024 * 1024;
+
+export type RunArtifactInspection = {
+  target: string;
+  root: string;
+  artifact?: Artifact;
+  stats?: Stats;
+  issue?: string;
+};
+
+type RunArtifactEvidence = {
+  runDir: Run["runDir"];
+  artifacts: readonly Artifact[];
+};
+
+type ArtifactEvidenceBoundary = {
+  root: string;
+  indexedOnly: boolean;
+};
+
+const artifactEvidenceBoundaries = new WeakMap<object, ArtifactEvidenceBoundary>();
+
+/** Internal: bind a frozen Run object to its isolated artifact snapshot. */
+export const bindRunArtifactEvidence = (
+  run: RunArtifactEvidence,
+  boundary: ArtifactEvidenceBoundary,
+): void => {
+  artifactEvidenceBoundaries.set(run, { ...boundary, root: resolve(boundary.root) });
+};
+
+/** Internal: whether a Run is confined to an isolated evidence snapshot. */
+export const hasRunArtifactEvidenceBoundary = (run: RunArtifactEvidence): boolean =>
+  artifactEvidenceBoundaries.has(run);
+
+const pathEscapesRoot = (root: string, target: string): boolean => {
+  const path = relative(root, target);
+  return path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);
+};
+
+const defaultArtifactsRoot = (run: RunArtifactEvidence): string =>
+  artifactEvidenceBoundaries.get(run)?.root ?? resolve(run.runDir, "artifacts");
+
+const rootsForArtifacts = (run: RunArtifactEvidence, artifacts: readonly Artifact[]): string[] => [
+  ...new Set(
+    artifacts.map((artifact) =>
+      artifact.root && isAbsolute(artifact.root)
+        ? resolve(artifact.root)
+        : defaultArtifactsRoot(run),
+    ),
+  ),
+];
+
+/**
+ * Resolve the common root captured by a driver. The default run artifacts
+ * directory remains the fallback for empty or genuinely multi-root evidence.
+ */
+export const runArtifactsRoot = (run: RunArtifactEvidence): string => {
+  const boundary = artifactEvidenceBoundaries.get(run);
+  if (boundary) return boundary.root;
+  const roots = rootsForArtifacts(run, run.artifacts);
+  return roots.length === 1 ? (roots[0] ?? defaultArtifactsRoot(run)) : defaultArtifactsRoot(run);
+};
+
+/**
+ * Inspect one captured artifact without following symlinks or allowing a path
+ * to escape the root recorded by its driver. An exact artifact-index entry
+ * wins; otherwise Lux uses the run's common captured-artifact root.
+ */
+export const inspectRunArtifact = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+): Promise<RunArtifactInspection> => {
+  if (authoredPath.includes("\0")) {
+    return {
+      target: authoredPath,
+      root: runArtifactsRoot(run),
+      issue: `${authoredPath} contains a null byte`,
+    };
+  }
+  const matching = run.artifacts.filter((candidate) => candidate.path === authoredPath);
+  if (artifactEvidenceBoundaries.get(run)?.indexedOnly && matching.length === 0) {
+    const root = defaultArtifactsRoot(run);
+    return {
+      target: resolve(root, authoredPath),
+      root,
+      issue: `${authoredPath} was not captured in the frozen artifact index`,
+    };
+  }
+  if (matching.some((candidate) => candidate.root !== undefined && !isAbsolute(candidate.root))) {
+    return {
+      target: authoredPath,
+      root: defaultArtifactsRoot(run),
+      issue: `${authoredPath} declares a non-absolute artifact root`,
+    };
+  }
+  const artifact = matching[0];
+  const identified = artifact ? { artifact } : {};
+  const matchingRoots = rootsForArtifacts(run, matching);
+  if (matchingRoots.length > 1) {
+    return {
+      target: authoredPath,
+      root: defaultArtifactsRoot(run),
+      issue: `${authoredPath} is ambiguous across multiple artifact roots`,
+    };
+  }
+  // A non-default root is trusted only for an exact artifact-index entry.
+  // Otherwise one captured path could turn its whole external root into
+  // assertion-readable evidence.
+  const root = matchingRoots[0] ?? defaultArtifactsRoot(run);
+  const target = resolve(root, authoredPath);
+  if (pathEscapesRoot(root, target)) {
+    return { target, root, issue: `${authoredPath} escapes the captured artifact root` };
+  }
+
+  const path = relative(root, target);
+  const components = [
+    root,
+    ...path
+      .split(sep)
+      .filter(Boolean)
+      .map((_, index, parts) => join(root, ...parts.slice(0, index + 1))),
+  ];
+  for (const [index, component] of components.entries()) {
+    let stats: Stats;
+    try {
+      stats = await lstat(component);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === "ENOTDIR") {
+        return { target, root, ...identified, issue: `${authoredPath} not found` };
+      }
+      throw error;
+    }
+    if (stats.isSymbolicLink()) {
+      return {
+        target,
+        root,
+        ...identified,
+        issue: `${authoredPath} resolves through a symlink`,
+      };
+    }
+    if (index < components.length - 1 && !stats.isDirectory()) {
+      return { target, root, ...identified, issue: `${authoredPath} not found` };
+    }
+    if (index === components.length - 1) {
+      return { target, root, ...identified, stats };
+    }
+  }
+  return { target, root, ...identified, issue: `${authoredPath} not found` };
+};
+
+export type ReadRunArtifactTextOptions = {
+  /**
+   * Maximum bytes read before UTF-8 decoding. Defaults to 5 MiB and cannot
+   * exceed Lux's 10 MiB public artifact-read ceiling.
+   */
+  maxBytes?: number;
+};
+
+export const readInspectedFileBytes = async (
+  target: string,
+  expected: Stats,
+  maxBytes: number,
+  label: string,
+): Promise<Buffer> => {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > MAX_ARTIFACT_READ_BYTES) {
+    throw new RangeError(
+      `artifact maxBytes must be an integer from 0 to ${MAX_ARTIFACT_READ_BYTES}`,
+    );
+  }
+  if (!expected.isFile()) throw new Error(`${label} is not a file`);
+  if (expected.size > maxBytes) {
+    throw new Error(`${label} exceeds the ${maxBytes}-byte artifact read limit`);
+  }
+
+  try {
+    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+      const opened = await handle.stat();
+      if (!opened.isFile()) throw new Error(`${label} is not a file`);
+      if (opened.dev !== expected.dev || opened.ino !== expected.ino) {
+        throw new Error(`${label} changed while it was being inspected`);
+      }
+      if (opened.size !== expected.size) {
+        throw new Error(`${label} changed while it was being inspected`);
+      }
+      if (opened.size > maxBytes) {
+        throw new Error(`${label} exceeds the ${maxBytes}-byte artifact read limit`);
+      }
+      // Allocate for the inspected file, not the caller's ceiling. Reading one
+      // extra byte detects same-inode growth after fstat without making many
+      // tiny artifact reads reserve the maximum concurrently.
+      const bytes = Buffer.alloc(expected.size + 1);
+      let offset = 0;
+      while (offset < bytes.length) {
+        const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+        if (read.bytesRead === 0) break;
+        offset += read.bytesRead;
+      }
+      if (offset !== expected.size) {
+        throw new Error(`${label} changed while it was being inspected`);
+      }
+      return bytes.subarray(0, offset);
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ELOOP") {
+      throw new Error(`${label} resolves through a symlink`);
+    }
+    throw error;
+  }
+};
+
+export const readRunArtifactBytes = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+  options: ReadRunArtifactTextOptions = {},
+): Promise<Buffer> => {
+  const maxBytes = options.maxBytes ?? DEFAULT_ARTIFACT_READ_BYTES;
+  const inspected = await inspectRunArtifact(run, authoredPath);
+  if (!inspected.stats?.isFile()) {
+    throw new Error(
+      inspected.issue ??
+        (inspected.stats ? `${authoredPath} is not a file` : `${authoredPath} not found`),
+    );
+  }
+  return await readInspectedFileBytes(inspected.target, inspected.stats, maxBytes, authoredPath);
+};
+
+/**
+ * Read UTF-8 artifact evidence through Lux's traversal, symlink, regular-file,
+ * and size checks. Throws a bounded, path-specific error when evidence is not
+ * safe to consume.
+ */
+export const readRunArtifactText = async (
+  run: RunArtifactEvidence,
+  authoredPath: string,
+  options: ReadRunArtifactTextOptions = {},
+): Promise<string> => {
+  return (await readRunArtifactBytes(run, authoredPath, options)).toString("utf8");
+};

package/src/core/artifact-snapshot.ts

@@ -0,0 +1,429 @@
+import { createHash } from "node:crypto";
+import {
+  chmod,
+  constants,
+  copyFile,
+  lstat,
+  mkdir,
+  mkdtemp,
+  open,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  unlink,
+} from "node:fs/promises";
+import { dirname, join, posix, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+
+const DEFAULT_MAX_FILES = 100_000;
+const DEFAULT_MAX_BYTES = 256 * 1024 * 1024;
+const DEFAULT_WRITE_CONCURRENCY = 16;
+const MAX_MANIFEST_BYTES = 64 * 1024 * 1024;
+const MAX_SNAPSHOT_PATH_BYTES = 4_096;
+export const ARTIFACT_SNAPSHOT_MANIFEST = ".lux-snapshot.json";
+const SNAPSHOT_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export const ArtifactSnapshotFileSchema = z.object({
+  path: z
+    .string()
+    .min(1)
+    .refine((path) => {
+      try {
+        return snapshotPath(path) === path;
+      } catch {
+        return false;
+      }
+    }, "invalid snapshot path"),
+  bytes: z.number().int().nonnegative(),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+});
+export type ArtifactSnapshotFile = z.infer<typeof ArtifactSnapshotFileSchema>;
+
+export const ArtifactSnapshotManifestSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    name: z.string().regex(SNAPSHOT_NAME),
+    files: z.array(ArtifactSnapshotFileSchema),
+    fileCount: z.number().int().nonnegative(),
+    bytes: z.number().int().nonnegative(),
+    baseSnapshot: z.string().regex(SNAPSHOT_NAME).optional(),
+    reusedFiles: z.number().int().nonnegative(),
+    reusedBytes: z.number().int().nonnegative(),
+  })
+  .superRefine((manifest, ctx) => {
+    const paths = new Set(manifest.files.map((file) => file.path));
+    const bytes = manifest.files.reduce((total, file) => total + file.bytes, 0);
+    if (paths.size !== manifest.files.length) {
+      ctx.addIssue({ code: "custom", path: ["files"], message: "paths must be unique" });
+    }
+    if (manifest.fileCount !== manifest.files.length) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["fileCount"],
+        message: "fileCount must equal files.length",
+      });
+    }
+    if (manifest.bytes !== bytes) {
+      ctx.addIssue({ code: "custom", path: ["bytes"], message: "bytes must equal file sizes" });
+    }
+    if (manifest.reusedFiles > manifest.fileCount || manifest.reusedBytes > manifest.bytes) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["reusedFiles"],
+        message: "reused totals cannot exceed snapshot totals",
+      });
+    }
+  });
+export type ArtifactSnapshotManifest = z.infer<typeof ArtifactSnapshotManifestSchema>;
+
+export type ArtifactSnapshotContent = string | Uint8Array;
+export type ArtifactSnapshotFiles = Readonly<Record<string, ArtifactSnapshotContent>>;
+
+export interface WriteArtifactSnapshotOptions {
+  artifactsDir: string;
+  name: string;
+  files: ArtifactSnapshotFiles;
+  baseSnapshot?: string;
+  maxFiles?: number;
+  maxBytes?: number;
+  writeConcurrency?: number;
+}
+
+type PreparedSnapshotFile = ArtifactSnapshotFile & {
+  content: Buffer;
+};
+
+const positiveInteger = (value: number | undefined, fallback: number, label: string): number => {
+  const resolved = value ?? fallback;
+  if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+    throw new RangeError(`${label} must be a positive safe integer`);
+  }
+  return resolved;
+};
+
+const snapshotPath = (source: string): string => {
+  if (!source || source.includes("\0") || source.includes("\\")) {
+    throw new Error(`snapshot file path is invalid: ${JSON.stringify(source)}`);
+  }
+  const withoutRoot = source.replace(/^\/+/, "");
+  if (Buffer.byteLength(withoutRoot) > MAX_SNAPSHOT_PATH_BYTES) {
+    throw new Error(`snapshot file path is too long: ${JSON.stringify(source)}`);
+  }
+  const normalized = posix.normalize(withoutRoot);
+  if (
+    !withoutRoot ||
+    normalized === "." ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    posix.isAbsolute(normalized) ||
+    normalized !== withoutRoot
+  ) {
+    throw new Error(`snapshot file path is unsafe: ${JSON.stringify(source)}`);
+  }
+  return normalized;
+};
+
+const contentBuffer = (content: ArtifactSnapshotContent): Buffer =>
+  typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
+
+const prepareFiles = (
+  files: ArtifactSnapshotFiles,
+  maxFiles: number,
+  maxBytes: number,
+): PreparedSnapshotFile[] => {
+  const paths = new Set<string>();
+  const entries = Object.entries(files);
+  if (entries.length > maxFiles) {
+    throw new Error(`snapshot has ${entries.length} files, exceeding the ${maxFiles}-file limit`);
+  }
+  const prepared: PreparedSnapshotFile[] = [];
+  let bytes = 0;
+  for (const [sourcePath, content] of entries) {
+    const path = snapshotPath(sourcePath);
+    if (path === ARTIFACT_SNAPSHOT_MANIFEST) {
+      throw new Error(`snapshot file path is reserved: ${path}`);
+    }
+    if (paths.has(path)) {
+      throw new Error(`snapshot contains duplicate path: ${path}`);
+    }
+    paths.add(path);
+    const contentBytes =
+      typeof content === "string" ? Buffer.byteLength(content, "utf8") : content.byteLength;
+    bytes += contentBytes;
+    if (!Number.isSafeInteger(bytes) || bytes > maxBytes) {
+      throw new Error(`snapshot has ${bytes} bytes, exceeding the ${maxBytes}-byte limit`);
+    }
+    const buffer = contentBuffer(content);
+    prepared.push({
+      path,
+      content: buffer,
+      bytes: buffer.byteLength,
+      sha256: createHash("sha256").update(buffer).digest("hex"),
+    });
+  }
+  prepared.sort((left, right) => {
+    if (left.path < right.path) return -1;
+    if (left.path > right.path) return 1;
+    return 0;
+  });
+  return prepared;
+};
+
+const ensurePrivateParents = async (root: string, target: string): Promise<void> => {
+  const resolvedRoot = resolve(root);
+  const parent = dirname(target);
+  const path = relative(resolvedRoot, parent);
+  let cursor = resolvedRoot;
+  for (const part of path.split(sep).filter(Boolean)) {
+    cursor = resolve(cursor, part);
+    try {
+      await mkdir(cursor, { mode: 0o700 });
+    } catch (error) {
+      if (!(error instanceof Error && "code" in error && error.code === "EEXIST")) throw error;
+    }
+    const stats = await lstat(cursor);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) {
+      throw new Error(`snapshot parent must be a real directory: ${cursor}`);
+    }
+    const canonical = await realpath(cursor);
+    if (canonical !== resolvedRoot && !canonical.startsWith(`${resolvedRoot}${sep}`)) {
+      throw new Error(`snapshot parent escaped its root: ${cursor}`);
+    }
+    await chmod(cursor, 0o700);
+  }
+};
+
+const writePrivateFile = async (root: string, path: string, content: Uint8Array): Promise<void> => {
+  const target = resolve(root, path);
+  if (!target.startsWith(`${resolve(root)}${sep}`)) {
+    throw new Error(`snapshot path escaped its root: ${path}`);
+  }
+  await ensurePrivateParents(root, target);
+  const handle = await open(
+    target,
+    constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW,
+    0o600,
+  );
+  try {
+    await handle.writeFile(content);
+    await handle.chmod(0o400);
+  } finally {
+    await handle.close();
+  }
+};
+
+type SnapshotBase = {
+  root: string;
+  files: Map<string, ArtifactSnapshotFile>;
+};
+
+export const readArtifactSnapshotManifest = async (
+  snapshotRoot: string,
+): Promise<ArtifactSnapshotManifest | undefined> => {
+  const rootStats = await lstat(snapshotRoot);
+  if (rootStats.isSymbolicLink() || !rootStats.isDirectory()) {
+    throw new Error(`artifact snapshot must be a real directory: ${snapshotRoot}`);
+  }
+  const manifestPath = join(snapshotRoot, ARTIFACT_SNAPSHOT_MANIFEST);
+  const manifestStats = await lstat(manifestPath).catch((error: unknown) => {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  });
+  if (!manifestStats) return undefined;
+  if (
+    manifestStats.isSymbolicLink() ||
+    !manifestStats.isFile() ||
+    manifestStats.size > MAX_MANIFEST_BYTES
+  ) {
+    throw new Error(`artifact snapshot manifest is invalid: ${snapshotRoot}`);
+  }
+  return ArtifactSnapshotManifestSchema.parse(JSON.parse(await readFile(manifestPath, "utf8")));
+};
+
+const loadSnapshotBase = async (
+  root: string,
+  name: string | undefined,
+): Promise<SnapshotBase | undefined> => {
+  if (name === undefined) return undefined;
+  if (!SNAPSHOT_NAME.test(name)) {
+    throw new Error(`artifact base snapshot name is invalid: ${name}`);
+  }
+  const baseRoot = join(root, name);
+  const stats = await lstat(baseRoot);
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new Error(`artifact base snapshot must be a real directory: ${name}`);
+  }
+  const manifest = await readArtifactSnapshotManifest(baseRoot);
+  if (!manifest) throw new Error(`artifact base snapshot manifest is missing: ${name}`);
+  if (manifest.name !== name) {
+    throw new Error(`artifact base snapshot manifest names ${manifest.name}, expected ${name}`);
+  }
+  return {
+    root: baseRoot,
+    files: new Map(manifest.files.map((file) => [file.path, file])),
+  };
+};
+
+const writeSnapshotFile = async (
+  root: string,
+  file: PreparedSnapshotFile,
+  base: SnapshotBase | undefined,
+): Promise<boolean> => {
+  const previous = base?.files.get(file.path);
+  if (base && previous?.bytes === file.bytes && previous.sha256 === file.sha256) {
+    const source = resolve(base.root, file.path);
+    const target = resolve(root, file.path);
+    if (
+      !source.startsWith(`${resolve(base.root)}${sep}`) ||
+      !target.startsWith(`${resolve(root)}${sep}`)
+    ) {
+      throw new Error(`snapshot path escaped its root: ${file.path}`);
+    }
+    let sourceMatches = false;
+    try {
+      const sourceHandle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const sourceStats = await sourceHandle.stat();
+        if (sourceStats.isFile() && sourceStats.size === file.bytes) {
+          const sourceContent = await sourceHandle.readFile();
+          sourceMatches = createHash("sha256").update(sourceContent).digest("hex") === file.sha256;
+        }
+      } finally {
+        await sourceHandle.close();
+      }
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        "code" in error &&
+        (error.code === "ENOENT" || error.code === "ELOOP")
+      ) {
+        await writePrivateFile(root, file.path, file.content);
+        return false;
+      }
+      throw error;
+    }
+    if (sourceMatches) {
+      await ensurePrivateParents(root, target);
+      await copyFile(source, target, constants.COPYFILE_FICLONE);
+      await chmod(target, 0o400);
+      const copied = await readFile(target);
+      if (
+        copied.byteLength === file.bytes &&
+        createHash("sha256").update(copied).digest("hex") === file.sha256
+      ) {
+        return true;
+      }
+      try {
+        await unlink(target);
+      } catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
+      }
+    }
+  }
+  await writePrivateFile(root, file.path, file.content);
+  return false;
+};
+
+const writeFiles = async (
+  root: string,
+  files: PreparedSnapshotFile[],
+  concurrency: number,
+  base: SnapshotBase | undefined,
+): Promise<Set<string>> => {
+  let cursor = 0;
+  const reused = new Set<string>();
+  const worker = async (): Promise<void> => {
+    while (cursor < files.length) {
+      const file = files[cursor];
+      cursor += 1;
+      if (file && (await writeSnapshotFile(root, file, base))) {
+        reused.add(file.path);
+      }
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(concurrency, Math.max(1, files.length)) }, worker),
+  );
+  return reused;
+};
+
+const ensureArtifactRoot = async (artifactsDir: string): Promise<string> => {
+  await mkdir(artifactsDir, { recursive: true, mode: 0o700 });
+  const stats = await lstat(artifactsDir);
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    throw new Error(`artifact snapshot root must be a real directory: ${artifactsDir}`);
+  }
+  await chmod(artifactsDir, 0o700);
+  return await realpath(artifactsDir);
+};
+
+export const writeArtifactSnapshot = async ({
+  artifactsDir,
+  name,
+  files,
+  baseSnapshot,
+  maxFiles: requestedMaxFiles,
+  maxBytes: requestedMaxBytes,
+  writeConcurrency: requestedWriteConcurrency,
+}: WriteArtifactSnapshotOptions): Promise<ArtifactSnapshotManifest> => {
+  if (!SNAPSHOT_NAME.test(name)) {
+    throw new Error(
+      "artifact snapshot name must start with a letter or number and contain only letters, numbers, dots, underscores, or hyphens",
+    );
+  }
+  const maxFiles = positiveInteger(requestedMaxFiles, DEFAULT_MAX_FILES, "snapshot maxFiles");
+  const maxBytes = positiveInteger(requestedMaxBytes, DEFAULT_MAX_BYTES, "snapshot maxBytes");
+  const writeConcurrency = positiveInteger(
+    requestedWriteConcurrency,
+    DEFAULT_WRITE_CONCURRENCY,
+    "snapshot writeConcurrency",
+  );
+  const prepared = prepareFiles(files, maxFiles, maxBytes);
+  const root = await ensureArtifactRoot(artifactsDir);
+  if (baseSnapshot === name) {
+    throw new Error("artifact snapshot cannot use itself as its base");
+  }
+  const base = await loadSnapshotBase(root, baseSnapshot);
+  const target = join(root, name);
+  try {
+    await lstat(target);
+    throw new Error(`artifact snapshot already exists: ${name}`);
+  } catch (error) {
+    if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+
+  const staging = await mkdtemp(join(root, `.lux-snapshot-${name}-`));
+  await chmod(staging, 0o700);
+  try {
+    const reused = await writeFiles(staging, prepared, writeConcurrency, base);
+    const manifest: ArtifactSnapshotManifest = {
+      schemaVersion: 1,
+      name,
+      files: prepared.map(({ path, bytes, sha256 }) => ({
+        path,
+        bytes,
+        sha256,
+      })),
+      fileCount: prepared.length,
+      bytes: prepared.reduce((total, file) => total + file.bytes, 0),
+      ...(baseSnapshot ? { baseSnapshot } : {}),
+      reusedFiles: reused.size,
+      reusedBytes: prepared
+        .filter((file) => reused.has(file.path))
+        .reduce((total, file) => total + file.bytes, 0),
+    };
+    await writePrivateFile(
+      staging,
+      ARTIFACT_SNAPSHOT_MANIFEST,
+      Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`, "utf8"),
+    );
+    await rename(staging, target);
+    return manifest;
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+};