@cassiomc1/forgeloop 0.1.0

package/src/core/conformance.js

@@ -0,0 +1,133 @@
+import { PROTOCOL_VERSION } from "./protocol.js";
+import { createEvidence } from "./evidence.js";
+
+function error(code, message, artifacts = []) {
+  return { code, message, artifacts };
+}
+
+function addVersionErrors(artifact, label, errors) {
+  if (!artifact) return;
+  if (artifact.schemaVersion !== 1 || artifact.protocolVersion !== PROTOCOL_VERSION) {
+    errors.push(error(
+      "UNSUPPORTED_PROTOCOL_VERSION",
+      `${label} must use schemaVersion 1 and protocolVersion ${PROTOCOL_VERSION}`,
+      [label],
+    ));
+  }
+}
+
+function sortErrors(errors) {
+  return errors.sort((left, right) => left.code.localeCompare(right.code)
+    || left.artifacts.join("\0").localeCompare(right.artifacts.join("\0"))
+    || left.message.localeCompare(right.message));
+}
+
+export function validateTaskArtifactSet({
+  route = null,
+  state = null,
+  stateClassification = null,
+  receipt = null,
+  taskBriefs = [],
+  delegatedResults = [],
+} = {}) {
+  const errors = [];
+  const incomplete = [];
+
+  addVersionErrors(route, "route", errors);
+  addVersionErrors(state, "state", errors);
+  addVersionErrors(receipt, "receipt", errors);
+  for (const brief of taskBriefs) addVersionErrors(brief, `taskBrief:${brief?.taskId ?? "unknown"}`, errors);
+  for (const result of delegatedResults) addVersionErrors(result, `delegatedResult:${result?.taskId ?? "unknown"}`, errors);
+
+  if (route && state && route.protocolVersion !== state.protocolVersion) {
+    errors.push(error("ROUTE_STATE_PROTOCOL_MISMATCH", "routing-result and work-state protocol versions differ", ["route", "state"]));
+  }
+  if (state && receipt && state.contractFingerprint !== receipt.contractFingerprint) {
+    errors.push(error("STATE_RECEIPT_CONTRACT_MISMATCH", "work-state and execution-receipt contract fingerprints differ", ["state", "receipt"]));
+  }
+  if (state && receipt && state.taskId !== receipt.taskId) {
+    errors.push(error("STATE_RECEIPT_TASK_MISMATCH", "work-state and execution-receipt task IDs differ", ["state", "receipt"]));
+  }
+  if (route && state && JSON.stringify(route.guides) !== JSON.stringify(state.selectedGuides)) {
+    errors.push(error("ROUTE_STATE_GUIDES_MISMATCH", "work-state.selectedGuides must equal routing-result.guides", ["route", "state"]));
+  }
+  if (state && receipt && JSON.stringify(state.selectedGuides) !== JSON.stringify(receipt.selectedGuides)) {
+    errors.push(error("STATE_RECEIPT_GUIDES_MISMATCH", "execution-receipt.selectedGuides must equal work-state.selectedGuides", ["state", "receipt"]));
+  }
+
+  const briefIds = new Set();
+  for (const brief of taskBriefs) {
+    if (!brief?.taskId) continue;
+    if (briefIds.has(brief.taskId)) {
+      errors.push(error("DUPLICATE_TASK_ID", `task brief ID is duplicated: ${brief.taskId}`, [`taskBrief:${brief.taskId}`]));
+    }
+    briefIds.add(brief.taskId);
+    if (state && brief.parentTaskId !== state.taskId) {
+      errors.push(error("TASK_PARENT_MISMATCH", `task brief ${brief.taskId} does not belong to ${state.taskId}`, [`taskBrief:${brief.taskId}`, "state"]));
+    }
+  }
+
+  const delegatedIds = new Set();
+  for (const result of delegatedResults) {
+    if (!result?.taskId) continue;
+    if (delegatedIds.has(result.taskId)) {
+      errors.push(error("DUPLICATE_DELEGATED_RESULT", `delegated result is duplicated: ${result.taskId}`, [`delegatedResult:${result.taskId}`]));
+    }
+    delegatedIds.add(result.taskId);
+    if (!briefIds.has(result.taskId)) {
+      errors.push(error("UNKNOWN_DELEGATED_TASK", `delegated result has no corresponding task brief: ${result.taskId}`, [`delegatedResult:${result.taskId}`]));
+    }
+  }
+
+  if (taskBriefs.length > 0) {
+    for (const taskId of [...briefIds].sort()) {
+      if (!delegatedIds.has(taskId)) incomplete.push(`missing delegated result: ${taskId}`);
+    }
+  } else if (delegatedResults.length === 0) {
+    incomplete.push("task briefs and delegated results were not supplied");
+  }
+  if (!route || !state || !receipt) incomplete.push("route, state, and receipt are all required for a complete artifact set");
+
+  const sortedErrors = sortErrors(errors);
+  let status = "VALID";
+  if (sortedErrors.some((item) => item.code === "UNSUPPORTED_PROTOCOL_VERSION")) {
+    status = "INVALID";
+  } else if (sortedErrors.length > 0) {
+    status = "INCONSISTENT";
+  } else if (stateClassification?.status === "REVALIDATION_REQUIRED") {
+    status = "STALE";
+  } else if (incomplete.length > 0) {
+    status = "INCOMPLETE";
+  }
+
+  const stale = status === "STALE"
+    ? {
+      reasons: [...(stateClassification?.reasons ?? [])],
+      warnings: [...(stateClassification?.warnings ?? [])],
+      repositoryComparison: stateClassification?.repositoryComparison ?? "NOT_VERIFIED",
+      contractComparison: stateClassification?.contractComparison ?? "NOT_VERIFIED",
+      artifactComparison: stateClassification?.artifactComparison ?? "NOT_APPLICABLE",
+    }
+    : null;
+
+  const evidenceKind = status === "VALID"
+    ? "OBSERVED"
+    : status === "INCOMPLETE"
+      ? "NOT_VERIFIED"
+      : status === "STALE"
+        ? "INFERRED"
+        : status === "INVALID"
+          ? "BLOCKED"
+          : "OBSERVED";
+  return {
+    status,
+    errors: sortedErrors,
+    incomplete: [...new Set(incomplete)].sort(),
+    stale,
+    evidence: [createEvidence({
+      kind: evidenceKind,
+      source: "ForgeLoop protocol conformance",
+      result: status,
+    })],
+  };
+}

