frontend-project-context 1.0.0

package/src/project-context/maintenance.mjs

@@ -0,0 +1,400 @@
+import { digestJson } from "./canonical-json.mjs";
+import { buildItemProposal } from "./authoring.mjs";
+import { sourceStatus, validateContract, validateSourceLock } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { writeProjectState } from "./project-store.mjs";
+import { readSourceDigest } from "./source-reader.mjs";
+import { findConflicts, validateOverrides } from "./scope-compiler.mjs";
+
+const LOCAL_SOURCE_KINDS = new Set(["file", "path", "json-pointer"]);
+
+function sameStrings(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function itemSummary(item, reasons = []) {
+  return {
+    id: item.id,
+    kind: item.kind,
+    subject: item.subject,
+    scope: structuredClone(item.scope),
+    itemDigest: digestJson(item),
+    ...(reasons.length > 0 ? { reasons: [...reasons].sort() } : {}),
+  };
+}
+
+function reverseOverrideDependents(contract, initialIds) {
+  const approved = contract.items.filter((item) => item.status === "approved");
+  const affected = new Set(initialIds);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const item of approved) {
+      if (affected.has(item.id) || !item.overrides.some((id) => affected.has(id))) continue;
+      affected.add(item.id);
+      changed = true;
+    }
+  }
+  return affected;
+}
+
+function relationDetails(contract, sourceId) {
+  const approved = contract.items.filter((item) => item.status === "approved");
+  const directReasons = new Map();
+  for (const item of approved) {
+    const reasons = [];
+    if (item.sources.includes(sourceId)) reasons.push("source");
+    if (item.verification?.source === sourceId) reasons.push("verification");
+    if (reasons.length > 0) directReasons.set(item.id, reasons);
+  }
+  const affected = reverseOverrideDependents(contract, directReasons.keys());
+  const byId = new Map(approved.map((item) => [item.id, item]));
+  const items = [...affected]
+    .map((id) => {
+      const item = byId.get(id);
+      const reasons = directReasons.get(id) ?? ["override-dependent"];
+      return itemSummary(item, reasons);
+    })
+    .sort((left, right) => left.id.localeCompare(right.id));
+  const fallbackIds = new Set();
+  for (const id of affected) {
+    for (const target of byId.get(id)?.overrides ?? []) {
+      if (!affected.has(target) && byId.has(target)) fallbackIds.add(target);
+    }
+  }
+  const fallbackItems = [...fallbackIds]
+    .map((id) => itemSummary(byId.get(id)))
+    .sort((left, right) => left.id.localeCompare(right.id));
+  return { items, fallbackItems };
+}
+
+export function sourceImpact(project, sourceId) {
+  const relations = relationDetails(project.contract, sourceId);
+  const affectedIds = new Set(relations.items.map((item) => item.id));
+  const directProjectionPaths = project.projectionsLock.projections
+    .filter((entry) => entry.itemIds.some((id) => affectedIds.has(id)))
+    .map((entry) => entry.path)
+    .sort();
+  const staleProjectionPaths = project.projectionsLock.projections.map((entry) => entry.path).sort();
+  return { ...relations, directProjectionPaths, staleProjectionPaths };
+}
+
+export async function reviewSource(root, project, sourceId) {
+  const source = project.contract.sources.find((entry) => entry.id === sourceId);
+  if (!source) fail("source-not-found", `source is not registered: ${sourceId}`, { details: { source: sourceId } });
+  const sourceObjectDigest = digestJson(source);
+  if (sourceStatus(source) === "deprecated") {
+    return {
+      source: structuredClone(source),
+      sourceObjectDigest,
+      contractDigest: project.contractDigest,
+      lockedDigest: null,
+      currentDigest: null,
+      status: "deprecated",
+      impact: sourceImpact(project, sourceId),
+    };
+  }
+  if (!LOCAL_SOURCE_KINDS.has(source.kind)) {
+    fail("source-review-unsupported", `source kind cannot be reviewed for local drift: ${source.kind}`, {
+      details: { source: sourceId, kind: source.kind },
+    });
+  }
+  const lockedDigest = project.sourcesLock.sources.find((entry) => entry.id === sourceId)?.digest ?? null;
+  let currentDigest = null;
+  let status;
+  let reason;
+  try {
+    currentDigest = await readSourceDigest(root, source);
+    if (lockedDigest === null || lockedDigest !== source.digest) {
+      status = "unreadable";
+      reason = lockedDigest === null ? "source-lock-missing" : "source-lock-mismatch";
+    } else {
+      status = currentDigest === lockedDigest ? "unchanged" : "changed";
+    }
+  } catch (error) {
+    status = error.code === "source-missing" ? "missing" : "unreadable";
+    reason = error.code ?? "source-unreadable";
+  }
+  return {
+    source: structuredClone(source),
+    sourceObjectDigest,
+    contractDigest: project.contractDigest,
+    lockedDigest,
+    currentDigest,
+    status,
+    ...(reason ? { reason } : {}),
+    impact: sourceImpact(project, sourceId),
+  };
+}
+
+export async function acceptSourceChange(root, project, input, options = {}) {
+  const review = await reviewSource(root, project, input.id);
+  if (review.status === "deprecated") {
+    fail("source-already-deprecated", `source is already deprecated: ${input.id}`, {
+      details: { source: input.id },
+    });
+  }
+  if (review.status === "unchanged") {
+    fail("source-not-changed", `source has not changed: ${input.id}`, { details: { source: input.id } });
+  }
+  if (review.status !== "changed" || review.currentDigest === null) {
+    fail("source-change-not-acceptable", `source state cannot be accepted: ${review.status}`, {
+      details: { source: input.id, status: review.status, reason: review.reason },
+    });
+  }
+  if (input.expectedDigest !== review.currentDigest) {
+    fail("source-accept-digest-mismatch", "the reviewed source digest no longer matches", {
+      exitCode: 1,
+      details: { source: input.id, expected: input.expectedDigest, actual: review.currentDigest },
+    });
+  }
+  const expectedItems = review.impact.items.map((item) => item.id);
+  const acknowledgedItems = [...new Set(input.affectedItems ?? [])].sort();
+  if (!sameStrings(acknowledgedItems, expectedItems)) {
+    fail("source-impact-changed", "the acknowledged affected item set is incomplete or stale", {
+      exitCode: 1,
+      details: { source: input.id, expected: expectedItems, actual: acknowledgedItems },
+    });
+  }
+
+  const nextContract = structuredClone(project.contract);
+  const source = nextContract.sources.find((entry) => entry.id === input.id);
+  source.digest = review.currentDigest;
+  const affected = new Set(expectedItems);
+  nextContract.items = nextContract.items.map((item) => {
+    if (!affected.has(item.id) || item.status !== "approved") return item;
+    const pending = { ...item, status: "proposed" };
+    delete pending.approval;
+    return pending;
+  });
+  validateContract(nextContract);
+
+  const nextSourcesLock = structuredClone(project.sourcesLock);
+  const lockEntry = nextSourcesLock.sources.find((entry) => entry.id === input.id);
+  if (!lockEntry) fail("source-lock-missing", `source lock entry is missing: ${input.id}`, { exitCode: 1 });
+  lockEntry.digest = review.currentDigest;
+  nextSourcesLock.sources.sort((left, right) => left.id.localeCompare(right.id));
+  validateSourceLock(nextSourcesLock);
+
+  if (options.write) {
+    let actual;
+    try {
+      actual = await readSourceDigest(root, source);
+    } catch (error) {
+      fail("source-accept-digest-mismatch", "source became unavailable while acceptance was being prepared", {
+        exitCode: 1,
+        details: { source: input.id, expected: input.expectedDigest, actual: null, reason: error.code ?? "unreadable" },
+      });
+    }
+    if (actual !== input.expectedDigest) {
+      fail("source-accept-digest-mismatch", "source changed while acceptance was being prepared", {
+        exitCode: 1,
+        details: { source: input.id, expected: input.expectedDigest, actual },
+      });
+    }
+    await writeProjectState(project, nextContract, nextSourcesLock, options.storeOptions);
+  }
+  return {
+    action: "accept-source-change",
+    source: input.id,
+    previousDigest: review.lockedDigest,
+    acceptedDigest: review.currentDigest,
+    affectedItems: expectedItems,
+    staleProjectionPaths: review.impact.staleProjectionPaths,
+    nextContractDigest: digestJson(nextContract),
+    written: Boolean(options.write),
+  };
+}
+
+function currentSourceReferences(contract, sourceId) {
+  return contract.items
+    .filter((item) => item.status !== "deprecated")
+    .map((item) => {
+      const reasons = [];
+      if (item.sources.includes(sourceId)) reasons.push("source");
+      if (item.verification?.source === sourceId) reasons.push("verification");
+      return reasons.length > 0 ? itemSummary(item, reasons) : null;
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export async function deprecateSource(project, input, options = {}) {
+  if (typeof input.by !== "string" || input.by.length === 0) {
+    fail("argument-invalid", "source deprecation requires a non-empty maintainer name", {
+      details: { source: input.id },
+    });
+  }
+  if (typeof input.rationale !== "string" || input.rationale.length === 0) {
+    fail("argument-invalid", "source deprecation requires a non-empty rationale", {
+      details: { source: input.id },
+    });
+  }
+  const current = project.contract.sources.find((source) => source.id === input.id);
+  if (!current) fail("source-not-found", `source is not registered: ${input.id}`, { details: { source: input.id } });
+  if (sourceStatus(current) === "deprecated") {
+    fail("source-already-deprecated", `source is already deprecated: ${input.id}`, {
+      details: { source: input.id },
+    });
+  }
+
+  const currentSourceDigest = digestJson(current);
+  if (options.write && input.expectedSourceDigest !== currentSourceDigest) {
+    fail("source-baseline-changed", "source changed after the deprecation preview", {
+      exitCode: 1,
+      details: { source: input.id, expected: input.expectedSourceDigest, actual: currentSourceDigest },
+    });
+  }
+  const blockingItems = currentSourceReferences(project.contract, input.id);
+  if (options.write && blockingItems.length > 0) {
+    fail("source-still-referenced", "source is still referenced by proposed or approved items", {
+      details: { source: input.id, items: blockingItems },
+    });
+  }
+  if (blockingItems.length > 0) {
+    return {
+      action: "deprecate-source",
+      currentSource: structuredClone(current),
+      currentSourceDigest,
+      blockingItems,
+      impact: sourceImpact(project, input.id),
+      nextContractDigest: null,
+      nextSourcesLockDigest: null,
+      written: false,
+    };
+  }
+
+  const timestamp = input.at ?? new Date().toISOString();
+  const nextContract = structuredClone(project.contract);
+  nextContract.schemaVersion = 2;
+  nextContract.sources = nextContract.sources.map((source) => {
+    const active = source.status === undefined ? { ...source, status: "active" } : source;
+    if (source.id !== input.id) return active;
+    return {
+      ...active,
+      status: "deprecated",
+      deprecation: { by: input.by, at: timestamp, rationale: input.rationale },
+    };
+  });
+  validateContract(nextContract);
+
+  const nextSourcesLock = {
+    ...structuredClone(project.sourcesLock),
+    sources: project.sourcesLock.sources.filter((entry) => entry.id !== input.id),
+  };
+  validateSourceLock(nextSourcesLock);
+  if (options.write) await writeProjectState(project, nextContract, nextSourcesLock, options.storeOptions);
+  const deprecatedSource = nextContract.sources.find((source) => source.id === input.id);
+  return {
+    action: "deprecate-source",
+    currentSource: structuredClone(current),
+    currentSourceDigest,
+    deprecatedSource: structuredClone(deprecatedSource),
+    blockingItems,
+    impact: sourceImpact(project, input.id),
+    nextContractDigest: digestJson(nextContract),
+    nextSourcesLockDigest: digestJson(nextSourcesLock),
+    written: Boolean(options.write),
+  };
+}
+
+export async function reviseItem(root, project, input, options = {}) {
+  const current = project.contract.items.find((item) => item.id === input.id);
+  if (!current) fail("item-not-found", `contract item does not exist: ${input.id}`, { details: { item: input.id } });
+  if (current.status === "deprecated") {
+    fail("item-already-deprecated", `deprecated item cannot be revised: ${input.id}`, { details: { item: input.id } });
+  }
+  const revisionProject = {
+    ...project,
+    contract: { ...project.contract, items: project.contract.items.filter((item) => item.id !== input.id) },
+  };
+  const replacement = buildItemProposal(revisionProject, input).items[0];
+  if (replacement.kind !== current.kind || replacement.subject !== current.subject) {
+    fail("item-identity-change", "revision must preserve item id, kind, and subject", {
+      details: {
+        item: input.id,
+        current: { kind: current.kind, subject: current.subject },
+        proposed: { kind: replacement.kind, subject: replacement.subject },
+      },
+    });
+  }
+  const currentItemDigest = digestJson(current);
+  if (options.write && input.expectedItemDigest !== currentItemDigest) {
+    fail("item-baseline-changed", "item changed after the revision preview", {
+      exitCode: 1,
+      details: { item: input.id, expected: input.expectedItemDigest, actual: currentItemDigest },
+    });
+  }
+  const nextContract = structuredClone(project.contract);
+  nextContract.items[nextContract.items.findIndex((item) => item.id === input.id)] = replacement;
+  validateContract(nextContract);
+  if (options.write) await writeProjectState(project, nextContract, project.sourcesLock, options.storeOptions);
+  return {
+    action: "revise",
+    currentItem: structuredClone(current),
+    currentItemDigest,
+    proposedItem: structuredClone(replacement),
+    nextContractDigest: digestJson(nextContract),
+    written: Boolean(options.write),
+  };
+}
+
+function itemRelationships(contract, itemId) {
+  const dependentIds = reverseOverrideDependents(contract, [itemId]);
+  dependentIds.delete(itemId);
+  const approvedById = new Map(contract.items.filter((item) => item.status === "approved").map((item) => [item.id, item]));
+  const item = contract.items.find((entry) => entry.id === itemId);
+  const fallbackIds = (item?.overrides ?? []).filter((id) => approvedById.has(id));
+  return {
+    overrideDependents: [...dependentIds].map((id) => itemSummary(approvedById.get(id))).sort((a, b) => a.id.localeCompare(b.id)),
+    fallbackItems: fallbackIds.map((id) => itemSummary(approvedById.get(id))).sort((a, b) => a.id.localeCompare(b.id)),
+  };
+}
+
+export async function deprecateItem(project, input, options = {}) {
+  if (typeof input.rationale !== "string" || input.rationale.length === 0) {
+    fail("argument-invalid", "deprecation requires a non-empty rationale", { details: { item: input.id } });
+  }
+  const current = project.contract.items.find((item) => item.id === input.id);
+  if (!current) fail("item-not-found", `contract item does not exist: ${input.id}`, { details: { item: input.id } });
+  if (current.status === "deprecated") {
+    fail("item-already-deprecated", `item is already deprecated: ${input.id}`, { details: { item: input.id } });
+  }
+  const currentItemDigest = digestJson(current);
+  if (options.write && input.expectedItemDigest !== currentItemDigest) {
+    fail("item-baseline-changed", "item changed after the deprecation preview", {
+      exitCode: 1,
+      details: { item: input.id, expected: input.expectedItemDigest, actual: currentItemDigest },
+    });
+  }
+  const deprecatedItem = {
+    ...structuredClone(current),
+    status: "deprecated",
+    approval: {
+      by: input.by,
+      at: input.at ?? new Date().toISOString(),
+      rationale: input.rationale,
+    },
+  };
+  const nextContract = structuredClone(project.contract);
+  nextContract.items[nextContract.items.findIndex((item) => item.id === input.id)] = deprecatedItem;
+  validateContract(nextContract);
+  const findings = [...validateOverrides(nextContract.items), ...findConflicts(nextContract.items)];
+  if (options.write && findings.length > 0) {
+    fail("maintenance-preflight-failed", "deprecation would leave invalid approved overrides or conflicts", {
+      exitCode: 1,
+      details: { item: input.id, findings },
+    });
+  }
+  if (options.write) await writeProjectState(project, nextContract, project.sourcesLock, options.storeOptions);
+  return {
+    action: "deprecate",
+    currentItem: structuredClone(current),
+    currentItemDigest,
+    deprecatedItem,
+    relationships: itemRelationships(project.contract, input.id),
+    preflightFindings: findings,
+    nextContractDigest: digestJson(nextContract),
+    written: Boolean(options.write),
+  };
+}

package/src/project-context/path-policy.mjs

@@ -0,0 +1,155 @@
+import { lstat, mkdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { fail } from "./errors.mjs";
+
+function hasParentSegment(value) {
+  return value.split(/[\\/]+/u).includes("..");
+}
+
+export function normalizeRelativePath(value, options = {}) {
+  const { allowRoot = false, label = "path" } = options;
+  if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+    fail("invalid-path", `${label} must be a non-empty relative path`);
+  }
+  if (path.isAbsolute(value) || hasParentSegment(value)) {
+    fail("path-outside-project", `${label} must stay inside the project`, {
+      details: { path: value },
+    });
+  }
+  const normalized = path.posix.normalize(value.replaceAll("\\", "/")).replace(/^\.\//u, "");
+  if ((!allowRoot && (normalized === "." || normalized === "")) || normalized.startsWith("../")) {
+    fail("invalid-path", `${label} is not a valid project-relative path`, {
+      details: { path: value },
+    });
+  }
+  return normalized;
+}
+
+export async function resolveProjectRoot(projectPath) {
+  if (typeof projectPath !== "string" || projectPath.length === 0) {
+    fail("invalid-project", "--project must name an existing directory");
+  }
+  let root;
+  try {
+    root = await realpath(projectPath);
+    const info = await lstat(root);
+    if (!info.isDirectory()) fail("invalid-project", "project path is not a directory");
+  } catch (error) {
+    if (error?.code === "invalid-project") throw error;
+    fail("invalid-project", `cannot access project directory: ${projectPath}`, { cause: error });
+  }
+  return root;
+}
+
+function isInside(root, target) {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+export async function resolveExistingInside(root, relativePath, options = {}) {
+  const normalized = normalizeRelativePath(relativePath, options);
+  const candidate = path.join(root, normalized);
+  let resolved;
+  try {
+    resolved = await realpath(candidate);
+  } catch (error) {
+    fail("source-missing", `project path does not exist: ${normalized}`, {
+      cause: error,
+      details: { path: normalized },
+    });
+  }
+  if (!isInside(root, resolved)) {
+    fail("path-outside-project", `resolved path leaves the project: ${normalized}`, {
+      details: { path: normalized },
+    });
+  }
+  return { normalized, absolute: resolved };
+}
+
+export async function resolveWritableInside(root, relativePath, options = {}) {
+  const normalized = normalizeRelativePath(relativePath, options);
+  const absolute = path.join(root, normalized);
+  const parent = path.dirname(absolute);
+  let existingParent = parent;
+  let resolvedParent;
+  while (resolvedParent === undefined) {
+    try {
+      resolvedParent = await realpath(existingParent);
+    } catch (error) {
+      if (error?.code !== "ENOENT" || existingParent === root) {
+        fail("invalid-output-parent", `cannot resolve output parent: ${path.posix.dirname(normalized)}`, {
+          cause: error,
+          details: { path: normalized },
+        });
+      }
+      existingParent = path.dirname(existingParent);
+    }
+  }
+  if (!isInside(root, resolvedParent)) {
+    fail("path-outside-project", `output parent leaves the project: ${normalized}`, {
+      details: { path: normalized },
+    });
+  }
+  if (options.createParent) {
+    const missingSegments = path.relative(existingParent, parent).split(path.sep).filter(Boolean);
+    let current = existingParent;
+    for (const segment of missingSegments) {
+      current = path.join(current, segment);
+      try {
+        await mkdir(current);
+      } catch (error) {
+        if (error?.code !== "EEXIST") {
+          fail("invalid-output-parent", `cannot create output parent: ${path.posix.dirname(normalized)}`, {
+            cause: error,
+            details: { path: normalized },
+          });
+        }
+      }
+      let resolved;
+      try {
+        resolved = await realpath(current);
+      } catch (error) {
+        fail("invalid-output-parent", `cannot resolve output parent: ${path.posix.dirname(normalized)}`, {
+          cause: error,
+          details: { path: normalized },
+        });
+      }
+      if (!isInside(root, resolved)) {
+        fail("path-outside-project", `output parent leaves the project: ${normalized}`, {
+          details: { path: normalized },
+        });
+      }
+    }
+  }
+  try {
+    const info = await lstat(absolute);
+    if (info.isSymbolicLink()) {
+      fail("output-symlink", `output cannot be a symlink: ${normalized}`, {
+        details: { path: normalized },
+      });
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return { normalized, absolute };
+}
+
+export function assertProjectionPath(target, normalized) {
+  if (target === "agents") {
+    if (path.posix.basename(normalized) !== "AGENTS.md") {
+      fail("invalid-projection-path", "agents projections must target an AGENTS.md file", {
+        details: { path: normalized, target },
+      });
+    }
+    return;
+  }
+  if (target === "ruler") {
+    if (!normalized.startsWith(".ruler/") || path.posix.extname(normalized) !== ".md") {
+      fail("invalid-projection-path", "ruler projections must be Markdown files inside .ruler/", {
+        details: { path: normalized, target },
+      });
+    }
+    return;
+  }
+  fail("invalid-target", `unsupported projection target: ${target}`);
+}

package/src/project-context/project-store.mjs

@@ -0,0 +1,138 @@
+import { access, mkdir, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { validateContract, validateProjectionLock, validateSourceLock } from "./contract-schema.mjs";
+import { fail } from "./errors.mjs";
+import { atomicWriteJson, readJsonFile } from "./io.mjs";
+
+export const CONTEXT_DIRECTORY = ".project-context";
+export const CONTRACT_FILE = "contract.json";
+export const SOURCES_LOCK_FILE = "sources.lock.json";
+export const PROJECTIONS_LOCK_FILE = "projections.lock.json";
+
+export function projectFiles(root) {
+  const directory = path.join(root, CONTEXT_DIRECTORY);
+  return {
+    directory,
+    contract: path.join(directory, CONTRACT_FILE),
+    sourcesLock: path.join(directory, SOURCES_LOCK_FILE),
+    projectionsLock: path.join(directory, PROJECTIONS_LOCK_FILE),
+  };
+}
+
+export function initialProjectFiles(id, name) {
+  return {
+    contract: {
+      schemaVersion: 1,
+      project: { id, name, root: "." },
+      sources: [],
+      items: [],
+    },
+    sourcesLock: { schemaVersion: 1, sources: [] },
+    projectionsLock: { schemaVersion: 1, projections: [] },
+  };
+}
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function initializeProject(root, id, name, write) {
+  const files = projectFiles(root);
+  const initial = initialProjectFiles(id, name);
+  validateContract(initial.contract);
+  validateSourceLock(initial.sourcesLock);
+  validateProjectionLock(initial.projectionsLock);
+  const existing = [];
+  if (await exists(files.directory)) existing.push(CONTEXT_DIRECTORY);
+  for (const filePath of [files.contract, files.sourcesLock, files.projectionsLock]) {
+    if (await exists(filePath)) existing.push(path.relative(root, filePath));
+  }
+  if (existing.length > 0) {
+    fail("project-already-initialized", "project context files already exist", { details: { paths: existing } });
+  }
+  if (write) {
+    const temporaryDirectory = `${files.directory}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+    try {
+      await mkdir(temporaryDirectory, { recursive: false });
+      await atomicWriteJson(path.join(temporaryDirectory, CONTRACT_FILE), initial.contract);
+      await atomicWriteJson(path.join(temporaryDirectory, SOURCES_LOCK_FILE), initial.sourcesLock);
+      await atomicWriteJson(path.join(temporaryDirectory, PROJECTIONS_LOCK_FILE), initial.projectionsLock);
+      await rename(temporaryDirectory, files.directory);
+    } catch (error) {
+      try {
+        await rm(temporaryDirectory, { recursive: true, force: true });
+      } catch {
+        // A failed cleanup is limited to this command's uniquely named temporary directory.
+      }
+      throw error;
+    }
+  }
+  return { files, preview: initial, written: Boolean(write) };
+}
+
+export async function loadProject(root) {
+  const files = projectFiles(root);
+  const contract = validateContract(await readJsonFile(files.contract, CONTRACT_FILE));
+  const sourcesLock = validateSourceLock(await readJsonFile(files.sourcesLock, SOURCES_LOCK_FILE));
+  const projectionsLock = validateProjectionLock(await readJsonFile(files.projectionsLock, PROJECTIONS_LOCK_FILE));
+  return {
+    files,
+    contract,
+    sourcesLock,
+    projectionsLock,
+    contractDigest: digestJson(contract),
+    sourcesLockDigest: digestJson(sourcesLock),
+    projectionsLockDigest: digestJson(projectionsLock),
+  };
+}
+
+export async function writeProjectState(project, nextContractInput, nextSourcesLockInput, options = {}) {
+  const writeJson = options.writeJson ?? atomicWriteJson;
+  const readJson = options.readJson ?? readJsonFile;
+  const nextContract = validateContract(structuredClone(nextContractInput));
+  const nextSourcesLock = validateSourceLock(structuredClone(nextSourcesLockInput));
+  const currentContract = validateContract(await readJson(project.files.contract, CONTRACT_FILE));
+  const currentSourcesLock = validateSourceLock(await readJson(project.files.sourcesLock, SOURCES_LOCK_FILE));
+  const currentProjectionsLock = validateProjectionLock(await readJson(project.files.projectionsLock, PROJECTIONS_LOCK_FILE));
+  if (
+    digestJson(currentContract) !== project.contractDigest ||
+    digestJson(currentSourcesLock) !== project.sourcesLockDigest ||
+    digestJson(currentProjectionsLock) !== project.projectionsLockDigest
+  ) {
+    fail("project-state-changed", "contract, source lock, or projection lock changed while the update was being prepared", { exitCode: 1 });
+  }
+
+  const contractChanged = canonicalJson(nextContract) !== canonicalJson(project.contract);
+  const sourcesLockChanged = canonicalJson(nextSourcesLock) !== canonicalJson(project.sourcesLock);
+  if (!contractChanged && !sourcesLockChanged) return;
+
+  if (sourcesLockChanged) await writeJson(project.files.sourcesLock, nextSourcesLock);
+  try {
+    if (contractChanged) await writeJson(project.files.contract, nextContract);
+  } catch (error) {
+    if (sourcesLockChanged) {
+      try {
+        const recoveryCurrent = validateSourceLock(await readJson(project.files.sourcesLock, SOURCES_LOCK_FILE));
+        if (canonicalJson(recoveryCurrent) !== canonicalJson(nextSourcesLock)) {
+          if (error && typeof error === "object") {
+            error.details = { ...(error.details ?? {}), recovery: "sources-lock-restore-skipped-concurrent-change" };
+          }
+        } else {
+          await writeJson(project.files.sourcesLock, project.sourcesLock);
+        }
+      } catch (recoveryError) {
+        if (error && typeof error === "object") {
+          error.details = { ...(error.details ?? {}), recovery: "sources-lock-restore-failed", recoveryMessage: recoveryError.message };
+        }
+      }
+    }
+    throw error;
+  }
+}