@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/root-refusal.ts

@@ -0,0 +1,97 @@
+/**
+ * `chant build` and `chant lint` at the root of a declared workspace (#2537,
+ * #2524 D0 and D12, ws-023).
+ *
+ * Once `chant.workspace.json` declares members, their directories leave the
+ * root project. A top-level `chant build` there would quietly build less than
+ * it did before the file existed, so both commands refuse with `WSP000` and
+ * point to `chant workspace build` and `chant workspace lint`. `--root-only`,
+ * or `rootOnly: true` in the root's `chant.config`, lets them run on the root
+ * project alone, with the member directories and example-group matches left
+ * out of discovery.
+ *
+ * `main.ts` decides with `findWorkspaceRoot` and `findProjectRoot`, which only
+ * test whether files exist, and imports this module only when the command's
+ * project is a declared root. A project with no declaration never loads it.
+ */
+
+import { relative } from "node:path";
+import { formatError } from "../cli/format";
+import { ownerOf, readDeclaration, resolveGroups, rootExclusions, WorkspaceReadError } from "./declaration";
+import { workingTree } from "./tree";
+
+/** The code a refusal carries. `WSP` ids name workspace findings (#2524 D16); `000` is the refusal itself. */
+export const ROOT_REFUSAL_CODE = "WSP000";
+
+export interface RootGuardInput {
+  verb: "build" | "lint";
+  /** The command's target, absolute. */
+  target: string;
+  /** The directory holding the declaration, absolute. */
+  workspaceDir: string;
+  /** `--root-only` on the command line, or `rootOnly: true` in the root's chant.config. */
+  rootOnly: boolean;
+}
+
+export type RootGuardResult =
+  /** The target belongs to a member or an example group, so it is not the root project; nothing changes. */
+  | { action: "not-root" }
+  /** The command runs on the root project with these directories (relative to the root) left out. */
+  | { action: "root-only"; excluded: string[] }
+  /** The command stops; `message` says why and what to run instead. */
+  | { action: "refuse"; message: string };
+
+/** Decide what a root `build` or `lint` does. Pure apart from reading the declaration. */
+export function decideRootCommand(input: RootGuardInput): RootGuardResult {
+  const tree = workingTree(input.workspaceDir);
+  let declaration;
+  let groups;
+  try {
+    declaration = readDeclaration(tree);
+    groups = resolveGroups(declaration, tree);
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    return {
+      action: "refuse",
+      message:
+        `${ROOT_REFUSAL_CODE}: ${input.workspaceDir} holds a workspace declaration that can't be read, so chant ${input.verb} ` +
+        `can't tell which directories belong to the root project. ${err.code}: ${err.describe()}`,
+    };
+  }
+  const rel = relative(input.workspaceDir, input.target).split("\\").join("/") || ".";
+  const owner = ownerOf(declaration, groups, rel === "." ? "." : rel);
+  if (owner && ("group" in owner || owner.member.dir !== ".")) return { action: "not-root" };
+
+  const excluded = rootExclusions(declaration, groups).map((e) => e.dir);
+  if (input.rootOnly) return { action: "root-only", excluded };
+
+  const members = declaration.members.filter((m) => m.dir !== ".").length;
+  const matches = groups.reduce((n, g) => n + g.matches.length, 0);
+  const moved = [
+    `${members} member${members === 1 ? "" : "s"}`,
+    ...(matches > 0 ? [`${matches} example project${matches === 1 ? "" : "s"}`] : []),
+  ].join(" and ");
+  return {
+    action: "refuse",
+    message:
+      `${ROOT_REFUSAL_CODE}: this is the root of workspace ${declaration.name} (${declaration.file}), which moves ` +
+      `${moved} out of the root project. Run chant workspace ${input.verb} to ${input.verb} each member with its own ` +
+      `toolchain, or pass --root-only (or set rootOnly: true in chant.config) to ${input.verb} the root project alone.`,
+  };
+}
+
+/**
+ * Apply {@link decideRootCommand}: print the refusal and return 1, or return
+ * undefined so the command goes on. A root-only run needs nothing set up:
+ * every discovery walk under a declaration already leaves the member
+ * directories and group matches out (#2527, `workspaceMemberDirs` in
+ * `../discovery/walk.ts`), and `excluded` names the same directories.
+ */
+export function guardRootCommand(input: RootGuardInput): number | undefined {
+  const result = decideRootCommand(input);
+  if (result.action === "refuse") {
+    console.error(formatError({ message: result.message }));
+    return 1;
+  }
+  return undefined;
+}

