@intentius/chant 0.79.0 → 0.81.0

package/src/lifecycle/legacy-digest.test.ts

@@ -0,0 +1,206 @@
+/**
+ * chant #2514 — digests recorded before real SHA-256. A project whose release
+ * ledger or build manifests hold values from the old 32-bit `contentDigest`
+ * is told once; those records read back flagged `legacy-digest`, and nothing
+ * is re-keyed or rewritten.
+ */
+import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  LEGACY_DIGEST_ACCEPTED_THROUGH,
+  LEGACY_DIGEST_FLAG,
+  flagLegacyDigest,
+  isLegacyContentDigest,
+  resetLegacyDigestWarnings,
+  warnOnLegacyDigests,
+} from "./legacy-digest";
+import { appendReleaseRecord, readReleaseLedger, type ReleaseRecord, type ReleaseRecordInput } from "./release-ledger";
+import {
+  findBuildManifestByArtifactDigest,
+  persistBuildManifest,
+  readAllBuildManifests,
+  readBuildManifest,
+} from "./build-ledger-store";
+import { readBlobFromPath } from "./git";
+import { compareAcrossEnvironments } from "./status";
+import { addArchiveEntry, contentDigest, createBuildArchiveManifest } from "../components/verbs/build-archive";
+
+/** The 32-bit hash chant labelled `sha256:` up to 0.80.0, kept here to make old values. */
+function legacyContentDigest(input: string): string {
+  let hash = 0;
+  for (let i = 0; i < input.length; i++) {
+    hash = (Math.imul(hash, 31) + input.charCodeAt(i)) | 0;
+  }
+  const hex = Math.abs(hash).toString(16).padStart(8, "0");
+  return `sha256:${hex.repeat(8).slice(0, 64)}`;
+}
+
+function git(args: string[], cwd: string): void {
+  spawnSync("git", args, { cwd, encoding: "utf-8" });
+}
+
+function initRepo(dir: string): 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 release(digest: string, runId: string): ReleaseRecordInput {
+  return {
+    component: "web",
+    env: "prod",
+    digest,
+    gitSha: "deadbeef",
+    runId,
+    timestamp: "2026-01-01T00:00:00.000Z",
+    actor: "ci-bot",
+  };
+}
+
+const realSha256 = `sha256:${createHash("sha256").update("x").digest("hex")}`;
+
+describe("legacy content digests (#2514)", () => {
+  let warn: { mock: { calls: unknown[][] }; mockRestore(): void };
+
+  beforeEach(() => {
+    resetLegacyDigestWarnings();
+    warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+    resetLegacyDigestWarnings();
+  });
+
+  const legacyWarnings = () => warn.mock.calls.filter((c: unknown[]) => String(c[0]).includes("issues/2514"));
+
+  test("the old contentDigest output is recognised, and today's is not", () => {
+    expect(isLegacyContentDigest(legacyContentDigest("hello"))).toBe(true);
+    expect(isLegacyContentDigest(legacyContentDigest(""))).toBe(true);
+    expect(isLegacyContentDigest(contentDigest("hello"))).toBe(false);
+  });
+
+  test("a real SHA-256 value, a short value and a non-string are not", () => {
+    expect(isLegacyContentDigest(realSha256)).toBe(false);
+    expect(isLegacyContentDigest("sha256:abc123")).toBe(false);
+    expect(isLegacyContentDigest(undefined)).toBe(false);
+  });
+
+  test("warns once per project, and not at all without an old value", () => {
+    expect(warnOnLegacyDigests([realSha256], "release ledger", "/p/a")).toBe(false);
+    expect(warnOnLegacyDigests([legacyContentDigest("x")], "release ledger", "/p/a")).toBe(true);
+    expect(warnOnLegacyDigests([legacyContentDigest("y")], "build manifests", "/p/a")).toBe(false);
+    expect(warnOnLegacyDigests([legacyContentDigest("y")], "build manifests", "/p/b")).toBe(true);
+    expect(legacyWarnings()).toHaveLength(2);
+    expect(String(legacyWarnings()[0][0])).toContain("chant now computes real SHA-256");
+    expect(String(legacyWarnings()[0][0])).toContain(`accepts them through ${LEGACY_DIGEST_ACCEPTED_THROUGH}`);
+  });
+
+  test("flagLegacyDigest adds the flag once, keeps other flags, and leaves real values alone", () => {
+    const old = legacyContentDigest("x");
+    const record: { id: number; flags?: string[] } = { id: 1 };
+    expect(flagLegacyDigest(record, [realSha256])).toEqual({ id: 1 });
+    expect(flagLegacyDigest(record, [undefined, old])).toEqual({ id: 1, flags: [LEGACY_DIGEST_FLAG] });
+    expect(flagLegacyDigest({ flags: ["legacy-digest"] }, [old])).toEqual({ flags: ["legacy-digest"] });
+    expect(flagLegacyDigest({ flags: ["other"] }, [old])).toEqual({ flags: ["other", "legacy-digest"] });
+  });
+
+  test("a release ledger with old and new values: old entries read back flagged, warned once, never re-keyed", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const old = legacyContentDigest("rendered");
+      await appendReleaseRecord(release(old, "run-1"), { cwd: dir });
+      await appendReleaseRecord(release(contentDigest("rendered"), "run-2"), { cwd: dir });
+
+      const { records } = await readReleaseLedger("prod", { cwd: dir });
+      await readReleaseLedger("prod", { cwd: dir });
+      expect(legacyWarnings()).toHaveLength(1);
+      expect(String(legacyWarnings()[0][0])).toContain("release ledger holds");
+
+      expect(records.map((r) => [r.runId, r.digest, r.flags])).toEqual([
+        ["run-1", old, [LEGACY_DIGEST_FLAG]],
+        ["run-2", contentDigest("rendered"), undefined],
+      ]);
+
+      // Appending a record read back with its flag does not persist the flag,
+      // and the old digest is written exactly as it was.
+      const flagged = { ...records[0]!, runId: "run-3" } as ReleaseRecord;
+      const { record: written } = await appendReleaseRecord(flagged, { cwd: dir });
+      expect(written.flags).toBeUndefined();
+      expect(written.digest).toBe(old);
+      const raw = await readBlobFromPath("prod", "releases.jsonl", { cwd: dir });
+      expect(raw ?? "").not.toContain("legacy-digest");
+    });
+  });
+
+  test("a release ledger of real SHA-256 values stays quiet", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      await appendReleaseRecord(release(realSha256, "run-1"), { cwd: dir });
+      await readReleaseLedger("prod", { cwd: dir });
+      expect(legacyWarnings()).toHaveLength(0);
+    });
+  });
+
+  test("an old persisted build manifest reads back under its old key, flagged, and is found by its old artifact digest", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      const oldEntry = legacyContentDigest("{}");
+      const oldManifestDigest = legacyContentDigest(`template:web.json:${oldEntry}`);
+      const oldManifest = {
+        version: 1 as const,
+        component: "web",
+        createdAt: new Date(0).toISOString(),
+        contents: [{ kind: "template" as const, path: "web.json", digest: oldEntry }],
+        manifestDigest: oldManifestDigest,
+      };
+      await persistBuildManifest(oldManifest, { cwd: dir });
+
+      let fresh = createBuildArchiveManifest("web", { now: () => new Date(0) });
+      fresh = addArchiveEntry(fresh, { kind: "template", path: "web.json", digest: contentDigest("{}") });
+      await persistBuildManifest(fresh, { cwd: dir });
+
+      const all = await readAllBuildManifests({ cwd: dir });
+      await readAllBuildManifests({ cwd: dir });
+      expect(legacyWarnings()).toHaveLength(1);
+      expect(String(legacyWarnings()[0][0])).toContain("build manifests hold");
+      expect(all).toHaveLength(2);
+
+      const old = await readBuildManifest(oldManifestDigest, { cwd: dir });
+      expect(old?.manifestDigest).toBe(oldManifestDigest);
+      expect(old?.flags).toEqual([LEGACY_DIGEST_FLAG]);
+      expect((await findBuildManifestByArtifactDigest(oldEntry, { cwd: dir }))?.manifestDigest).toBe(oldManifestDigest);
+      expect((await readBuildManifest(fresh.manifestDigest, { cwd: dir }))?.flags).toBeUndefined();
+
+      // Persisting a flagged manifest again writes no flag.
+      await persistBuildManifest(old!, { cwd: dir });
+      const raw = await readBlobFromPath("_builds", `${oldManifestDigest.replace(/:/g, "_")}.json`, { cwd: dir });
+      expect(raw ?? "").not.toContain("legacy-digest");
+    });
+  });
+
+  test("a cross-environment comparison of an old and a new digest says it cannot tell", () => {
+    const rec = (env: string, digest: string): ReleaseRecord => ({ version: 1, ...release(digest, `${env}-1`), env });
+    const mixed = compareAcrossEnvironments(
+      "web",
+      { name: "staging", records: [rec("staging", contentDigest("x"))] },
+      { name: "prod", records: [rec("prod", legacyContentDigest("x"))] },
+    );
+    expect(mixed.same).toBe(false);
+    expect(mixed.mixedDigestForms).toBe(true);
+
+    const differentNew = compareAcrossEnvironments(
+      "web",
+      { name: "staging", records: [rec("staging", contentDigest("x"))] },
+      { name: "prod", records: [rec("prod", contentDigest("y"))] },
+    );
+    expect(differentNew.mixedDigestForms).toBeUndefined();
+  });
+});

