@intentius/chant 0.90.0 → 0.91.0

package/src/lifecycle/lease.ts

@@ -33,7 +33,7 @@
  */
 import { hostname } from "node:os";
 import { randomUUID } from "node:crypto";
-import { readRefSha, updateRefCAS, deleteRefCAS, writeBlob, readBlobBySha, pushRef, fetchRefInto, RefCASConflictError } from "./git";
+import { readRefSha, updateRefCAS, deleteRefCAS, writeBlob, readBlobBySha, pushRefStatus, fetchRefIntoStatus, RefCASConflictError, StaleLockError } from "./git";
 import { resolveMemberLedger } from "./member-ledger";
 
 export const LEASE_REF_PREFIX = "refs/chant/lease/";
@@ -95,7 +95,7 @@ function leaseFreshnessKey(record?: LeaseRecord): string {
   return record ? `${record.acquiredAt} ${record.expiresAt}` : "";
 }
 
-/** One lease's live state — the entire durable record; there is no history, only the current holder (see this module's doc on why no separate ledger). */
+/** One lease's live state: the current holder only. An operator lease keeps no history; a work lease (./work-lease.ts) appends each change to `_leases/<id>.jsonl` beside it. */
 export interface LeaseRecord {
   op: string;
   /** `<hostname>:<pid>:<random>` — a diagnostic identity, not itself the fencing mechanism (`token` is). */
@@ -137,6 +137,23 @@ export interface ReadLeaseResult {
   /** The ref's current SHA (the CAS anchor for the next write), or `null` if no lease has ever been written. */
   sha: string | null;
   record?: LeaseRecord;
+  /**
+   * The value of the remote-tracking ref (`refs/chant/lease-remote/<op>`)
+   * after the fetch: what the remote held when last seen, or `null` when it
+   * held nothing. The `--force-with-lease` expectation of the next push
+   * (#2732).
+   */
+  remoteSha: string | null;
+}
+
+/** Options every lease read and write takes. `cwd` also picks the ledger, and so the member prefix of the refs (./member-ledger.ts). */
+export interface LeaseOptions {
+  cwd?: string;
+}
+
+async function readRecordAt(ref: string, opts?: { cwd?: string }): Promise<{ sha: string | null; record?: LeaseRecord }> {
+  const sha = await readRefSha(ref, opts);
+  return { sha, record: sha ? parseLease((await readBlobBySha(sha, opts)) ?? "") : undefined };
 }
 
 /**
@@ -159,26 +176,76 @@ export interface ReadLeaseResult {
  * against — is always the local ref's own actual value; only the local
  * canonical ref is ever a valid basis for a `updateRefCAS`/`deleteRefCAS`
  * call against it, regardless of what the comparison decided about `record`.
+ *
+ * When the remote answers without the ref, the lease was released there, and
+ * the tracking ref is dropped so a stale copy of it no longer counts (#2732).
+ * A read-only report that must stay off the network reads the refs itself
+ * (`./work-lease.ts`'s `listWorkLeases`).
  */
-export async function readLease(opName: string, opts?: { cwd?: string }): Promise<ReadLeaseResult> {
+export async function readLease(opName: string, opts?: LeaseOptions): Promise<ReadLeaseResult> {
   const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
-  await fetchRefInto(ref, trackingRef, opts).catch(() => undefined);
-
-  const sha = await readRefSha(ref, opts);
-  const localRecord = sha ? parseLease((await readBlobBySha(sha, opts)) ?? "") : undefined;
+  const fetched = await fetchRefIntoStatus(ref, trackingRef, opts).catch(() => "failed" as const);
+  if (fetched === "missing") {
+    const stale = await readRefSha(trackingRef, opts);
+    if (stale) await deleteRefCAS(trackingRef, stale, opts).catch(() => undefined);
+  }
 
-  const remoteSha = await readRefSha(trackingRef, opts);
-  const remoteRecord = remoteSha ? parseLease((await readBlobBySha(remoteSha, opts)) ?? "") : undefined;
+  const { sha, record: localRecord } = await readRecordAt(ref, opts);
+  const { sha: remoteSha, record: remoteRecord } = await readRecordAt(trackingRef, opts);
 
   const record = leaseFreshnessKey(remoteRecord) > leaseFreshnessKey(localRecord) ? remoteRecord : localRecord;
-  return { sha, record };
+  return { sha, record, remoteSha };
 }
 
+/** Why {@link acquireLease} did not acquire (#2732). */
+export type LeaseRefusal =
+  /** Someone holds it live: another holder, or, under `mode: "claim"`, anyone. */
+  | "held"
+  /** `mode: "renew"` and nobody holds it live any more: it expired or was released. */
+  | "not-held"
+  /** `mode: "renew"` and the live lease has another token than the one given. */
+  | "token-mismatch"
+  /** Another writer changed the ref between this call's read and its write. */
+  | "race"
+  /** `requirePush` and the remote refused the push: another clone got there first, or the remote could not be reached. */
+  | "push-rejected";
+
 export interface AcquireLeaseResult {
   acquired: boolean;
   lease?: LeaseRecord;
   /** Present when not acquired: the lease record currently held by someone else. */
   heldBy?: LeaseRecord;
+  /** Present when not acquired: why (#2732). */
+  reason?: LeaseRefusal;
+}
+
+/** Options for {@link acquireLease}. */
+export interface AcquireLeaseOptions extends LeaseOptions {
+  ttlMs?: number;
+  now?: () => Date;
+  /**
+   * `acquire` (the default, the operator's): take it when free or expired,
+   * renew it when `holder` already holds it. `claim`: take it only when free
+   * or expired, and refuse even its own holder. `renew`: only move the expiry
+   * of a live lease `holder` holds (#2732).
+   */
+  mode?: "acquire" | "claim" | "renew";
+  /** With `mode: "renew"`, the token the caller holds; a live lease with another token is refused. */
+  token?: string;
+  /**
+   * Count the write only once the remote has taken it, when there is a
+   * remote. A rejected push undoes the local write and refuses with
+   * `push-rejected`, so two clones racing for one lease cannot both hold it.
+   * The operator leaves it off: its push is best-effort (#2732).
+   */
+  requirePush?: boolean;
+  /**
+   * Wait out a `.lock` another process holds on the ref for up to this long,
+   * retrying, before surfacing it as a {@link StaleLockError}. A lock left by
+   * a killed process outlives the wait; one held by a racing writer does
+   * not. Off (0) by default, as the operator has always had it.
+   */
+  lockWaitMs?: number;
 }
 
 /**
@@ -198,22 +265,42 @@ export interface AcquireLeaseResult {
  * against a lease nobody can ever actually acquire again without manual
  * intervention. It propagates instead, so the caller (`../op/operator.ts`'s
  * `runOperatorRound`) can surface it as its own distinct, diagnosable event
- * rather than a silent, permanent skip.
+ * rather than a silent, permanent skip. `lockWaitMs` waits a racing writer's
+ * lock out first.
+ *
+ * `mode`, `token` and `requirePush` are the work lease's (#2732,
+ * ./work-lease.ts); the operator uses none of them.
  */
 export async function acquireLease(
   opName: string,
   holder: string,
-  opts?: { cwd?: string; ttlMs?: number; now?: () => Date },
+  opts?: AcquireLeaseOptions,
 ): Promise<AcquireLeaseResult> {
+  const deadline = Date.now() + (opts?.lockWaitMs ?? 0);
+  for (;;) {
+    try {
+      return await acquireOnce(opName, holder, opts);
+    } catch (err) {
+      if (!(err instanceof StaleLockError) || Date.now() >= deadline) throw err;
+      await new Promise((r) => setTimeout(r, 20 + Math.floor(Math.random() * 60)));
+    }
+  }
+}
+
+async function acquireOnce(opName: string, holder: string, opts?: AcquireLeaseOptions): Promise<AcquireLeaseResult> {
   const ttlMs = opts?.ttlMs ?? DEFAULT_LEASE_TTL_MS;
   const now = opts?.now?.() ?? new Date();
+  const mode = opts?.mode ?? "acquire";
 
-  const { sha, record: current } = await readLease(opName, opts);
+  const { sha, record: current, remoteSha } = await readLease(opName, opts);
   const expired = !current || isExpired(current, now);
   const ownedByUs = current?.holder === holder;
 
-  if (current && !expired && !ownedByUs) {
-    return { acquired: false, heldBy: current };
+  if (mode === "renew") {
+    if (!current || expired || !ownedByUs) return { acquired: false, reason: current && !expired ? "held" : "not-held", ...(current ? { heldBy: current } : {}) };
+    if (opts?.token !== undefined && current.token !== opts.token) return { acquired: false, reason: "token-mismatch", heldBy: current };
+  } else if (current && !expired && (!ownedByUs || mode === "claim")) {
+    return { acquired: false, heldBy: current, reason: "held" };
   }
 
   const renewing = !!current && ownedByUs && !expired;
@@ -225,21 +312,31 @@ export async function acquireLease(
     expiresAt: new Date(now.getTime() + ttlMs).toISOString(),
   };
 
-  const { ref } = await projectLeaseRefs(opName, opts);
+  const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
   const blobSha = await writeBlob(JSON.stringify(record), opts);
   try {
     await updateRefCAS(ref, blobSha, sha, opts);
   } catch (err) {
     if (err instanceof RefCASConflictError) {
       const retry = await readLease(opName, opts);
-      return { acquired: false, heldBy: retry.record };
+      return { acquired: false, heldBy: retry.record, reason: "race" };
     }
     // A StaleLockError (or any other non-CAS failure) is NOT "someone else
     // has it" — propagate it as its own distinct error rather than folding
     // it into `heldBy`, per this function's doc.
     throw err;
   }
-  await pushRef(ref, opts).catch(() => undefined);
+  const pushed = await pushRefStatus(ref, { ...opts, expect: remoteSha }).catch(() => "rejected" as const);
+  if (pushed === "pushed") {
+    // What the remote holds now; the next push expects it.
+    await updateRefCAS(trackingRef, blobSha, remoteSha, opts).catch(() => undefined);
+  } else if (pushed === "rejected" && opts?.requirePush) {
+    // Undo the local write, which the remote refused, and report who has it there.
+    await (sha === null ? deleteRefCAS(ref, blobSha, opts) : updateRefCAS(ref, sha, blobSha, opts)).catch(() => undefined);
+    const retry = await readLease(opName, opts);
+    const heldBy = retry.record && retry.record.token !== record.token ? retry.record : undefined;
+    return { acquired: false, reason: "push-rejected", ...(heldBy ? { heldBy } : {}) };
+  }
   return { acquired: true, lease: record };
 }
 
@@ -249,23 +346,30 @@ export async function acquireLease(
  * silently drop someone else's. Best-effort courtesy: a lease nobody
  * releases is reclaimed anyway once its TTL passes, so a failed release
  * (returns `false`, never throws) is not itself a correctness problem.
+ *
+ * The deletion is pushed to the remote, expecting the value last fetched
+ * there, so another clone sees the lease free without waiting out its TTL
+ * (#2732).
  */
 export async function releaseLease(
   opName: string,
   holder: string,
   token: string,
-  opts?: { cwd?: string },
+  opts?: LeaseOptions,
 ): Promise<boolean> {
-  const { sha, record } = await readLease(opName, opts);
-  if (!sha || !record || record.holder !== holder || record.token !== token) return false;
-  const { ref } = await projectLeaseRefs(opName, opts);
-  try {
-    await deleteRefCAS(ref, sha, opts);
-  } catch {
-    return false;
+  const { sha, record, remoteSha } = await readLease(opName, opts);
+  if (!record || record.holder !== holder || record.token !== token) return false;
+  const { ref, trackingRef } = await projectLeaseRefs(opName, opts);
+  if (sha) {
+    try {
+      await deleteRefCAS(ref, sha, opts);
+    } catch {
+      return false;
+    }
   }
-  await pushRef(ref, opts).catch(() => undefined);
-  return true;
+  const pushed = await pushRefStatus(ref, { ...opts, expect: remoteSha }).catch(() => "rejected" as const);
+  if (pushed === "pushed" && remoteSha) await deleteRefCAS(trackingRef, remoteSha, opts).catch(() => undefined);
+  return sha !== null || pushed === "pushed";
 }
 
 /**
@@ -278,7 +382,7 @@ export async function stillHoldsLease(
   opName: string,
   holder: string,
   token: string,
-  opts?: { cwd?: string },
+  opts?: LeaseOptions,
 ): Promise<boolean> {
   const { record } = await readLease(opName, opts);
   return record?.holder === holder && record?.token === token;

package/src/lifecycle/member-ledger.ts

@@ -5,8 +5,9 @@
  * A workspace member writes every lifecycle store under
  * `_members/<member>/` on the one existing branch: releases, snapshots, runs,
  * converge records and observation baselines under `<env>/`, gates under
- * `_gates/`, build records under `_builds/`. Its operator leases move the same
- * way, to `refs/chant/lease/_members/<member>/<op>`. Push, fetch, lease and
+ * `_gates/`, build records under `_builds/`, release plans under `_plans/`
+ * (ws-055, #2733). Its operator leases move the same way, to
+ * `refs/chant/lease/_members/<member>/<op>`. Push, fetch, lease and
  * staleness code are untouched: they still see one branch and plain refs.
  *
  * Everything else keeps today's flat layout, byte for byte:

package/src/lifecycle/plan-ledger.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { persistReleasePlan, readReleasePlan, InvalidReleasePlanError, type ReleasePlan } from "./plan-ledger";
+import { readRefSha } from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+function makePlan(digest: string, extra: Record<string, unknown> = {}): ReleasePlan {
+  return { digest, release: "r-abc12345", units: [{ id: "w-1", contract: "c-1" }], evidence: [], ...extra };
+}
+
+describe("lifecycle/plan-ledger", () => {
+  describe("persistReleasePlan / readReleasePlan", () => {
+    test("round-trips a plan by its own digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "1".repeat(64));
+
+        const { commit, written } = await persistReleasePlan(plan, { cwd: dir });
+        expect(written).toBe(true);
+        expect(commit).toMatch(/^[0-9a-f]{40}$/);
+
+        const readBack = await readReleasePlan(plan.digest, { cwd: dir });
+        expect(readBack).toEqual(plan);
+      });
+    });
+
+    test("readReleasePlan returns null for an unknown digest", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        expect(await readReleasePlan("sha256:doesnotexist", { cwd: dir })).toBeNull();
+      });
+    });
+
+    test("a plan already written is never rewritten: no second commit, content unchanged", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "2".repeat(64));
+
+        const first = await persistReleasePlan(plan, { cwd: dir });
+        expect(first.written).toBe(true);
+        const tipAfterFirst = await readRefSha("refs/heads/chant/lifecycle", { cwd: dir });
+
+        const second = await persistReleasePlan(plan, { cwd: dir });
+        expect(second.written).toBe(false);
+        expect(second.commit).toBeNull();
+        const tipAfterSecond = await readRefSha("refs/heads/chant/lifecycle", { cwd: dir });
+
+        // Not a new commit — the branch tip is unchanged.
+        expect(tipAfterSecond).toBe(tipAfterFirst);
+        expect(await readReleasePlan(plan.digest, { cwd: dir })).toEqual(plan);
+      });
+    });
+
+    test("a plan with a different digest is a separate entry, coexisting with the first", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const planA = makePlan("sha256:" + "a".repeat(64), { release: "r-a" });
+        const planB = makePlan("sha256:" + "b".repeat(64), { release: "r-b" });
+
+        await persistReleasePlan(planA, { cwd: dir });
+        await persistReleasePlan(planB, { cwd: dir });
+
+        expect(await readReleasePlan(planA.digest, { cwd: dir })).toEqual(planA);
+        expect(await readReleasePlan(planB.digest, { cwd: dir })).toEqual(planB);
+      });
+    });
+
+    test("refuses a plan with no digest field", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = { release: "r-nodigest" } as unknown as ReleasePlan;
+        await expect(persistReleasePlan(plan, { cwd: dir })).rejects.toThrow(InvalidReleasePlanError);
+      });
+    });
+
+    test("release ledger and plan store coexist on the same orphan branch", async () => {
+      const { appendReleaseRecord, readReleaseLedger } = await import("./release-ledger");
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const plan = makePlan("sha256:" + "3".repeat(64));
+        await persistReleasePlan(plan, { cwd: dir });
+        await appendReleaseRecord(
+          {
+            component: "svc",
+            env: "prod",
+            digest: plan.digest,
+            gitSha: "deadbeef",
+            runId: "run-1",
+            timestamp: "2026-01-01T00:00:00.000Z",
+            actor: "ci-bot",
+          },
+          { cwd: dir },
+        );
+
+        expect(await readReleasePlan(plan.digest, { cwd: dir })).toEqual(plan);
+        const { records } = await readReleaseLedger("prod", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(records[0].digest).toBe(plan.digest);
+      });
+    });
+
+    test("a member's plan lives under _members/<member>/_plans/ (#2524 D7), reached via the prefix readReleasePlan takes", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        mkdirSync(join(dir, "apps", "web"), { recursive: true });
+        writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({
+          name: "acme",
+          schema: 1,
+          members: [{ name: "web", dir: "apps/web", kind: "chant" }],
+        }));
+        writeFileSync(join(dir, "apps", "web", "chant.config.ts"), "");
+        git(["add", "-A"], dir);
+        git(["commit", "-q", "-m", "workspace"], dir);
+
+        const plan = makePlan("sha256:" + "4".repeat(64));
+        // Persisted from inside the member's own directory, the way `chant
+        // components release` runs there — writeBlobToPath resolves the
+        // _members/web/ prefix automatically from cwd.
+        const webDir = join(dir, "apps", "web");
+        await persistReleasePlan(plan, { cwd: webDir });
+
+        // readReleasePlan reads it back two ways: with the matching prefix
+        // (as ../workspace/status.ts resolves it for a "members"-layout
+        // release), and directly at the branch path it actually landed on.
+        expect(await readReleasePlan(plan.digest, { cwd: dir, prefix: "_members/web/" })).toEqual(plan);
+        const raw = git(["show", `chant/lifecycle:_members/web/_plans/sha256_${"4".repeat(64)}.json`], dir);
+        expect(raw.exitCode).toBe(0);
+        expect(JSON.parse(raw.stdout)).toEqual(plan);
+      });
+    });
+  });
+});

package/src/lifecycle/plan-ledger.ts

@@ -0,0 +1,158 @@
+/**
+ * Release plan store (ws-055, #2733, part of the chud retirement epic
+ * #2715): persists a release plan — the work items and evidence a release
+ * ships — to the `chant/lifecycle` orphan branch, content-addressed by the
+ * plan's own digest.
+ *
+ * **Why this exists.** ws-055 (docs/design/decisions/ws-055-dev-model-
+ * ledgers.md) decided where a development model's plans live: "a release
+ * plan is written content-addressed to `_plans/<digest>.json` on
+ * chant/lifecycle, and the release ledger record already names that
+ * digest." A `ReleaseRecord.digest` (../lifecycle/release-ledger.ts) is
+ * ordinarily an artifact digest; for a release a runner (the studio kit
+ * today, chud before it) plans work-item by work-item, that same field
+ * *is* the plan's own digest — the release ledger needs no new field to
+ * point at it, it already names the plan. Reading a release through the
+ * read contract (../workspace/status.ts) resolves that digest to the plan
+ * exactly the way it already resolves a build archive digest to a
+ * `BuildArchiveManifest` (./build-ledger-store.ts) — this module is that
+ * store's plan-shaped sibling, same plumbing, same directory-per-kind
+ * convention on the one orphan branch.
+ *
+ * **Storage.** Reuses `writeBlobToPath`/`readBlobFromPath` (./git.ts) —
+ * the identical hash-object -> mktree -> commit-tree -> update-ref
+ * pipeline `writeSnapshot`/`persistBuildManifest` already use. Plans live
+ * under a fixed top-level `_plans/` directory, a peer of `_builds/` and the
+ * per-env directories, never nested inside one — a plan is not env-scoped,
+ * it is named by its own content. Per #2524 D7 / #2538, `writeBlobToPath`'s
+ * `ledgerDir` already folds a workspace member's own `_members/<member>/`
+ * prefix in ahead of `_plans/`, so a member's plans live at
+ * `_members/<member>/_plans/<digest>.json` the same way its build records
+ * live at `_members/<member>/_builds/` — this module does nothing itself
+ * to earn that; it falls out of reusing the shared plumbing.
+ *
+ * **Content-addressed, keyed by the plan's own `digest`.** One file per
+ * plan, `_plans/<digest-with-":"->"_">.json` (`:` is not usable in a git
+ * tree entry name the way `readBlobFromPath`'s `<ref>:<path>` spelling
+ * reads it back, the same reason `./build-ledger-store.ts` substitutes it
+ * for `_builds/`). The digest is computed by whoever plans the release —
+ * the release Op, or a runner like the studio kit — not by chant; this
+ * module only trusts and stores it, exactly as `persistBuildManifest`
+ * trusts a manifest's own `manifestDigest`.
+ *
+ * **A plan already written is never rewritten (#2733 acceptance).**
+ * Unlike `persistBuildManifest`, which writes unconditionally every call
+ * (safe only because identical content produces an identical blob and,
+ * usually, an identical tree — but still a new, redundant commit on the
+ * branch each time), `persistReleasePlan` reads the path first and returns
+ * without writing when a plan is already stored under that digest. A plan
+ * is immutable by construction (it is named by a hash of its own content),
+ * so there is never a reason to overwrite one — only ever a reason to skip
+ * the write.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { writeBlobToPath, readBlobFromPath, RefCASConflictError } from "./git";
+
+/** Fixed top-level directory on the `chant/lifecycle` orphan branch that holds every persisted release plan — a peer of `_builds/` and the per-env directories, never nested inside one (see module doc for why). */
+const PLANS_DIR = "_plans";
+
+/**
+ * A release plan (ws-055): the work items and evidence a release ships.
+ * chant does not own this shape — it is a runner's own record, the way a
+ * record kind's schema is the kind's own (../workspace/records.ts) — only
+ * `digest` is required, since it is the storage key. Every other field is
+ * read back and returned exactly as written.
+ */
+export interface ReleasePlan {
+  /**
+   * Content-addressed digest of this plan (`sha256:...`) — the same digest
+   * the release ledger record names (`ReleaseRecord.digest`,
+   * ../lifecycle/release-ledger.ts), so a record leads to its plan.
+   * Computed by the caller before persisting; this module trusts it rather
+   * than recomputing it, the same way `persistBuildManifest` trusts a
+   * manifest's own `manifestDigest`.
+   */
+  digest: string;
+  [key: string]: unknown;
+}
+
+/** Thrown by `persistReleasePlan` when the plan carries no usable `digest` — a plan can't be content-addressed without one. */
+export class InvalidReleasePlanError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidReleasePlanError";
+  }
+}
+
+/** Turn a `sha256:...`-style digest into a filesystem/git-tree-safe filename stem. */
+function digestToFilenameStem(digest: string): string {
+  return digest.replace(/:/g, "_");
+}
+
+function planFilename(digest: string): string {
+  return `${digestToFilenameStem(digest)}.json`;
+}
+
+/**
+ * Persist a release plan to the orphan branch, keyed by its own `digest`.
+ * Does not push to the remote — call `pushLifecycle` (./git.ts) afterward,
+ * the same two-step (`write` then `push`) shape `appendReleaseRecord`/
+ * `persistBuildManifest` use, so a caller persisting a plan alongside the
+ * release record it names can batch both into one push.
+ *
+ * Never rewrites a plan already stored under `plan.digest` (#2733
+ * acceptance) — reads the path first, and returns `{ commit: null, written:
+ * false }` without writing when it is already there. A `RefCASConflictError`
+ * from a genuine race (another writer persisted the same digest's plan
+ * between this call's read and its write) is treated the same way: the
+ * plan is content-addressed, so whatever is already at that path under this
+ * digest is authoritative, never overwritten.
+ */
+export async function persistReleasePlan(
+  plan: ReleasePlan,
+  opts?: { cwd?: string },
+): Promise<{ commit: string | null; written: boolean }> {
+  if (typeof plan.digest !== "string" || plan.digest.length === 0) {
+    throw new InvalidReleasePlanError("release plan is missing its own \"digest\" field — a release plan is content-addressed by its own digest");
+  }
+  const filename = planFilename(plan.digest);
+  const existing = await readBlobFromPath(PLANS_DIR, filename, opts);
+  if (existing !== null) return { commit: null, written: false };
+
+  const json = JSON.stringify(plan, sortedJsonReplacer);
+  try {
+    const commit = await writeBlobToPath(PLANS_DIR, filename, json, "Release plan", { ...opts, expectPriorPathSha: null });
+    return { commit, written: true };
+  } catch (err) {
+    if (err instanceof RefCASConflictError) return { commit: null, written: false };
+    throw err;
+  }
+}
+
+/**
+ * Read a persisted release plan back by its own digest — the same digest a
+ * `ReleaseRecord.digest` names. Returns `null` when no plan was ever
+ * persisted under that digest (never throws — most releases carry no plan
+ * at all, and reading one for status is a normal, expected miss), and when
+ * the stored blob fails to parse as JSON.
+ *
+ * `prefix` lets a multi-member reader (../workspace/status.ts) resolve a
+ * specific member's plan directory directly, the same way
+ * `readReleaseLedgerLines` is handed an already-member-prefixed path there
+ * — `cwd` alone can't do it, since one status read walks every member from
+ * one process without changing directory per member.
+ */
+export async function readReleasePlan(
+  digest: string,
+  opts?: { cwd?: string; prefix?: string },
+): Promise<ReleasePlan | null> {
+  const dir = `${opts?.prefix ?? ""}${PLANS_DIR}`;
+  const content = await readBlobFromPath(dir, planFilename(digest), opts);
+  if (!content) return null;
+  try {
+    return JSON.parse(content) as ReleasePlan;
+  } catch {
+    return null;
+  }
+}