package/src/core/delegation.js

@@ -0,0 +1,283 @@
+import path from "node:path";
+
+import { GUIDE_IDS, PROTOCOL_VERSION } from "./protocol.js";
+import { assertSchema, readSchema } from "./schema-validation.js";
+import { assertSecretFree } from "./receipt.js";
+import { assertEvidenceList } from "./evidence.js";
+
+const DELEGATION_SCHEMA_VERSION = 1;
+
+function normalizePath(value, label) {
+  if (typeof value !== "string" || !value) throw new Error(`${label} must contain non-empty paths`);
+  const portable = value.replaceAll("\\", "/");
+  if (portable.startsWith("/") || /^[A-Za-z]:\//.test(portable)) {
+    throw new Error(`${label} must remain relative: ${value}`);
+  }
+  const normalized = path.posix.normalize(portable);
+  if (normalized === "." || normalized === ".." || normalized.startsWith("../")) {
+    throw new Error(`${label} escapes the task target: ${value}`);
+  }
+  return normalized === "." ? "" : normalized.replace(/^\.\//, "");
+}
+
+function normalizePathList(value, label) {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  const normalized = value.map((item) => normalizePath(item, label));
+  if (new Set(normalized).size !== normalized.length) throw new Error(`${label} must not contain duplicate paths`);
+  return normalized.sort();
+}
+
+function pathsOverlap(left, right) {
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function overlapPath(left, right) {
+  return left.length <= right.length ? left : right;
+}
+
+function assertBriefPathBoundaries(brief) {
+  for (const allowed of brief.allowedPaths) {
+    for (const readOnly of brief.readOnlyPaths) {
+      if (pathsOverlap(allowed, readOnly)) {
+        throw new Error(`allowed and read-only paths overlap: ${allowed} / ${readOnly}`);
+      }
+    }
+  }
+}
+
+export async function validateTaskBrief(brief, packageRoot) {
+  assertSecretFree(brief);
+  const normalized = {
+    ...brief,
+    schemaVersion: DELEGATION_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    allowedPaths: normalizePathList(brief.allowedPaths, "allowedPaths"),
+    readOnlyPaths: normalizePathList(brief.readOnlyPaths, "readOnlyPaths"),
+    dependencies: [...(brief.dependencies ?? [])].sort(),
+    constraints: [...(brief.constraints ?? [])],
+    requiredGuides: [...(brief.requiredGuides ?? [])].sort(),
+    verification: [...(brief.verification ?? [])],
+    authority: [...(brief.authority ?? [])],
+    deliverables: [...(brief.deliverables ?? [])],
+    executionMode: brief.executionMode ?? "inline",
+  };
+  const schema = await readSchema("task-brief", packageRoot);
+  assertSchema(normalized, schema, "delegation task brief");
+  for (const guide of normalized.requiredGuides) {
+    if (!GUIDE_IDS.includes(guide)) throw new Error(`Task brief contains unknown guide: ${guide}`);
+  }
+  if (normalized.dependencies.includes(normalized.taskId)) {
+    throw new Error("Task brief cannot depend on itself");
+  }
+  assertBriefPathBoundaries(normalized);
+  return normalized;
+}
+
+export async function validateDelegatedResult(result, packageRoot) {
+  assertSecretFree(result);
+  const schema = await readSchema("delegated-result", packageRoot);
+  const validated = assertSchema(result, schema, "delegated result");
+  assertEvidenceList(validated.evidence ?? [], "delegated-result.evidence");
+  if (validated.status === "complete" && !(validated.evidence ?? []).some((item) => ["OBSERVED", "INFERRED"].includes(item.kind))) {
+    throw new Error("complete delegated result requires verification evidence");
+  }
+  return validated;
+}
+
+export function findOwnershipConflicts(briefs) {
+  const conflicts = [];
+  const ordered = [...briefs].sort((left, right) => left.taskId.localeCompare(right.taskId));
+  for (let leftIndex = 0; leftIndex < ordered.length; leftIndex += 1) {
+    for (let rightIndex = leftIndex + 1; rightIndex < ordered.length; rightIndex += 1) {
+      const left = ordered[leftIndex];
+      const right = ordered[rightIndex];
+      const leftPaths = (left.allowedPaths ?? []).map((value) => normalizePath(value, "allowedPaths"));
+      const rightPaths = (right.allowedPaths ?? []).map((value) => normalizePath(value, "allowedPaths"));
+      const leftReadOnly = (left.readOnlyPaths ?? []).map((value) => normalizePath(value, "readOnlyPaths"));
+      const rightReadOnly = (right.readOnlyPaths ?? []).map((value) => normalizePath(value, "readOnlyPaths"));
+      const seen = new Set();
+      const addConflict = (type, leftPath, rightPath) => {
+        if (!pathsOverlap(leftPath, rightPath)) return;
+        const pathValue = overlapPath(leftPath, rightPath);
+        const key = `${type}:${pathValue}`;
+        if (seen.has(key)) return;
+        seen.add(key);
+        conflicts.push({ taskIds: [left.taskId, right.taskId], type, path: pathValue });
+      };
+      for (const leftPath of leftPaths) {
+        for (const rightPath of rightPaths) addConflict("WRITE_WRITE", leftPath, rightPath);
+        for (const rightPath of rightReadOnly) addConflict("WRITE_READ", leftPath, rightPath);
+      }
+      for (const rightPath of rightPaths) {
+        for (const leftPath of leftReadOnly) addConflict("WRITE_READ", rightPath, leftPath);
+      }
+    }
+  }
+  conflicts.sort((left, right) => left.taskIds.join("\0").localeCompare(right.taskIds.join("\0"))
+    || left.type.localeCompare(right.type)
+    || left.path.localeCompare(right.path));
+  return { conflicts };
+}
+
+export function findUnknownDependencies(briefs) {
+  const known = new Set(briefs.map((brief) => brief.taskId));
+  return briefs
+    .flatMap((brief) => (Array.isArray(brief.dependencies) ? brief.dependencies : [])
+      .filter((dependency) => !known.has(dependency))
+      .map((dependency) => ({ taskId: brief.taskId, dependency })))
+    .sort((left, right) => left.taskId.localeCompare(right.taskId) || left.dependency.localeCompare(right.dependency));
+}
+
+export function findDependencyCycles(briefs) {
+  const graph = new Map(briefs.map((brief) => [brief.taskId, [...(Array.isArray(brief.dependencies) ? brief.dependencies : [])].sort()]));
+  const visiting = new Set();
+  const visited = new Set();
+  const stack = [];
+  const cycles = [];
+  const seen = new Set();
+
+  function visit(taskId) {
+    if (visiting.has(taskId)) {
+      const cycle = [...stack.slice(stack.indexOf(taskId)), taskId];
+      const key = cycle.join("->");
+      if (!seen.has(key)) {
+        seen.add(key);
+        cycles.push(cycle);
+      }
+      return;
+    }
+    if (visited.has(taskId)) return;
+    visiting.add(taskId);
+    stack.push(taskId);
+    for (const dependency of graph.get(taskId) ?? []) {
+      if (graph.has(dependency)) visit(dependency);
+    }
+    stack.pop();
+    visiting.delete(taskId);
+    visited.add(taskId);
+  }
+
+  for (const taskId of [...graph.keys()].sort()) visit(taskId);
+  return cycles;
+}
+
+function setError(errors, code, message, details = {}) {
+  errors.push({ code, message, ...details });
+}
+
+export function validateDelegationSet(briefs) {
+  const errors = [];
+  if (!Array.isArray(briefs)) {
+    return {
+      status: "INVALID",
+      errors: [{ code: "INVALID_SET", message: "Delegation set must be an array" }],
+      conflicts: [],
+      cycles: [],
+      unknownDependencies: [],
+      integrationOwner: null,
+    };
+  }
+
+  const ordered = [...briefs].sort((left, right) => String(left?.taskId).localeCompare(String(right?.taskId)));
+  const taskIds = new Set();
+  for (const brief of ordered) {
+    if (!brief || typeof brief !== "object" || Array.isArray(brief)) {
+      setError(errors, "INVALID_TASK_BRIEF", "Each delegation item must be an object");
+      continue;
+    }
+    if (typeof brief.taskId !== "string" || !brief.taskId) {
+      setError(errors, "INVALID_TASK_ID", "Each task brief requires a taskId");
+    } else if (taskIds.has(brief.taskId)) {
+      setError(errors, "DUPLICATE_TASK_ID", `Task ID is duplicated: ${brief.taskId}`, { taskId: brief.taskId });
+    } else {
+      taskIds.add(brief.taskId);
+    }
+    if (brief.schemaVersion !== DELEGATION_SCHEMA_VERSION || brief.protocolVersion !== PROTOCOL_VERSION) {
+      setError(errors, "UNSUPPORTED_PROTOCOL_VERSION", `Unsupported task brief version: ${brief.taskId}`, { taskId: brief.taskId });
+    }
+    try {
+      assertSecretFree(brief);
+      const allowedPaths = normalizePathList(brief.allowedPaths, "allowedPaths");
+      const readOnlyPaths = normalizePathList(brief.readOnlyPaths, "readOnlyPaths");
+      assertBriefPathBoundaries({ allowedPaths, readOnlyPaths });
+      if (!Array.isArray(brief.verification) || brief.verification.length === 0) {
+        setError(errors, "MISSING_VERIFICATION", `Task brief requires verification: ${brief.taskId}`, { taskId: brief.taskId });
+      }
+      if (!Array.isArray(brief.authority) || brief.authority.length === 0) {
+        setError(errors, "MISSING_AUTHORITY", `Task brief requires authority: ${brief.taskId}`, { taskId: brief.taskId });
+      }
+      for (const guide of brief.requiredGuides ?? []) {
+        if (!GUIDE_IDS.includes(guide)) {
+          setError(errors, "UNKNOWN_GUIDE", `Task brief contains unknown guide: ${guide}`, { taskId: brief.taskId, guide });
+        }
+      }
+    } catch (error) {
+      setError(errors, "INVALID_TASK_BRIEF", error.message, { taskId: brief.taskId ?? null });
+    }
+    if (Array.isArray(brief.dependencies) && brief.dependencies.includes(brief.taskId)) {
+      setError(errors, "SELF_DEPENDENCY", `Task brief cannot depend on itself: ${brief.taskId}`, { taskId: brief.taskId });
+    }
+    if (Array.isArray(brief.dependencies) && new Set(brief.dependencies).size !== brief.dependencies.length) {
+      setError(errors, "DUPLICATE_DEPENDENCY", `Task brief dependencies must be unique: ${brief.taskId}`, { taskId: brief.taskId });
+    }
+  }
+
+  const unknownDependencies = findUnknownDependencies(ordered);
+  for (const item of unknownDependencies) {
+    setError(errors, "UNKNOWN_DEPENDENCY", `Unknown dependency ${item.dependency} for ${item.taskId}`, item);
+  }
+  const cycles = findDependencyCycles(ordered);
+  for (const cycle of cycles) {
+    setError(errors, "DEPENDENCY_CYCLE", `Dependency cycle: ${cycle.join(" -> ")}`, { cycle });
+  }
+
+  let conflicts = [];
+  if (!errors.some((error) => error.code === "INVALID_TASK_BRIEF")) {
+    try {
+      conflicts = findOwnershipConflicts(ordered).conflicts;
+    } catch (error) {
+      setError(errors, "INVALID_TASK_BRIEF", error.message);
+    }
+  }
+  const parentIds = [...new Set(ordered.map((brief) => brief?.parentTaskId).filter(Boolean))].sort();
+  if (parentIds.length > 1) {
+    setError(errors, "MULTIPLE_INTEGRATION_OWNERS", "All child tasks in a delegation set must share one parent integration owner");
+  }
+  errors.sort((left, right) => left.code.localeCompare(right.code)
+    || String(left.taskId).localeCompare(String(right.taskId))
+    || left.message.localeCompare(right.message));
+
+  return {
+    status: errors.length > 0 ? "INVALID" : conflicts.length > 0 ? "SERIAL_REQUIRED" : "PARALLEL_SAFE",
+    errors,
+    conflicts,
+    cycles,
+    unknownDependencies,
+    integrationOwner: parentIds.length === 1 ? parentIds[0] : null,
+  };
+}
+
+export function isIndependentReview({ implementerId, reviewerId, reviewType }) {
+  return reviewType === "independent"
+    && typeof implementerId === "string"
+    && typeof reviewerId === "string"
+    && implementerId !== reviewerId;
+}
+
+export function selectExecutionMode({ subagentsAvailable }) {
+  return subagentsAvailable ? "delegated" : "inline";
+}
+
+export function normalizeDelegatedResult(result) {
+  return {
+    schemaVersion: DELEGATION_SCHEMA_VERSION,
+    protocolVersion: PROTOCOL_VERSION,
+    taskId: result.taskId,
+    status: result.status,
+    changes: [...(result.changes ?? [])],
+    verification: [...(result.verification ?? [])],
+    evidence: [...(result.evidence ?? [])],
+    openFindings: [...(result.openFindings ?? [])],
+    limitations: [...(result.limitations ?? [])],
+  };
+}

package/src/core/evidence.js

@@ -0,0 +1,56 @@
+export const EVIDENCE_KINDS = Object.freeze([
+  "OBSERVED",
+  "INFERRED",
+  "NOT_VERIFIED",
+  "BLOCKED",
+]);
+
+export class EvidenceError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "EvidenceError";
+    this.code = "EVIDENCE_INVALID";
+  }
+}
+
+function assertNonEmptyString(value, label) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new EvidenceError(`${label} must be a non-empty string`);
+  }
+}
+
+export function createEvidence(input, source, result, details) {
+  const value = typeof input === "string"
+    ? { kind: input, source, result, ...(details === undefined ? {} : { details }) }
+    : input;
+  assertEvidence(value);
+  return value;
+}
+
+export function assertEvidence(value, label = "evidence") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new EvidenceError(`${label} must be an object`);
+  }
+  if (!EVIDENCE_KINDS.includes(value.kind)) {
+    throw new EvidenceError(`${label}.kind must be one of ${EVIDENCE_KINDS.join(", ")}`);
+  }
+  assertNonEmptyString(value.source, `${label}.source`);
+  assertNonEmptyString(value.result, `${label}.result`);
+  return value;
+}
+
+export function assertEvidenceList(value, label = "evidence") {
+  if (!Array.isArray(value)) throw new EvidenceError(`${label} must be an array`);
+  value.forEach((item, index) => assertEvidence(item, `${label}[${index}]`));
+  return value;
+}
+
+export function evidenceMatches(evidence, terms) {
+  const normalizedTerms = (Array.isArray(terms) ? terms : [terms])
+    .filter((term) => typeof term === "string" && term.length > 0)
+    .map((term) => term.toLowerCase());
+  return (evidence ?? []).some((item) => {
+    const haystack = `${item.source} ${item.result}`.toLowerCase();
+    return normalizedTerms.some((term) => haystack.includes(term));
+  });
+}