package/src/lifecycle/legacy-digest.ts

@@ -0,0 +1,103 @@
+/**
+ * Digests recorded before real SHA-256 (chant #2514).
+ *
+ * Up to chant 0.80.0, `contentDigest` labelled its output `sha256:` but
+ * computed a 32-bit string hash and repeated its 8 hex digits eight times.
+ * It now computes real SHA-256 (../content-digest.ts), so every value it
+ * produces changed once. Values already recorded in a project's release
+ * ledger or persisted build manifests keep the old form: they are never
+ * re-keyed or rewritten, because a digest is an identity other records point
+ * at.
+ *
+ * Readers accept both forms. A record read back with an old value carries
+ * `flags: ["legacy-digest"]`, computed on read and never written, and chant
+ * warns once per project, per process, that the ledger holds such values.
+ * Both forms stay accepted through {@link LEGACY_DIGEST_ACCEPTED_THROUGH}.
+ * A later release may stop accepting old values, and it will warn a release
+ * ahead, as #2525 requires of any level-0 change.
+ *
+ * An old value is recognisable by its shape alone. A real SHA-256 hex digest
+ * whose 64 characters are one 8-character block repeated eight times has
+ * probability 2^-224, so the check has no false positives worth considering.
+ */
+
+import { resolve } from "node:path";
+
+const LEGACY_DIGEST = /^sha256:([0-9a-f]{8})\1{7}$/;
+
+/** The flag a record read back with an old-form digest carries. */
+export const LEGACY_DIGEST_FLAG = "legacy-digest";
+export type LegacyDigestFlag = typeof LEGACY_DIGEST_FLAG;
+
+/**
+ * The last release series in which readers are guaranteed to accept old-form
+ * digests: every 0.8x release. The first release allowed to refuse them is
+ * 0.90.0, and only after a release that warns about it.
+ */
+export const LEGACY_DIGEST_ACCEPTED_THROUGH = "0.89.x";
+
+/** Whether `value` is a `sha256:` string made by the old 32-bit `contentDigest`. */
+export function isLegacyContentDigest(value: unknown): boolean {
+  return typeof value === "string" && LEGACY_DIGEST.test(value);
+}
+
+/** Whether any of `values` is an old-form digest. */
+export function hasLegacyContentDigest(values: Iterable<unknown>): boolean {
+  for (const value of values) {
+    if (isLegacyContentDigest(value)) return true;
+  }
+  return false;
+}
+
+/**
+ * `record` with `flags: ["legacy-digest"]` added when any of `values` (the
+ * record's own digests) is in the old form, and otherwise unchanged. Other
+ * flags a record carries are kept.
+ */
+export function flagLegacyDigest<T extends { flags?: string[] }>(record: T, values: Iterable<unknown>): T {
+  if (!hasLegacyContentDigest(values)) return record;
+  const flags = record.flags ?? [];
+  if (flags.includes(LEGACY_DIGEST_FLAG)) return record;
+  return { ...record, flags: [...flags, LEGACY_DIGEST_FLAG] };
+}
+
+/**
+ * `record` without its read-side `flags`, for writers. Flags describe how a
+ * record reads now, so they are never persisted.
+ */
+export function withoutReadFlags<T extends { flags?: unknown }>(record: T): Omit<T, "flags"> {
+  if (!("flags" in record)) return record;
+  const { flags: _flags, ...rest } = record;
+  return rest;
+}
+
+/** Project roots already warned about in this process. */
+const warnedProjects = new Set<string>();
+
+/** Forget which projects were warned about. For tests. */
+export function resetLegacyDigestWarnings(): void {
+  warnedProjects.clear();
+}
+
+/**
+ * Warn once for the project at `cwd` (default: the working directory) when
+ * any of `values` is an old-form digest. `where` names the record that held
+ * it, for the message. Returns whether a warning was printed.
+ */
+export function warnOnLegacyDigests(
+  values: Iterable<unknown>,
+  where: "release ledger" | "build manifests",
+  cwd?: string,
+): boolean {
+  const project = resolve(cwd ?? process.cwd());
+  if (warnedProjects.has(project)) return false;
+  if (!hasLegacyContentDigest(values)) return false;
+  warnedProjects.add(project);
+  console.warn(
+    `[chant] warning: this project's ${where} ${where === "release ledger" ? "holds" : "hold"} sha256: values made by chant's old 32-bit content hash, ` +
+      "not real SHA-256. chant now computes real SHA-256, so a digest recorded from now on will not match " +
+      "an old one for the same content. Old entries are not rewritten: they read back flagged legacy-digest, " +
+      `and chant accepts them through ${LEGACY_DIGEST_ACCEPTED_THROUGH}. See https://github.com/INTENTIUS/chant/issues/2514`,
+  );
+  return true;
+}

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

