@clossys/launcher 0.3.1 → 0.4.0

package/src/apply-plan.ts

@@ -1,155 +1,128 @@
 // Apply an approved plan (#1178): writes clossys/brief.json into a staffed
-// repository from the exact EngagementBrief shape and plan.json contract
-// recorded on issue #1175 ("Plan file contract", posted 2026-09-22).
+// repository once clossys/advisor/plan.json is approved, both validated
+// against the shared plan and brief contracts (#1175, #1475).
 //
 // SCOPE OF THIS MODULE (see the wave-2 PR body for the full explanation):
 // this lands the mechanical, auditable core the landed contract fully
 // specifies -- reading clossys/advisor/plan.json, confirming it is
 // approved, validating an EngagementBrief, and writing clossys/brief.json
-// byte-identically. Multi-repository orchestration (branch creation, exact
-// package installs, Starter's caller workflow, opening one pull request
-// per repository) is deferred: the landed contract does not yet specify
-// how a plan's approved roles map to inventory repository ids or to
-// install/remove/relocate work items, and building that mapping now would
-// mean inventing an interface Advisor's still-open PR (#1193) might define
-// differently.
+// byte-identically. The plan contract now says which roles work in which
+// inventory repository (`staffing`) and which exact package acts are
+// authorized (`packages`), and approvedSubject() below says what an
+// approval binds (#1178). Multi-repository orchestration (computing each
+// repository's change, branch creation, exact package installs, Starter's
+// caller workflow, opening one pull request per repository) is not built
+// yet, and this module does not act on those fields.
 //
 // clossys/brief.json's shape is NOT re-derived here -- @clossys/advisor's
-// EngagementBrief export (landing in #1193) is the one owner of that
-// computation. This module receives an already-computed brief (as a file
-// path today; a direct call once #1193 lands and a caller can import the
-// package) and only validates its shape and writes it, exactly the split
-// #1187's governing principle draws between package-owned definition and
-// judgment versus Launcher's deterministic mechanics.
+// toEngagementBrief() is the one owner of that computation. This module
+// receives an already-computed brief and only validates it and writes it,
+// exactly the split #1187's governing principle draws between
+// package-owned definition and judgment versus Launcher's deterministic
+// mechanics.
+//
+// VALIDATION (issue #1475): see plan-contract.ts. There is no second,
+// hand-written shape check here to drift from Advisor's: a plan or brief
+// Advisor accepts, Launcher accepts, and every object in them is closed, so
+// an unknown field is refused. This package still has no runtime
+// dependency on @clossys/advisor.
 
+import { validateAdvisorPlan, validateEngagementBrief } from "./plan-contract.js";
+import type { AdvisorPlan, EngagementBrief, PlanDecision } from "./plan-contract.js";
+import { planDigest } from "./plan-digest.js";
 import type { WorkspaceHost } from "./types.js";
 
-export interface EngagementBriefRole {
-  readonly role: string;
-  readonly why: string;
-  readonly goal: { readonly metric: string; readonly direction: "increase" | "decrease" };
-  readonly inputsFrom: readonly string[];
-  readonly outputsTo: readonly string[];
-}
-
-export interface EngagementBrief {
-  readonly schemaVersion: 1;
-  readonly problem: string;
-  readonly roles: readonly EngagementBriefRole[];
-  readonly sequence: readonly string[];
-  readonly deliverables: readonly string[];
-}
-
-export type BlockerKind = "missing-input" | "missing-authority" | "failing-evidence" | "unavailable-environment" | "contradiction";
-
-export interface PlanBlocker {
-  readonly kind: BlockerKind;
-  readonly description: string;
-  readonly owner: string;
-  readonly dueDate?: string;
-}
-
-export interface PlanDecision {
-  readonly at: string;
-  readonly recommended: string;
-  readonly chosen: string;
-  readonly by: string;
-}
-
-export interface AdvisorPlan {
-  readonly schemaVersion: 1;
-  readonly asOf: string;
-  readonly mandate: { readonly problem: string; readonly primaryProblemId: string; readonly roles: readonly string[] };
-  readonly whereWeAre: readonly string[];
-  readonly recommendedNext: { readonly action: string; readonly owner: string; readonly due: string } | null;
-  readonly decisions: readonly PlanDecision[];
-  readonly blockers: readonly PlanBlocker[];
-}
+export { validateAdvisorPlan, validateEngagementBrief } from "./plan-contract.js";
+export type {
+  AdvisorPlan, BlockerKind, EngagementBrief, EngagementBriefRole, EngagementContext, EngagementContextField, EngagementContextFieldId, GoalDirection, PlanBlocker, PlanDecision,
+  PlanKit, PlanPackageAct, PlanStaffing, ValidationResult,
+} from "./plan-contract.js";
 