package/src/workspace/status-contract.test.ts

@@ -0,0 +1,308 @@
+/**
+ * The read contract for `chant workspace status --json` (#2544, #2524 D15,
+ * D19): the output schema is a valid draft 2020-12 document, its closed code
+ * lists match the code, and real output validates against it, for workspaces
+ * built here with a `chant/lifecycle` branch holding member ledgers in both
+ * layouts, and for the chant repo's own declaration (#2557).
+ */
+
+import { execFileSync } 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 Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test, vi } from "vitest";
+import type { CommandContext } from "../cli/registry";
+import { listWorkspace } from "./ls";
+import {
+  formatStatus,
+  runWorkspaceStatus,
+  STATUS_CONTRACT_VERSION,
+  STATUS_ERROR_CODES,
+  STATUS_OUTPUT_SCHEMA_ID,
+  STATUS_REASON_CODES,
+  workspaceStatus,
+  type StatusDocument,
+} from "./status";
+import schema from "./status.schema.json";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(schema);
+
+function expectValid(doc: StatusDocument): void {
+  const ok = validate(doc);
+  expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+}
+
+function result(doc: StatusDocument): Extract<StatusDocument, { members: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function git(cwd: string, args: string[], env?: NodeJS.ProcessEnv, input?: string): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], {
+    cwd,
+    encoding: "utf-8",
+    input,
+    env: { ...process.env, ...env },
+    stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+/** A git repository holding `files`, committed. */
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-status-")));
+  scratch.push(root);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  git(root, ["init", "-q", "-b", "main"]);
+  git(root, ["add", "-A"]);
+  git(root, ["commit", "-q", "--allow-empty", "-m", "init"]);
+  return root;
+}
+
+/**
+ * Write `files` as the whole tree of a `chant/lifecycle` commit, the way the
+ * lifecycle code stores ledgers, without touching the working tree or index.
+ */
+function lifecycle(root: string, files: Record<string, string>): string {
+  const index = join(root, ".git", "status-test-index");
+  const env = { GIT_INDEX_FILE: index };
+  rmSync(index, { force: true });
+  for (const [path, text] of Object.entries(files)) {
+    const blob = git(root, ["hash-object", "-w", "--stdin"], env, text);
+    git(root, ["update-index", "--add", "--cacheinfo", `100644,${blob},${path}`], env);
+  }
+  const tree = git(root, ["write-tree"], env);
+  const commit = git(root, ["commit-tree", tree, "-m", "ledger"], env);
+  git(root, ["update-ref", "refs/heads/chant/lifecycle", commit]);
+  rmSync(index, { force: true });
+  return commit;
+}
+
+let n = 0;
+/** One ledger line. */
+function release(component: string, env: string, digest: string, gitSha: string, extra: Record<string, string> = {}): string {
+  n++;
+  return JSON.stringify({
+    version: 1,
+    component,
+    env,
+    digest,
+    gitSha,
+    runId: `run-${n}`,
+    timestamp: `2026-09-${String(10 + n).padStart(2, "0")}T00:00:00.000Z`,
+    actor: "ci",
+    ...extra,
+  });
+}
+const jsonl = (...lines: string[]) => lines.join("\n") + "\n";
+
+const D = (c: string) => `sha256:${c.repeat(64)}`;
+
+const declaration = (members: unknown[]) => JSON.stringify({ name: "acme", schema: 1, members }, null, 2);
+
+/** web has moved to _members/ (#2538); api and the root member still read the flat ledger. */
+function twoLayouts(): string {
+  const root = repo({
+    "chant.workspace.json": declaration([
+      { name: "site", dir: ".", kind: "other", because: "the root project" },
+      { name: "web", dir: "apps/web", kind: "chant" },
+      { name: "api", dir: "apps/api", kind: "chant" },
+      { name: "examples", kind: "examples", glob: "examples/*" },
+    ]),
+    "apps/web/chant.config.ts": "",
+    "apps/api/chant.config.ts": "",
+  });
+  lifecycle(root, {
+    "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("0"), "0".repeat(40)), release("web", "staging", D("a"), "a".repeat(40))),
+    "_members/web/prod/releases.jsonl": jsonl(release("web", "prod", D("a"), "a".repeat(40))),
+    "staging/releases.jsonl": jsonl(
+      release("api", "staging", D("b"), "b".repeat(40)),
+      release("worker", "staging", D("d"), "d".repeat(40)),
+    ),
+    "prod/releases.jsonl": jsonl(release("api", "prod", D("c"), "c".repeat(40))),
+  });
+  return root;
+}
+
+describe("status output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(ajv.validateSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(STATUS_OUTPUT_SCHEMA_ID);
+    expect(STATUS_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the reason and error codes the code can return", () => {
+    expect(schema.$defs.environment.properties.reason.oneOf[1].properties!.code.enum).toEqual([...STATUS_REASON_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...STATUS_ERROR_CODES]);
+  });
+});
+
+describe("chant workspace status on built workspaces", () => {
+  test("lists each member's latest release per environment, from _members/ and from the flat layout", async () => {
+    const root = twoLayouts();
+    const doc = result(await workspaceStatus({ cwd: join(root, "apps", "web"), env: "staging" }));
+    expectValid(doc);
+    expect(doc.lifecycle.commit).toBe(git(root, ["rev-parse", "chant/lifecycle"]));
+    expect(doc.members.map((m) => m.name)).toEqual(["site", "web", "api"]);
+    const [site, web, api] = doc.members;
+    expect(web.environments).toHaveLength(1);
+    expect(web.environments[0].ledger).toEqual({ layout: "members", path: "_members/web/staging/releases.jsonl", shared: false });
+    // The later of the two records wins.
+    expect(web.environments[0].releases.map((r) => [r.component, r.digest, r.gitSha])).toEqual([["web", D("a"), "a".repeat(40)]]);
+    // api has no _members/api/ yet, so it falls back to the flat ledger, which the root member reads too.
+    expect(api.environments[0].ledger).toEqual({ layout: "flat", path: "staging/releases.jsonl", shared: true });
+    expect(site.environments[0].ledger).toEqual({ layout: "flat", path: "staging/releases.jsonl", shared: true });
+    expect(api.environments[0].releases.map((r) => r.component)).toEqual(["api", "worker"]);
+    expect(web.compare).toBeNull();
+    expect(doc.summary).toEqual({ members: 3, released: 3, unreadable: 0, differing: null });
+  });
+
+  test("--compare-to shows both environments and marks the members whose digests differ", async () => {
+    const root = twoLayouts();
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", compareTo: "prod" }));
+    expectValid(doc);
+    const web = doc.members.find((m) => m.name === "web")!;
+    const api = doc.members.find((m) => m.name === "api")!;
+    expect(web.environments.map((e) => [e.env, e.ledger.path])).toEqual([
+      ["staging", "_members/web/staging/releases.jsonl"],
+      ["prod", "_members/web/prod/releases.jsonl"],
+    ]);
+    expect(web.compare).toEqual({ differs: false, components: [{ component: "web", state: "same", digest: D("a"), compareDigest: D("a") }] });
+    expect(api.compare).toEqual({
+      differs: true,
+      components: [
+        { component: "api", state: "differs", digest: D("b"), compareDigest: D("c") },
+        { component: "worker", state: "only-env", digest: D("d"), compareDigest: null },
+      ],
+    });
+    expect(doc.summary).toEqual({ members: 3, released: 3, unreadable: 0, differing: 2 });
+
+    const text = formatStatus(doc);
+    expect(text).toContain("acme  staging compared to prod  (chant/lifecycle at ");
+    expect(text).toMatch(/web\s+web\s+sha256:aaaaaaaaaaaa aaaaaaaa\s+sha256:aaaaaaaaaaaa aaaaaaaa\n/);
+    expect(text).toMatch(/api\s+api\s+sha256:bbbbbbbbbbbb bbbbbbbb\s+sha256:cccccccccccc cccccccc\s+differs/);
+    expect(text).toMatch(/api\s+worker\s+sha256:dddddddddddd dddddddd\s+-\s+only-env/);
+    expect(text).toContain("3 members, 3 with a release in staging, 2 differ from prod, 0 unreadable");
+  });
+
+  test("compares on the input digest when a release has one", async () => {
+    const root = repo({ "chant.workspace.json": declaration([{ name: "chart", dir: "chart", kind: "other", because: "helm" }]) });
+    lifecycle(root, {
+      "staging/releases.jsonl": jsonl(release("chart", "staging", D("1"), "1".repeat(40), { inputDigest: D("9") })),
+      "prod/releases.jsonl": jsonl(release("chart", "prod", D("2"), "1".repeat(40), { inputDigest: D("9") })),
+    });
+    const doc = result(await workspaceStatus({ cwd: root, env: "staging", compareTo: "prod" }));
+    expectValid(doc);
+    expect(doc.members[0].compare?.components[0]).toMatchObject({ state: "same", digest: D("1"), compareDigest: D("2") });
+    expect(doc.members[0].environments[0].ledger.shared).toBe(false);
+  });
+
+  test("a member whose ledger can't be read is listed with a reason code, and the read still succeeds", async () => {
+    const root = twoLayouts();
+    lifecycle(root, {
+      "_members/web/staging/releases.jsonl": jsonl(release("web", "staging", D("a"), "a".repeat(40)), "{not json", JSON.stringify({ component: "web" })),
+      "staging/releases.jsonl": jsonl(release("api", "staging", D("b"), "b".repeat(40))),
+    });
+    const doc = result(
+      await workspaceStatus({
+        cwd: root,
+        env: "staging",
+        compareTo: "prod",
+        readLedger: async (path, cwd) => {
+          if (path === "prod/releases.jsonl") throw new Error("fatal: bad object\nmore");
+          const { readReleaseLedger } = await import("../lifecycle/release-ledger");
+          return readReleaseLedger(path.slice(0, -"/releases.jsonl".length), { cwd });
+        },
+      }),
+    );
+    expectValid(doc);
+    const web = doc.members.find((m) => m.name === "web")!;
+    const api = doc.members.find((m) => m.name === "api")!;
+    expect(web.readable).toBe(false);
+    expect(web.environments[0].reason).toEqual({
+      code: "ledger-malformed",
+      message: "_members/web/staging/releases.jsonl: 2 lines are not a release record and were skipped",
+    });
+    expect(web.environments[0].releases.map((r) => r.digest)).toEqual([D("a")]);
+    expect(api.environments[1].reason).toEqual({ code: "ledger-unreadable", message: "prod/releases.jsonl: fatal: bad object" });
+    expect(api.environments[1].releases).toEqual([]);
+    expect(doc.summary.unreadable).toBe(3);
+    expect(formatStatus(doc)).toContain("  ledger-unreadable: prod/releases.jsonl: fatal: bad object");
+  });
+
+  test("a checkout with no chant/lifecycle branch lists every member with no release", async () => {
+    const root = repo({ "chant.workspace.json": declaration([{ name: "web", dir: "web", kind: "chant" }]) });
+    const doc = result(await workspaceStatus({ cwd: root, env: "prod" }));
+    expectValid(doc);
+    expect(doc.lifecycle.commit).toBeNull();
+    expect(doc.members[0].environments[0]).toMatchObject({ releases: [], reason: null, ledger: { layout: "flat", shared: false } });
+    expect(formatStatus(doc)).toContain("web     -          no release");
+  });
+
+  test("every failure validates with its code", async () => {
+    const empty = repo({});
+    const outside = realpathSync(mkdtempSync(join(tmpdir(), "chant-status-nogit-")));
+    scratch.push(outside);
+    writeFileSync(join(outside, "chant.workspace.json"), declaration([]));
+    const broken = repo({ "chant.workspace.json": '{ "name": "acme", "schema": 1 "members": [] }' });
+    const ok = repo({ "chant.workspace.json": declaration([]) });
+    const docs = [
+      await workspaceStatus({ cwd: empty, env: "prod" }),
+      await workspaceStatus({ cwd: outside, env: "prod" }),
+      await workspaceStatus({ cwd: broken, env: "prod" }),
+      await workspaceStatus({ cwd: ok, env: "_members" }),
+      await workspaceStatus({ cwd: ok, env: "prod", compareTo: "../x" }),
+    ];
+    for (const doc of docs) expectValid(doc);
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual([
+      "declaration-missing",
+      "not-a-git-repository",
+      "declaration-unparseable",
+      "environment-invalid",
+      "environment-invalid",
+    ]);
+  });
+
+  test("the command needs an environment, refuses --live, and exits 0 with unreadable members", async () => {
+    const root = twoLayouts();
+    const err = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const run = (args: Record<string, unknown>) => runWorkspaceStatus({ args: { extraPositional2: root, ...args } } as unknown as CommandContext);
+      expect(await run({})).toBe(1);
+      expect(String(err.mock.calls.at(-1)?.[0])).toContain("needs an environment");
+      expect(await run({ extraPositional: "prod", compareTo: "--live" })).toBe(1);
+      expect(String(err.mock.calls.at(-1)?.[0])).toContain("doesn't read live state yet");
+      expect(await run({ extraPositional: "prod", compareTo: "staging", json: true })).toBe(0);
+      const printed = JSON.parse(String(log.mock.calls.at(-1)?.[0])) as StatusDocument;
+      expectValid(printed);
+      expect(await run({ extraPositional: "../prod", json: true })).toBe(1);
+    } finally {
+      err.mockRestore();
+      log.mockRestore();
+    }
+  });
+});
+
+describe("chant workspace status on the chant repo (#2557)", () => {
+  test("validates and lists every declared member", async () => {
+    const doc = result(await workspaceStatus({ cwd: join(REPO, "packages", "core"), env: "prod", compareTo: "staging" }));
+    expectValid(doc);
+    expect(doc.workspace).toMatchObject({ name: "chant", root: ".", file: "chant.workspace.json" });
+    const ls = listWorkspace({ cwd: REPO });
+    if ("error" in ls) throw new Error(ls.error.message);
+    expect(doc.members.map((m) => m.name)).toEqual(ls.members.map((m) => m.name));
+  });
+});