@@ -0,0 +1,319 @@
+/**
+ * #2538 — member ledgers under `_members/<member>/` on `chant/lifecycle`.
+ *
+ * One fixture workspace holds a root member `.`, two members `api` and `web`
+ * that use the same environment name, an example group, and a nested
+ * workspace `platform` with a member `core`. Each store is written from a
+ * member's directory and the exact branch path is asserted, then read back
+ * from each member to show neither sees the other's records.
+ */
+
+import { afterAll, beforeEach, describe, expect, test } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { clearMemberLedgerCache, memberLedgerPrefix, MemberLedgerError, resolveMemberLedger } from "./member-ledger";
+import { ledgerDir, listLedgerEnvironments, listSnapshots, readEnvironmentSnapshots, writeLedgerFiles, writeSnapshot } from "./git";
+import { appendReleaseRecord, readReleaseLedger, type ReleaseRecordInput } from "./release-ledger";
+import { appendRunRecord, readRunLedger } from "./run-ledger";
+import type { OpRunRecordInput } from "../op/runtime";
+import { appendConvergeRecord, readConvergeLedger, type ConvergeTickRecordInput } from "./converge-ledger";
+import { appendGateResolution, appendPendingGate, gateLedgerPath, readGateLedger } from "./gate-ledger";
+import { persistBuildManifest, listBuildManifestDigests } from "./build-ledger-store";
+import { emptyBaseline, readObservationBaseline, writeObservationBaseline } from "./observation-baseline";
+import { acquireLease, leaseRef, readLease } from "./lease";
+import { createBuildArchiveManifest } from "../components/verbs/build-archive";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+beforeEach(() => clearMemberLedgerCache());
+
+function git(args: string[], cwd: string): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout;
+}
+
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-member-ledger-")));
+  scratch.push(root);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  git(["init", "-q", "-b", "main"], root);
+  git(["config", "user.email", "test@chant.dev"], root);
+  git(["config", "user.name", "Test"], root);
+  git(["add", "-A"], root);
+  git(["commit", "-q", "-m", "init"], root);
+  return root;
+}
+
+const CONFIG = JSON.stringify({ lexicons: ["k8s"] });
+
+function workspace(): string {
+  return repo({
+    "chant.workspace.json": JSON.stringify({
+      name: "acme",
+      schema: 1,
+      members: [
+        { name: "root", dir: ".", kind: "chant" },
+        { name: "api", dir: "services/api", kind: "chant" },
+        { name: "web", dir: "services/web", kind: "chant" },
+        { name: "platform", dir: "platform", kind: "workspace" },
+        { name: "examples", kind: "examples", glob: "examples/*" },
+      ],
+    }),
+    "chant.config.json": CONFIG,
+    "services/api/chant.config.json": CONFIG,
+    "services/api/src/main.ts": "",
+    "services/web/chant.config.json": CONFIG,
+    "examples/demo/chant.config.json": CONFIG,
+    "docs/README.md": "",
+    "platform/chant.workspace.json": JSON.stringify({
+      name: "platform",
+      schema: 1,
+      members: [{ name: "core", dir: "core", kind: "chant" }],
+    }),
+    "platform/core/chant.config.json": CONFIG,
+  });
+}
+
+/** Every file on chant/lifecycle, sorted. */
+function branchFiles(root: string): string[] {
+  return git(["ls-tree", "-r", "--name-only", "chant/lifecycle"], root).split("\n").filter(Boolean).sort();
+}
+
+function release(overrides: Partial<ReleaseRecordInput> = {}): ReleaseRecordInput {
+  return {
+    component: "svc",
+    env: "prod",
+    digest: "sha256:abc",
+    gitSha: "deadbeef",
+    runId: "run-1",
+    timestamp: "2026-01-01T00:00:00.000Z",
+    actor: "ci",
+    ...overrides,
+  };
+}
+
+function run(overrides: Partial<OpRunRecordInput> = {}): OpRunRecordInput {
+  return {
+    op: "deploy",
+    env: "prod",
+    started: "2026-01-01T00:00:00.000Z",
+    ended: "2026-01-01T00:00:01.000Z",
+    status: "ok",
+    labels: { Env: "prod" },
+    outcomes: {},
+    phases: [],
+    ...overrides,
+  };
+}
+
+function tick(overrides: Partial<ConvergeTickRecordInput> = {}): ConvergeTickRecordInput {
+  return {
+    op: "converge",
+    env: "prod",
+    timestamp: "2026-01-01T00:00:00.000Z",
+    firedRuleIds: [],
+    outcomes: [],
+    summary: { drifted: 0, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0 },
+    log: "converge(prod)",
+    ...overrides,
+  };
+}
+
+describe("resolveMemberLedger (#2538)", () => {
+  test("a project with no declaration keeps the flat layout", async () => {
+    const root = repo({ "chant.config.json": CONFIG });
+    expect(await resolveMemberLedger(root)).toEqual({ members: [], prefix: "" });
+  });
+
+  test("the root member, unowned directories and example matches keep the flat layout", async () => {
+    const root = workspace();
+    for (const dir of [".", "docs", "examples/demo"]) {
+      expect((await resolveMemberLedger(join(root, dir))).prefix, dir).toBe("");
+    }
+  });
+
+  test("a member, and any directory inside it, writes under _members/<member>/", async () => {
+    const root = workspace();
+    expect(await resolveMemberLedger(join(root, "services/api"))).toEqual({ members: ["api"], prefix: "_members/api/" });
+    expect((await resolveMemberLedger(join(root, "services/api/src"))).prefix).toBe("_members/api/");
+    expect((await resolveMemberLedger(join(root, "services/web"))).prefix).toBe("_members/web/");
+  });
+
+  test("a nested workspace's ledgers sit inside the outer member that holds it", async () => {
+    const root = workspace();
+    expect((await resolveMemberLedger(join(root, "platform"))).prefix).toBe("_members/platform/");
+    expect(await resolveMemberLedger(join(root, "platform/core"))).toEqual({
+      members: ["platform", "core"],
+      prefix: "_members/platform/_members/core/",
+    });
+  });
+
+  test("an unreadable declaration refuses to place the ledger rather than guess", async () => {
+    const root = repo({ "chant.workspace.json": "{ not json", "api/chant.config.json": CONFIG });
+    await expect(resolveMemberLedger(join(root, "api"))).rejects.toBeInstanceOf(MemberLedgerError);
+    await expect(ledgerDir("prod", { cwd: join(root, "api") })).rejects.toThrow(/cannot place this project's lifecycle ledger/);
+  });
+
+  test("memberLedgerPrefix joins one _members/<name>/ per level", () => {
+    expect(memberLedgerPrefix([])).toBe("");
+    expect(memberLedgerPrefix(["a", "b"])).toBe("_members/a/_members/b/");
+  });
+});
+
+describe("every lifecycle store writes under the member path (#2538)", () => {
+  test("releases: two members with one environment name keep separate ledgers", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    await appendReleaseRecord(release({ component: "api" }), { cwd: api });
+    await appendReleaseRecord(release({ component: "web" }), { cwd: web });
+    await appendReleaseRecord(release({ component: "root" }), { cwd: root });
+
+    expect(branchFiles(root)).toEqual(["_members/api/prod/releases.jsonl", "_members/web/prod/releases.jsonl", "prod/releases.jsonl"]);
+    expect((await readReleaseLedger("prod", { cwd: api })).records.map((r) => r.component)).toEqual(["api"]);
+    expect((await readReleaseLedger("prod", { cwd: web })).records.map((r) => r.component)).toEqual(["web"]);
+    expect((await readReleaseLedger("prod", { cwd: root })).records.map((r) => r.component)).toEqual(["root"]);
+    expect(await listLedgerEnvironments({ cwd: api })).toEqual(["prod"]);
+    // The root member's listing never reads `_members` as an environment.
+    expect(await listLedgerEnvironments({ cwd: root })).toEqual(["prod"]);
+  });
+
+  test("snapshots and observation baselines", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    await writeSnapshot("prod", "k8s", '{"from":"api"}', { cwd: api });
+    await writeSnapshot("prod", "k8s", '{"from":"web"}', { cwd: web });
+    await writeObservationBaseline(emptyBaseline("prod"), { cwd: api });
+
+    const files = branchFiles(root);
+    expect(files).toContain("_members/api/prod/k8s.json");
+    expect(files).toContain("_members/web/prod/k8s.json");
+    expect(files.filter((f) => f.startsWith("_members/api/prod/") && f !== "_members/api/prod/k8s.json")).toHaveLength(1);
+    expect(files.every((f) => f.startsWith("_members/"))).toBe(true);
+    expect([...(await readEnvironmentSnapshots("prod", { cwd: web })).values()]).toEqual(['{"from":"web"}']);
+    expect(await readObservationBaseline("prod", { cwd: api })).toMatchObject({ environment: "prod" });
+    expect(await readObservationBaseline("prod", { cwd: web })).toBeNull();
+    // A member's history lists only the commits that touched its ledger.
+    expect(await listSnapshots({ cwd: web })).toHaveLength(1);
+    expect(await listSnapshots({ cwd: root })).toHaveLength(3);
+  });
+
+  test("runs and converge records", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    await appendRunRecord(run(), { cwd: api });
+    await appendConvergeRecord(tick(), { cwd: web });
+
+    expect(branchFiles(root)).toEqual(["_members/api/prod/runs__deploy.jsonl", "_members/web/prod/converge.jsonl"]);
+    expect((await readRunLedger("prod", "deploy", { cwd: api })).records).toHaveLength(1);
+    expect((await readRunLedger("prod", "deploy", { cwd: web })).records).toHaveLength(0);
+    expect((await readConvergeLedger("prod", { cwd: web })).records).toHaveLength(1);
+    expect((await readConvergeLedger("prod", { cwd: api })).records).toHaveLength(0);
+  });
+
+  test("gates: _gates moves under the member, and an Op name can repeat across members", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    await appendPendingGate({ op: "deploy", gate: "approve", timestamp: "2026-01-01T00:00:00.000Z", expiresAt: "2026-01-02T00:00:00.000Z" }, { cwd: api });
+    await appendGateResolution({ op: "deploy", gate: "approve", resolvedBy: "alex", timestamp: "2026-01-01T00:00:01.000Z" }, { cwd: web });
+
+    expect(branchFiles(root)).toEqual(["_members/api/_gates/deploy.jsonl", "_members/web/_gates/deploy.jsonl"]);
+    const apiGates = await readGateLedger("deploy", { cwd: api });
+    expect(apiGates.pending).toHaveLength(1);
+    expect(apiGates.resolutions).toHaveLength(0);
+    const webGates = await readGateLedger("deploy", { cwd: web });
+    expect(webGates.pending).toHaveLength(0);
+    expect(webGates.resolutions).toHaveLength(1);
+    expect(gateLedgerPath("deploy", "_members/api/")).toBe("_members/api/_gates/deploy.jsonl");
+    expect(gateLedgerPath("deploy")).toBe("_gates/deploy.jsonl");
+  });
+
+  test("build records: _builds moves under the member", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const manifest = createBuildArchiveManifest("api", { now: () => new Date("2026-01-01T00:00:00.000Z") });
+    await persistBuildManifest(manifest, { cwd: api });
+
+    const files = branchFiles(root);
+    expect(files).toHaveLength(1);
+    expect(files[0]).toMatch(/^_members\/api\/_builds\/sha256_[0-9a-f]+\.json$/);
+    expect(await listBuildManifestDigests({ cwd: api })).toEqual([manifest.manifestDigest]);
+    expect(await listBuildManifestDigests({ cwd: join(root, "services/web") })).toEqual([]);
+  });
+
+  test("leases: refs/chant/lease/_members/<member>/<op>, so two members' Ops of one name hold separate leases", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    expect((await acquireLease("converge", "holder-api", { cwd: api })).acquired).toBe(true);
+    expect((await acquireLease("converge", "holder-web", { cwd: web })).acquired).toBe(true);
+    expect((await acquireLease("converge", "holder-root", { cwd: root })).acquired).toBe(true);
+
+    const refs = git(["for-each-ref", "--format=%(refname)", "refs/chant/lease/"], root).split("\n").filter(Boolean).sort();
+    expect(refs).toEqual([
+      "refs/chant/lease/_members/api/converge",
+      "refs/chant/lease/_members/web/converge",
+      "refs/chant/lease/converge",
+    ]);
+    expect((await readLease("converge", { cwd: api })).record?.holder).toBe("holder-api");
+    expect((await readLease("converge", { cwd: web })).record?.holder).toBe("holder-web");
+    expect(leaseRef("converge", "_members/api/")).toBe("refs/chant/lease/_members/api/converge");
+  });
+
+  test("a nested workspace member writes under both levels", async () => {
+    const root = workspace();
+    await appendReleaseRecord(release({ component: "core" }), { cwd: join(root, "platform/core") });
+    expect(branchFiles(root)).toEqual(["_members/platform/_members/core/prod/releases.jsonl"]);
+  });
+});
+
+describe("one commit can write several members (#2538)", () => {
+  test("writeLedgerFiles lands two members' records in a single commit, each read back by its own member", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    const web = join(root, "services/web");
+    // An earlier write, so the multi-member commit extends a branch that has other entries.
+    await appendReleaseRecord(release({ component: "root" }), { cwd: root });
+    const before = git(["rev-parse", "chant/lifecycle"], root).trim();
+
+    const line = (component: string) => JSON.stringify({ version: 1, ...release({ component }) });
+    const commit = await writeLedgerFiles(
+      [
+        { path: `${await ledgerDir("prod", { cwd: api })}/releases.jsonl`, content: line("api") },
+        { path: `${await ledgerDir("prod", { cwd: web })}/releases.jsonl`, content: line("web") },
+      ],
+      "Release records: api, web",
+      { cwd: root },
+    );
+
+    expect(git(["rev-parse", "chant/lifecycle"], root).trim()).toBe(commit);
+    expect(git(["rev-parse", `${commit}^`], root).trim()).toBe(before);
+    expect(git(["diff-tree", "-r", "--name-only", "--no-commit-id", commit], root).split("\n").filter(Boolean).sort()).toEqual([
+      "_members/api/prod/releases.jsonl",
+      "_members/web/prod/releases.jsonl",
+    ]);
+    expect((await readReleaseLedger("prod", { cwd: api })).records.map((r) => r.component)).toEqual(["api"]);
+    expect((await readReleaseLedger("prod", { cwd: web })).records.map((r) => r.component)).toEqual(["web"]);
+    expect((await readReleaseLedger("prod", { cwd: root })).records.map((r) => r.component)).toEqual(["root"]);
+  });
+
+  test("an expected prior sha that moved is a conflict, not a blind overwrite", async () => {
+    const root = workspace();
+    const api = join(root, "services/api");
+    await appendReleaseRecord(release({ component: "api" }), { cwd: api });
+    await expect(
+      writeLedgerFiles([{ path: "_members/api/prod/releases.jsonl", content: "{}", expectPriorSha: null }], "stale", { cwd: root }),
+    ).rejects.toThrow(/target path changed concurrently/);
+  });
+});