-export type ValidationResult = { readonly valid: true } | { readonly valid: false; readonly reason: string };
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function nonEmptyString(value: unknown): value is string {
-  return typeof value === "string" && value.trim() !== "";
-}
-function stringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === "string");
-}
-
-/** Validates an EngagementBrief's shape exactly against the #1175 contract. Never mutates, never re-derives content. */
-export function validateEngagementBrief(value: unknown): ValidationResult {
-  if (!isRecord(value)) return { valid: false, reason: "brief must be an object" };
-  if (value.schemaVersion !== 1) return { valid: false, reason: "brief.schemaVersion must be 1" };
-  if (!nonEmptyString(value.problem)) return { valid: false, reason: "brief.problem must be a non-empty string" };
-  if (!Array.isArray(value.roles) || value.roles.length === 0) return { valid: false, reason: "brief.roles must be a non-empty array" };
-  for (const [index, role] of value.roles.entries()) {
-    if (!isRecord(role)) return { valid: false, reason: `brief.roles[${index}] must be an object` };
-    if (!nonEmptyString(role.role)) return { valid: false, reason: `brief.roles[${index}].role must be a non-empty string` };
-    if (!nonEmptyString(role.why)) return { valid: false, reason: `brief.roles[${index}].why must be a non-empty string` };
-    if (!isRecord(role.goal) || !nonEmptyString(role.goal.metric) || (role.goal.direction !== "increase" && role.goal.direction !== "decrease")) {
-      return { valid: false, reason: `brief.roles[${index}].goal must have a metric and a direction of increase or decrease` };
-    }
-    if (!stringArray(role.inputsFrom)) return { valid: false, reason: `brief.roles[${index}].inputsFrom must be a string array` };
-    if (!stringArray(role.outputsTo)) return { valid: false, reason: `brief.roles[${index}].outputsTo must be a string array` };
-  }
-  if (!stringArray(value.sequence) || value.sequence.length === 0) return { valid: false, reason: "brief.sequence must be a non-empty string array" };
-  if (!stringArray(value.deliverables)) return { valid: false, reason: "brief.deliverables must be a string array" };
-  return { valid: true };
+/**
+ * The decisions made at the latest instant, by `at` -- never by array
+ * position -- or null when there are none, or when any decision's `at` does
+ * not parse to a finite time (the plan contract already refuses one; this
+ * does not rely on that), because then time cannot say which is latest.
+ */
+function latestDecisions(plan: AdvisorPlan): readonly PlanDecision[] | null {
+  if (plan.decisions.length === 0) return null;
+  const times = plan.decisions.map((decision) => Date.parse(decision.at));
+  if (!times.every(Number.isFinite)) return null;
+  // A reduce, not Math.max(...times): spreading a very long list into
+  // arguments throws a RangeError.
+  const latest = times.reduce((highest, time) => (time > highest ? time : highest), Number.NEGATIVE_INFINITY);
+  return plan.decisions.filter((_, index) => times[index] === latest);
 }
 
-const BLOCKER_KINDS = new Set<BlockerKind>(["missing-input", "missing-authority", "failing-evidence", "unavailable-environment", "contradiction"]);
+const SUBJECT_DIGEST = /^sha256:[0-9a-f]{64}$/;
 
-/** Validates an AdvisorPlan's shape exactly against the #1175 contract. */
-export function validateAdvisorPlan(value: unknown): ValidationResult {
-  if (!isRecord(value)) return { valid: false, reason: "plan must be an object" };
-  if (value.schemaVersion !== 1) return { valid: false, reason: "plan.schemaVersion must be 1" };
-  if (!nonEmptyString(value.asOf)) return { valid: false, reason: "plan.asOf must be a non-empty string" };
-  if (!isRecord(value.mandate) || !nonEmptyString(value.mandate.problem) || !nonEmptyString(value.mandate.primaryProblemId) || !stringArray(value.mandate.roles)) {
-    return { valid: false, reason: "plan.mandate must have problem, primaryProblemId, and a roles string array" };
-  }
-  if (!stringArray(value.whereWeAre)) return { valid: false, reason: "plan.whereWeAre must be a string array" };
-  if (value.recommendedNext !== null) {
-    if (!isRecord(value.recommendedNext) || !nonEmptyString(value.recommendedNext.action) || !nonEmptyString(value.recommendedNext.owner) || !nonEmptyString(value.recommendedNext.due)) {
-      return { valid: false, reason: "plan.recommendedNext must be null or have action, owner, and due" };
-    }
-  }
-  if (!Array.isArray(value.decisions)) return { valid: false, reason: "plan.decisions must be an array" };
-  for (const [index, decision] of value.decisions.entries()) {
-    if (!isRecord(decision) || !nonEmptyString(decision.at) || !nonEmptyString(decision.recommended) || !nonEmptyString(decision.chosen) || !nonEmptyString(decision.by)) {
-      return { valid: false, reason: `plan.decisions[${index}] must have at, recommended, chosen, and by` };
-    }
-  }
-  if (!Array.isArray(value.blockers)) return { valid: false, reason: "plan.blockers must be an array" };
-  for (const [index, blocker] of value.blockers.entries()) {
-    if (!isRecord(blocker) || !BLOCKER_KINDS.has(blocker.kind as BlockerKind) || !nonEmptyString(blocker.description) || !nonEmptyString(blocker.owner)) {
-      return { valid: false, reason: `plan.blockers[${index}] must have a valid kind, description, and owner` };
-    }
-  }
-  return { valid: true };
+/**
+ * What an approval binds (#1178): the `subjectDigest` of the plan's latest
+ * decision, by `at`, when that decision has chosen "approved" -- the digest of
+ * the exact change the approver was shown. Otherwise null, and null binds
+ * nothing. Fails closed:
+ *
+ * - a plan that does not validate against the plan contract, rules
+ *   included: null. It checks this itself rather than trusting its caller,
+ *   because on an unchecked plan a time with no offset parses as local time,
+ *   so the machine's time zone could decide which decision is latest;
+ * - no decisions, or any decision time that does not parse: null;
+ * - a latest decision that is not "approved": null;
+ * - an approval with no `subjectDigest`, or one that is not a sha256 digest:
+ *   null -- an approval that names no bytes approves no bytes;
+ * - several decisions at the latest instant: their subject only when every
+ *   one of them is "approved" with the same `subjectDigest`, else null.
+ *
+ * It says what was approved, not whether that is what is about to be applied:
+ * the caller recomputes the digest of the change it holds and refuses unless
+ * the two are equal.
+ */
+export function approvedSubject(plan: AdvisorPlan): string | null {
+  if (!validateAdvisorPlan(plan).valid) return null;
+  const latest = latestDecisions(plan);
+  if (latest === null || !latest.every((decision) => decision.chosen === "approved")) return null;
+  const subject = latest[0]!.subjectDigest;
+  if (typeof subject !== "string" || !SUBJECT_DIGEST.test(subject)) return null;
+  return latest.every((decision) => decision.subjectDigest === subject) ? subject : null;
 }
 
 /**
  * The plan is approved when its most recent decision (by `at`) records
  * chosen === "approved". No decisions, or a most-recent decision that
  * isn't "approved", is not approved -- this never assumes approval from
- * absence.
+ * absence. Fails closed on anything that would let array order decide
+ * instead of time: a decision whose `at` does not parse to a finite time
+ * (the plan contract already refuses one; this does not rely on that), or
+ * two decisions at the same latest instant that do not all say "approved".
+ *
+ * It binds no bytes (#1178): it does not look at `subjectDigest`, so it is
+ * true for an approval that names no change at all. It says only that the
+ * latest decision is an approval. Anything that applies a plan must use
+ * `approvedSubject()` instead, and compare the subject it returns with the
+ * digest of the change it holds. The one stated exception is the legacy
+ * brief-only path, `applyEngagementBrief()`, which predates the binding.
  */
 export function isPlanApproved(plan: AdvisorPlan): boolean {
-  if (plan.decisions.length === 0) return false;
-  const mostRecent = [...plan.decisions].sort((left, right) => Date.parse(left.at) - Date.parse(right.at)).at(-1);
-  return mostRecent?.chosen === "approved";
+  const latest = latestDecisions(plan);
+  return latest !== null && latest.every((decision) => decision.chosen === "approved");
 }
 
 export type ApplyBriefResult =
-  | { readonly state: "applied"; readonly path: string }
+  | { readonly state: "applied"; readonly path: string; readonly planDigest: string }
   | { readonly state: "refused"; readonly reason: string };
 
 /**
  * Writes clossys/brief.json into `repositoryDirectory`, byte-identically
  * from the validated brief -- never re-authors its prose. Refuses (does
- * not write) unless both the plan is approved and the brief validates.
+ * not write) unless the plan validates and is approved and the brief,
+ * including its context snapshot, validates. Reports the canonical digest
+ * of the plan it applied.
+ *
+ * LEGACY (#1178): this path predates the approval binding. It accepts an
+ * approval whether or not it carries a `subjectDigest` and checks no
+ * binding (it uses `isPlanApproved()`), exactly as before; it is kept
+ * working, not extended. Anything that must know what an approval binds uses
+ * `approvedSubject()`.
  */
 export function applyEngagementBrief(
   host: WorkspaceHost,
@@ -158,15 +131,30 @@ export function applyEngagementBrief(
   brief: EngagementBrief,
   briefRelPath: string,
 ): ApplyBriefResult {
+  const planValidation = validateAdvisorPlan(plan);
+  if (!planValidation.valid) {
+    return { state: "refused", reason: `plan does not validate: ${planValidation.reason}` };
+  }
   if (!isPlanApproved(plan)) {
-    return { state: "refused", reason: "the plan's most recent decision is not \"approved\"" };
+    return { state: "refused", reason: "the plan's most recent decision is not \"approved\", or decisions made at that same time disagree" };
   }
   const validation = validateEngagementBrief(brief);
   if (!validation.valid) {
     return { state: "refused", reason: `brief does not validate: ${validation.reason}` };
   }
+  // Everything that can refuse runs before the first write, so a refusal
+  // never leaves a brief behind. A plan that validates always has a digest
+  // (the contract refuses what canonical JSON cannot carry); this catch is
+  // the backstop that keeps that a refusal rather than a throw after writing.
+  let digest: string;
+  try {
+    digest = planDigest(plan);
+  } catch (cause) {
+    return { state: "refused", reason: `plan has no canonical digest: ${cause instanceof Error ? cause.message : String(cause)}` };
+  }
+  const contents = `${JSON.stringify(brief, null, 2)}\n`;
   const path = `${repositoryDirectory}/${briefRelPath}`;
   host.mkdirp(path.slice(0, path.lastIndexOf("/")));
-  host.writeText(path, `${JSON.stringify(brief, null, 2)}\n`);
-  return { state: "applied", path };
+  host.writeText(path, contents);
+  return { state: "applied", path, planDigest: digest };
 }

package/src/apply-step-fixture.ts

@@ -0,0 +1,236 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+  SITE_ID,
+  approvedPlan,
+  basePlan,
+  buildWorld,
+  bundleOf,
+  committedPlanPackages,
+  hubRepo,
+  lockfileText,
+  reseal,
+  siteRepo,
+} from "./admission-fixture.js";
+import type { HubOptions, World, WorldOptions } from "./admission-fixture.js";
+import { contentDigest, discoveryLinkRole, discoveryLinkTarget } from "./change-set-contract.js";
+import type { ApplyBundle, RepositoryChangeSet } from "./change-set-contract.js";
+import type { LockfileSpawn } from "./lockfile-regen.js";
+import type { AdvisorPlan } from "./plan-contract.js";
+import { planDigest } from "./plan-digest.js";
+
+export { reseal };
+
+const REPO = new URL("../../../", import.meta.url);
+const read = (path: string): string => readFileSync(new URL(path, REPO), "utf8");
+
+type Loose = Record<string, any>;
+
+const gitEnv = {
+  ...process.env,
+  PATH: process.env.PATH ?? "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+  GIT_CONFIG_GLOBAL: "/dev/null",
+  GIT_CONFIG_NOSYSTEM: "1",
+  GIT_AUTHOR_NAME: "Example Author",
+  GIT_AUTHOR_EMAIL: "author@example.com",
+  GIT_COMMITTER_NAME: "Example Author",
+  GIT_COMMITTER_EMAIL: "author@example.com",
+};
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", ...args], {
+    cwd,
+    env: gitEnv,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+}
+
+export interface MaterializedFixtureOptions {
+  /** Overrides for the hub: options, or a function of what the fixture built (its plan, its approved bundle and its set). */
+  readonly hub?: Partial<HubOptions> | ((built: { plan: AdvisorPlan; bundle: ApplyBundle; set: RepositoryChangeSet }) => Partial<HubOptions>);
+  /** Store the set, with its whole-file texts, in the hub's change-set store, where the command line finds it. Default false. */
+  readonly storeSet?: boolean;
+}
+
+/**
+ * A setup change set whose whole-file bytes are known, with the pin already
+ * satisfied and no lockfile to regenerate, checked out from a local clone, and
+ * a hub that approved it: a git repository whose HEAD holds a plan (its latest
+ * decision approves the bundle that holds the set) and an execution
+ * authorization, with the bundle stored and the hub's readiness executable
+ * installed. `binding` is the binding admission is expected to compute; it is
+ * never an input to materialize or verify.
+ */
+export function buildMaterializedFixture(roots: string[], options: MaterializedFixtureOptions = {}) {
+  const parent = mkdtempSync(join(tmpdir(), "launcher-apply-step-"));
+  roots.push(parent);
+  const origin = join(parent, "origin.git");
+  const clone = join(parent, "site");
+  mkdirSync(clone, { recursive: true });
+  git(clone, "init", "-b", "main");
+  git(clone, "config", "core.autocrlf", "false");
+  writeFileSync(join(clone, "README.md"), "# Site\n");
+  git(clone, "add", "README.md");
+  git(clone, "commit", "-m", "init");
+  execFileSync("git", ["init", "--bare", origin], { env: gitEnv, stdio: "ignore" });
+  git(clone, "remote", "add", "origin", origin);
+  git(clone, "push", "-u", "origin", "HEAD");
+  const baseCommit = git(clone, "rev-parse", "HEAD").trim();
+
+  const corpus = JSON.parse(read("docs/contracts/apply-change-set-digest.fixture.json")) as {
+    changeSets: { name: string; changeSet: RepositoryChangeSet }[];
+  };
+  const set = structuredClone(corpus.changeSets.find((entry) => entry.name === "setup-site")!.changeSet) as unknown as Loose;
+  set.repository.baseCommit = baseCommit;
+  set.keys = [];
+  set.deferred = [];
+  set.files = (set.files as Loose[]).filter((file) => file.path !== "package-lock.json");
+  for (const item of set.items as Loose[]) {
+    if (item.act === "pin-starter" || item.act === "install") item.satisfiedInBase = true;
+  }
+  const plan0 = basePlan() as unknown as AdvisorPlan;
+  set.planDigest = planDigest(plan0);
+  const texts: Record<string, string> = {};
+  for (const file of set.files as Loose[]) {
+    if (file.derived === true) continue;
+    if (file.mode === "120000") {
+      const role = discoveryLinkRole(file.path as string);
+      const target = discoveryLinkTarget(role!);
+      texts[file.path as string] = target;
+      file.before = null;
+      file.after = contentDigest(target);
+    } else {
+      const text = `fixture ${file.path}\n`;
+      texts[file.path as string] = text;
+      file.before = null;
+      file.after = contentDigest(text);
+    }
+  }
+  const sealed = reseal(set);
+  const bundle = bundleOf(plan0, [{ id: SITE_ID, set: sealed }]);
+  const built = { ...sealed, bundle: bundle.bundleDigest } as RepositoryChangeSet;
+  const plan = approvedPlan(bundle.bundleDigest, plan0);
+  const override = typeof options.hub === "function" ? options.hub({ plan, bundle, set: built }) : (options.hub ?? {});
+  // What the planner stores carries the whole-file texts, so the command line can write from the store alone.
+  const stored = { ...built, texts: Object.entries(texts).map(([path, text]) => ({ path, text })).sort((left, right) => left.path.localeCompare(right.path)) };
+  const hub = hubRepo(roots, { plans: [plan], sets: options.storeSet === true ? [stored] : [], bundles: [bundle], ...override });
+  const binding = { kind: "approved" as const, subjectDigest: bundle.bundleDigest };
+  return { clone: realpathSync(clone), hub: hub.hub, set: built, texts, binding, planPackages: committedPlanPackages(plan, SITE_ID), plan, bundle, origin };
+}
+
+export interface AdmittedFixtureOptions {
+  readonly world?: WorldOptions;
+  readonly hub?: Partial<HubOptions> | ((world: World) => Partial<HubOptions>);
+  /** How the setup set reached the default branch. Default `squash`: no ancestor of the setup branch. */
+  readonly mergeStyle?: "direct" | "squash";
+  /** Edits the base tree before it is committed. */
+  readonly tree?: (tree: World["tree"]) => void;
+  /** Store the apply set in the hub too. Default false. */
+  readonly storeApplySet?: boolean;
+}
+
+/**
+ * The two phases of one plan. The setup set was approved (the plan's latest
+ * decision approves the bundle that holds it), materialized and merged into
+ * the clone's default branch (by squash by default), and the apply set was
+ * then computed against the merged base and is held by a later run's bundle,
+ * which the hub stores. `spawn` stands in for the package manager: it
+ * regenerates the lockfile the apply set's installs write.
+ */
+export function buildAdmittedFixture(roots: string[], options: AdmittedFixtureOptions = {}) {
+  let site: ReturnType<typeof siteRepo> | undefined;
+  const world = buildWorld({
+    ...options.world,
+    commitBase: (tree) => {
+      options.tree?.(tree);
+      site = siteRepo(roots, tree, { mergeStyle: options.mergeStyle ?? "squash" });
+      const origin = join(dirname(site.clone), "origin.git");
+      execFileSync("git", ["init", "--bare", origin], { env: gitEnv, stdio: "ignore" });
+      git(site.clone, "remote", "add", "origin", origin);
+      git(site.clone, "push", "-u", "origin", "main");
+      return site.baseCommit;
+    },
+  });
+  const override = typeof options.hub === "function" ? options.hub(world) : (options.hub ?? {});
+  const hub = hubRepo(roots, {
+    plans: [world.plan],
+    sets: options.storeApplySet === true ? [world.setup, world.apply] : [world.setup],
+    bundles: [world.approvedBundle, world.applyBundle],
+    ...override,
+  });
+  const packages = committedPlanPackages(world.plan, SITE_ID);
+  const spawn: LockfileSpawn = async (request) => {
+    if (request.args.includes("--version")) return { status: 0, stdout: "10.9.0\n", stderr: "" };
+    writeFileSync(join(request.cwd, "package-lock.json"), lockfileText(packages));
+    return { status: 0, stdout: "", stderr: "" };
+  };
+  return {
+    world,
+    hub: hub.hub,
+    clone: site!.clone,
+    baseCommit: site!.baseCommit,
+    sideTip: site!.sideTip,
+    set: world.apply,
+    setup: world.setup,
+    texts: world.texts,
+    spawn,
+  };
+}
+
+function walk(root: string, skip: (relative: string) => boolean, into: string[], relative = ""): void {
+  let names: string[];
+  try {
+    names = readdirSync(join(root, relative)).sort();
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const path = relative === "" ? name : `${relative}/${name}`;
+    if (skip(path)) continue;
+    const stat = lstatSync(join(root, path));
+    if (stat.isDirectory()) walk(root, skip, into, path);
+    else if (stat.isSymbolicLink()) into.push(`${path} -> ${readlinkSync(join(root, path))}`);
+    else into.push(`${path} ${createHash("sha256").update(readFileSync(join(root, path))).digest("hex")} ${stat.mode & 0o777}`);
+  }
+}
+
+/**
+ * Everything a refused materialize must leave alone: the clone's refs, HEAD,
+ * index, status and every file outside .git, and every file the hub keeps
+ * under clossys/.state. Two snapshots are equal only when nothing moved.
+ */
+export function writeSnapshot(clone: string, hub: string): string {
+  const files: string[] = [];
+  walk(clone, (path) => path === ".git", files);
+  const hubFiles: string[] = [];
+  walk(join(hub, "clossys", ".state"), () => false, hubFiles);
+  return JSON.stringify({
+    refs: git(clone, "for-each-ref").trim(),
+    head: git(clone, "rev-parse", "HEAD").trim(),
+    branch: git(clone, "rev-parse", "--abbrev-ref", "HEAD").trim(),
+    index: git(clone, "ls-files", "-s").trim(),
+    status: git(clone, "status", "--porcelain", "--untracked-files=all").trim(),
+    files,
+    hub: hubFiles,
+  });
+}
+
+/** Whether the clone holds a local branch of this name. */
+export function branchExists(clone: string, branch: string): boolean {
+  try {
+    git(clone, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The ledger a clone holds at clossys/.state/installed.json, parsed, or null when it holds none. */
+export function readCloneLedger(clone: string): Loose | null {
+  const path = join(clone, "clossys/.state/installed.json");
+  return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Loose) : null;
+}