package/src/core/filesystem.js

@@ -0,0 +1,122 @@
+import { randomUUID } from "node:crypto";
+import {
+  access,
+  lstat,
+  mkdir,
+  readFile,
+  realpath,
+  rename,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+export function ensureWithin(root, relativePath) {
+  if (path.isAbsolute(relativePath)) {
+    throw new Error(`Path must remain inside target directory: ${relativePath}`);
+  }
+
+  const normalized = path.normalize(relativePath);
+  if (normalized === ".." || normalized.startsWith(`..${path.sep}`)) {
+    throw new Error(`Path escapes target directory: ${relativePath}`);
+  }
+
+  return path.join(root, normalized);
+}
+
+export async function assertSafePath(root, relativePath) {
+  const destination = ensureWithin(root, relativePath);
+  const absoluteRoot = path.resolve(root);
+  const rootInfo = await lstat(absoluteRoot);
+  if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) {
+    throw new Error(`Target directory must not be a symlink: ${absoluteRoot}`);
+  }
+
+  let current = absoluteRoot;
+  const segments = path.relative(absoluteRoot, destination).split(path.sep).filter(Boolean);
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    try {
+      const info = await lstat(current);
+      if (info.isSymbolicLink()) {
+        throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") break;
+      throw error;
+    }
+  }
+
+  let existing = destination;
+  while (true) {
+    try {
+      const info = await lstat(existing);
+      if (info.isSymbolicLink()) {
+        throw new Error(`Path uses a symlink inside target directory: ${relativePath}`);
+      }
+      const resolvedRoot = await realpath(absoluteRoot);
+      const resolvedExisting = await realpath(existing);
+      const relativeResolved = path.relative(resolvedRoot, resolvedExisting);
+      if (relativeResolved === ".." || relativeResolved.startsWith(`..${path.sep}`) || path.isAbsolute(relativeResolved)) {
+        throw new Error(`Path escapes target directory: ${relativePath}`);
+      }
+      return destination;
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(existing);
+      if (parent === existing) throw new Error(`Path does not resolve inside target directory: ${relativePath}`);
+      existing = parent;
+    }
+  }
+}
+
+export async function resolveTarget(cwd, requestedPath = ".") {
+  const target = path.resolve(cwd, requestedPath);
+  let targetStat;
+  try {
+    targetStat = await lstat(target);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      throw new Error(`Target directory does not exist: ${target}`);
+    }
+    throw error;
+  }
+
+  if (!targetStat.isDirectory() || targetStat.isSymbolicLink()) {
+    throw new Error(`Target path is not a directory: ${target}`);
+  }
+
+  return target;
+}
+
+export async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export async function readBytes(filePath) {
+  return readFile(filePath);
+}
+
+export async function writeFileAtomic(filePath, bytes, { dryRun = false } = {}) {
+  if (dryRun) return;
+
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, bytes, { mode: 0o644 });
+    await rename(temporaryPath, filePath);
+  } catch (error) {
+    try {
+      await unlink(temporaryPath);
+    } catch {
+      // Preserve the original filesystem error.
+    }
+    throw error;
+  }
+}