package/src/workspace/status.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json",
+  "title": "chant workspace status output",
+  "description": "What `chant workspace status <env> --json` prints, version 1 of the read contract for releases across members (#2524 D15, D19, #2544). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "$defs": {
+    "result": {
+      "description": "The declaration was read. Exit code 0, even when some ledgers can't be read or members differ.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "env", "compareTo", "lifecycle", "workspace", "members", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string", "description": "The version of the chant that read the ledgers." },
+        "env": { "$ref": "#/$defs/env" },
+        "compareTo": {
+          "description": "The environment given to --compare-to, or null.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/env" }]
+        },
+        "error": false,
+        "lifecycle": {
+          "type": "object",
+          "required": ["ref", "commit"],
+          "properties": {
+            "ref": { "const": "chant/lifecycle" },
+            "commit": {
+              "description": "The local branch tip the ledgers were read at, or null when the checkout has no such branch. The command never fetches it.",
+              "type": ["string", "null"],
+              "pattern": "^[0-9a-f]{40,64}$"
+            }
+          }
+        },
+        "workspace": {
+          "type": "object",
+          "required": ["name", "root", "file"],
+          "properties": {
+            "name": { "type": "string" },
+            "root": { "type": "string", "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself." },
+            "file": { "enum": ["chant.workspace.json", "chant.workspace.jsonc"] }
+          }
+        },
+        "members": {
+          "description": "Every member, in declaration order. Example groups have no ledger and are not listed.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/member" }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["members", "released", "unreadable", "differing"],
+          "properties": {
+            "members": { "type": "integer", "minimum": 0 },
+            "released": { "type": "integer", "minimum": 0, "description": "Members with at least one release in env." },
+            "unreadable": { "type": "integer", "minimum": 0, "description": "Members with a reason in any environment." },
+            "differing": {
+              "type": ["integer", "null"],
+              "minimum": 0,
+              "description": "Members whose compare differs, or null without --compare-to."
+            }
+          }
+        }
+      }
+    },
+    "env": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$"
+    },
+    "member": {
+      "type": "object",
+      "required": ["name", "dir", "kind", "environments", "compare", "readable"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string", "description": "Relative to the workspace root, with / separators; \".\" is the root member." },
+        "kind": { "type": "string" },
+        "environments": {
+          "description": "env first, then compareTo when it is given and differs from env.",
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 2,
+          "items": { "$ref": "#/$defs/environment" }
+        },
+        "compare": {
+          "description": "Null without --compare-to.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/compare" }]
+        },
+        "readable": { "type": "boolean", "description": "True exactly when no environment has a reason." }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "required": ["env", "ledger", "releases", "reason"],
+      "properties": {
+        "env": { "$ref": "#/$defs/env" },
+        "ledger": {
+          "type": "object",
+          "required": ["layout", "path", "shared"],
+          "properties": {
+            "layout": {
+              "enum": ["members", "flat"],
+              "description": "members: _members/<member>/<env>/releases.jsonl (#2538). flat: <env>/releases.jsonl, for the root member and for a member with no _members/<member>/ directory yet."
+            },
+            "path": { "type": "string", "description": "The ledger's path on chant/lifecycle." },
+            "shared": { "type": "boolean", "description": "True when more than one member in this output reads the same flat ledger, so they list the same records." }
+          }
+        },
+        "releases": {
+          "description": "The latest release of each component in the ledger, sorted by component. Empty when the ledger has none.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/release" }
+        },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["ledger-unreadable", "ledger-malformed"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": ["component", "digest", "gitSha", "inputDigest", "runId", "timestamp", "actor", "flags"],
+      "properties": {
+        "component": { "type": "string" },
+        "digest": { "type": "string", "description": "The artifact digest the release deployed." },
+        "gitSha": { "type": "string", "description": "The commit the artifact was built from." },
+        "inputDigest": { "type": ["string", "null"], "description": "The input-side digest when digest is a rendered one. Compare joins on it when present." },
+        "runId": { "type": "string" },
+        "timestamp": { "type": "string" },
+        "actor": { "type": "string" },
+        "flags": { "type": "array", "items": { "enum": ["legacy-digest"] } }
+      }
+    },
+    "compare": {
+      "type": "object",
+      "required": ["differs", "components"],
+      "properties": {
+        "differs": { "type": "boolean", "description": "True when any component is not same." },
+        "components": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["component", "state", "digest", "compareDigest"],
+            "properties": {
+              "component": { "type": "string" },
+              "state": {
+                "enum": ["same", "differs", "only-env", "only-compare"],
+                "description": "same: both environments have the same digest (the input digest when there is one). only-env and only-compare: the component has a release in one of them."
+              },
+              "digest": { "type": ["string", "null"] },
+              "compareDigest": { "type": ["string", "null"] }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration could not be read, or an environment name can't be one. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/status/v1/status.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string" },
+        "error": {
+          "type": "object",
+          "required": ["code", "message", "location"],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "environment-invalid"
+              ]
+            },
+            "message": { "type": "string" },
+            "location": {
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["file", "line", "column"],
+                  "properties": {
+                    "file": { "type": "string" },
+                    "line": { "type": "integer", "minimum": 1 },
+                    "column": { "type": "integer", "minimum": 1 }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "members": false,
+        "workspace": false
+      }
+    }
+  }
+}