@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/workspace-kinds.schema.json

@@ -46,7 +46,7 @@
         "name": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]{0,39}$",
-          "description": "The kind's name, as a member's kind field names it. chant, workspace, other and examples are built in and can't be supplied."
+          "description": "The kind's name, as a member's kind field names it. chant, workspace, repo, design, other and examples are built in and can't be supplied."
         },
         "description": {
           "type": "string",
@@ -82,7 +82,10 @@
         "reader": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]{0,39}$",
-          "description": "A link reader chant ships, by name, that derives a member's links from the member's own files (#3932): dbt-project reads a dbt project's sources. The reader is chant's code and runs offline, parsing files as data; the package supplies only the name. A name this chant doesn't have keeps the kind without a reader, and the load reports it. A chant older than this field fails a kinds file that uses it."
+          "description": "A link reader chant ships, by name, that derives a member's links from the member's own files (#3932): dbt-project reads a dbt project's sources; goose-dir, golang-migrate-dir, clickhouse-migrations-dir and flyway-dir list a migrations directory in order (#4400). The reader is chant's code and runs offline, parsing files as data; the package supplies only the name. A name this chant doesn't have keeps the kind without a reader, and the load reports it. A chant older than this field fails a kinds file that uses it."
+        },
+        "memberFile": {
+          "$ref": "#/$defs/memberFile"
         }
       },
       "patternProperties": {
@@ -159,33 +162,104 @@
             }
           },
           "additionalProperties": false
+        },
+        "anyLine": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, has a line that starts with one of starts, after leading space and ignoring case (#4400). A goose directory is found by -- +goose Up. Added by the chant that adds the goose-dir reader.",
+          "required": [
+            "in",
+            "starts"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "starts": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "anyDocument": {
+          "type": "object",
+          "description": "The directory passes when a file directly in it, whose name matches one of in, parses as YAML or JSON and one of its documents satisfies an entry of match (#3179). An entry maps JSON Pointers to the values allowed there, all of which must hold; a * in a value matches any run of characters, so [\"*\"] means the pointer has a value. A file that does not parse is no evidence either way.",
+          "required": [
+            "in",
+            "match"
+          ],
+          "properties": {
+            "in": {
+              "type": "array",
+              "minItems": 1,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/fileName"
+              }
+            },
+            "match": {
+              "type": "array",
+              "minItems": 1,
+              "items": {
+                "type": "object",
+                "minProperties": 1,
+                "propertyNames": {
+                  "pattern": "^(/[^/]+)+$"
+                },
+                "additionalProperties": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1
+                  }
+                }
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
     },
     "fileName": {
       "type": "string",
-      "description": "A file name, with no directory part. A * matches any run of characters.",
+      "description": "A file name, with no directory part. A * matches any run of characters, and [0-9] one digit.",
       "pattern": "^(?!\\.\\.?$)[^/\\\\]+$"
     },
     "graph": {
       "type": "object",
-      "description": "How chant workspace graph reads a member of this kind (#2874). chant writes a reader project of its own outside the workspace, with a chant.config.json that declares lexicon and puts config under that lexicon's key, and runs the member's chant graph there. In every string key and value of config, {member} becomes the member's name, {dir} its absolute directory and {workspace} the absolute workspace root. Without this field a member of the kind is listed with kind-not-run.",
-      "required": [
-        "lexicon",
-        "config"
-      ],
+      "description": "How chant workspace graph reads a member of this kind (#2874, #4413). chant writes a reader project of its own outside the workspace and runs the member's chant graph there. The project either declares a lexicon and puts config under that lexicon's key (lexicon), or names a graph reader module the supplying package ships (reader). In every string key and value of config, {member} becomes the member's name, {dir} its absolute directory and {workspace} the absolute workspace root. Without this field a member of the kind is listed with kind-not-run.",
       "properties": {
         "lexicon": {
           "type": "string",
           "pattern": "^[a-z][a-z0-9-]{0,39}$",
-          "description": "The lexicon that reads the member, by name. The package that supplies the kind must be @intentius/chant-lexicon-<lexicon>, so the lexicon chant loads is the one the declaration pins."
+          "description": "The lexicon that reads the member, by name. The package that supplies the kind must be @intentius/chant-lexicon-<lexicon>, so the lexicon chant loads is the one the declaration pins. Not with reader."
+        },
+        "reader": {
+          "type": "string",
+          "pattern": "^(?!/)(?!.*\\.\\.)(?!.*\\\\)[^\\u0000-\\u001f]+$",
+          "description": "A graph reader module, as a path inside the supplying package (#4413): an ES module whose default export is (input: { dir, config }) => GraphIR. The member's own chant graph loads it in the reader project, so it runs under the member's toolchain, and it must only read files. Any package may supply it, not only a lexicon. Not with lexicon. A chant older than this field can't read a kinds file that uses it."
         },
         "config": {
           "type": "object",
-          "description": "The lexicon's config namespace for the reader project, such as terraform's roots. Placeholders are substituted; nothing else is interpreted."
+          "description": "With lexicon, the lexicon's config namespace for the reader project, such as terraform's roots. With reader, the config object the module is called with (optional). Placeholders are substituted; nothing else is interpreted."
         }
       },
+      "if": { "properties": { "reader": true }, "required": ["reader"] },
+      "then": { "not": { "properties": { "lexicon": true }, "required": ["lexicon"] } },
+      "else": { "properties": { "lexicon": true, "config": true }, "required": ["lexicon", "config"] },
       "patternProperties": {
         "^x-": true
       },
@@ -281,6 +355,30 @@
         }
       },
       "additionalProperties": false
+    },
+    "memberFile": {
+      "type": "object",
+      "description": "A file every member of this kind has, and the JSON Schema it must pass (#3672). chant workspace check reads the file from the member's directory, parses it as YAML when its name ends in .yml or .yaml and as JSON otherwise, and validates it against the schema (WSP012). The schema is a JSON file inside the supplying package, read as data with draft 2020-12. A chant older than this field fails a kinds file that uses it.",
+      "required": [
+        "path",
+        "schema"
+      ],
+      "properties": {
+        "path": {
+          "type": "string",
+          "description": "The file, relative to the member's directory, such as terragucci.yml. Forward slashes; no .. segment and no leading /.",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.?(/|$))[^\\\\]+$"
+        },
+        "schema": {
+          "type": "string",
+          "description": "The JSON Schema the file must pass, relative to the supplying package's directory, such as schemas/terragucci.schema.json. It must be a .json file inside the package.",
+          "pattern": "^(?!/)(?!.*(^|/)\\.\\.?(/|$))[^\\\\]+\\.json$"
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
     }
   }
 }

package/src/workspace/workspace-ledger.ts

@@ -0,0 +1,130 @@
+/**
+ * The workspace's own ledger (#2554, #2524 D17, ws-030): `_members/_workspace/`
+ * on the `chant/lifecycle` branch, beside every member's `_members/<member>/`.
+ * `_workspace` is a reserved member name, so no member writes here.
+ *
+ * Three stores, each a JSON Lines file appended with the read-modify-write
+ * and CAS retry every ledger here uses:
+ *
+ * - `<env>/runs.jsonl`: one record per `chant workspace run`, naming every
+ *   `<member>/<op>` step, how it ended, and the member run it started. Each
+ *   member run cites the workspace run back (`OpRunRecord.workspaceRun`).
+ * - `_gates/<gate>.jsonl`: a workspace gate's pending facts and approvals.
+ *   Each names the member plans it covers and their digest
+ *   (`./workspace-gates.ts`).
+ * - `<env>/trains.jsonl`: release trains, each pinning one release of every
+ *   `chant` member (`./release-train.ts`).
+ *
+ * A malformed line is skipped and counted, never thrown on.
+ */
+
+import { createHash } from "node:crypto";
+import { readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeBlobToPath, type LedgerLocation } from "../lifecycle/git";
+import { MEMBERS_DIR } from "../lifecycle/member-ledger";
+import { sortedJsonReplacer } from "../utils";
+
+/** The reserved member name the workspace's own ledger sits under. */
+export const WORKSPACE_LEDGER_NAME = "_workspace";
+/** The branch prefix of the workspace's ledger. */
+export const WORKSPACE_LEDGER_PREFIX = `${MEMBERS_DIR}/${WORKSPACE_LEDGER_NAME}/`;
+/** The environment directory a run with no `--env` records under, as a member Op run does. */
+export const DEFAULT_WORKSPACE_ENV = "local";
+export const WORKSPACE_GATES_DIR = "_gates";
+
+const APPEND_RETRY_ATTEMPTS = 5;
+
+function at(cwd: string): LedgerLocation {
+  return { cwd, ledgerPrefix: WORKSPACE_LEDGER_PREFIX };
+}
+
+/** Append one line to `<dir>/<file>` in the workspace ledger. Returns the ledger commit. */
+export async function appendWorkspaceLine(cwd: string, dir: string, file: string, value: unknown, message: string): Promise<string> {
+  const json = JSON.stringify(value, sortedJsonReplacer);
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const priorSha = await readPathSha(dir, file, at(cwd));
+      const existing = priorSha ? await readBlobBySha(priorSha, { cwd }) : null;
+      const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${json}\n`;
+      return await writeBlobToPath(dir, file, content, message, { ...at(cwd), expectPriorPathSha: priorSha });
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/** Read every line of `<dir>/<file>` that `accept` takes, oldest first. */
+export async function readWorkspaceLines<T>(cwd: string, dir: string, file: string, accept: (v: unknown) => v is T): Promise<{ records: T[]; malformed: number }> {
+  const content = await readBlobFromPath(dir, file, at(cwd));
+  if (!content) return { records: [], malformed: 0 };
+  const records: T[] = [];
+  let malformed = 0;
+  for (const line of content.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const v = JSON.parse(line) as unknown;
+      if (accept(v)) records.push(v);
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** `sha256:<hex>` over a value's canonical JSON (keys sorted). */
+export function canonicalDigest(value: unknown): string {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value, sortedJsonReplacer)).digest("hex")}`;
+}
+
+// ── Runs ─────────────────────────────────────────────────────────────────────
+
+/** How one `<member>/<op>` step of a workspace run ended. */
+export type WorkspaceStepStatus = "ok" | "fail" | "gated" | "not-run";
+
+export interface WorkspaceRunStep {
+  /** `<member>/<op>`. */
+  target: string;
+  member: string;
+  op: string;
+  status: WorkspaceStepStatus;
+  /** The member's `chant run` exit code; null for a step that did not run. */
+  exitCode: number | null;
+  /** The member run's id, read back from the member's run ledger, where it cites this run. Null when none was found. */
+  memberRun: string | null;
+  /** For a gated step: the member gate it stopped at and the plan it waits on. */
+  gate?: { op: string; name: string; planDigest: string | null; environment: string | null };
+}
+
+export interface WorkspaceRunRecord {
+  version: 1;
+  id: string;
+  started: string;
+  ended: string;
+  /** `gated` when a step stopped at a gate; `fail` when a step failed. A run stops at the first step that does not pass. */
+  status: "ok" | "fail" | "gated";
+  /** `--env`, or null. */
+  env: string | null;
+  /** The workspace gate the run was started under (`--gate`), or null. */
+  gate: string | null;
+  /** `--dependents-of`, the member whose dependents the run ran, or null. */
+  dependentsOf: string | null;
+  steps: WorkspaceRunStep[];
+}
+
+const RUNS_FILE = "runs.jsonl";
+
+function isRunRecord(v: unknown): v is WorkspaceRunRecord {
+  const r = v as WorkspaceRunRecord;
+  return typeof r === "object" && r !== null && r.version === 1 && typeof r.id === "string" && Array.isArray(r.steps);
+}
+
+export async function appendWorkspaceRun(cwd: string, record: WorkspaceRunRecord): Promise<string> {
+  return appendWorkspaceLine(cwd, record.env ?? DEFAULT_WORKSPACE_ENV, RUNS_FILE, record, `Workspace run record: ${record.id}`);
+}
+
+export async function readWorkspaceRuns(cwd: string, env: string = DEFAULT_WORKSPACE_ENV): Promise<{ records: WorkspaceRunRecord[]; malformed: number }> {
+  return readWorkspaceLines(cwd, env, RUNS_FILE, isRunRecord);
+}

package/src/workspace/workspace-run.test.ts

@@ -0,0 +1,322 @@
+/**
+ * Workspace Ops (#2554, #2524 D17, ws-030, ws-039): OPS019 over the composed
+ * graph, the run's order and dependents, its ledger and the member records
+ * that cite it, the workspace gate rule, and release trains.
+ */
+import { describe, test, expect, afterEach } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { runCrossRootChecks } from "../lint/post-synth";
+import { ops019Check, parseWorkspaceOpTarget } from "../lint/rules/op/ops019-workspace-op-target";
+import { evaluateGate, memoryGateLedgerPort } from "../op/gate";
+import { buildRunRecord } from "../lifecycle/run-ledger";
+import { writeLedgerFiles } from "../lifecycle/git";
+import { resolveWorkspaceRun, WORKSPACE_GATE_ENV, WORKSPACE_RUN_ENV } from "../op/workspace-run-env";
+import type { WorkspaceGraph } from "./compose-graph";
+import { crossRootInputs, dependentsOf, orderTargets, workspaceRun, type MemberOpResult } from "./workspace-run";
+import { readWorkspaceRuns } from "./workspace-ledger";
+import { approveWorkspaceGate, readWorkspaceGate, workspaceGateDigest, workspaceGateStandsIn, type WorkspaceGateApproval } from "./workspace-gates";
+import { pickTrain } from "./release-train";
+import { decideRootCommand } from "./root-refusal";
+
+const PLAN_A = `sha256:${"a".repeat(64)}`;
+const PLAN_B = `sha256:${"b".repeat(64)}`;
+
+function opNode(member: string, name: string, env?: string) {
+  return { id: `${member}/${name}`, kind: "Chant::Op", lexicon: "chant", member, attrs: { name, overview: "t", phases: [], ...(env ? { labels: { Env: env } } : {}) } };
+}
+
+function member(name: string, status: "composed" | "skipped" | "failed" = "composed", kind = "chant") {
+  return { name, dir: name, kind, status, reason: null, chant: null, irVersion: 1, live: false };
+}
+
+function link(producer: string, consumer: string) {
+  return { consumer, producer, output: "out", kind: "depends-on", origin: "declared", resolves: "source", status: "resolved", label: "exact", input: null, reason: null };
+}
+
+/** network <- api <- web, and docs (other) composes nothing. */
+function graph(): WorkspaceGraph {
+  return {
+    version: 1,
+    workspace: { name: "acme", root: "." },
+    members: [member("network"), member("api"), member("web"), member("docs", "skipped", "other")],
+    nodes: [opNode("network", "deploy"), opNode("api", "deploy"), opNode("api", "migrate", "prod"), opNode("web", "deploy"), { id: "api/bucket", kind: "AWS::S3::Bucket", lexicon: "aws", member: "api", attrs: {} }],
+    edges: [],
+    groups: { byMember: {} },
+    exports: [],
+    imports: [],
+    links: [link("network", "api"), link("api", "web")],
+    collectors: [],
+    records: [],
+  } as unknown as WorkspaceGraph;
+}
+
+describe("OPS019: workspace Op targets against the composed graph", () => {
+  test("parses <member>/<op> at the first slash", () => {
+    expect(parseWorkspaceOpTarget("api/deploy")).toEqual({ member: "api", op: "deploy" });
+    expect(parseWorkspaceOpTarget("api/ns/op")).toEqual({ member: "api", op: "ns/op" });
+    expect(parseWorkspaceOpTarget("deploy")).toBeNull();
+    expect(parseWorkspaceOpTarget("/deploy")).toBeNull();
+    expect(parseWorkspaceOpTarget("api/")).toBeNull();
+  });
+
+  test("each composed chant member is one root, with its Ops among the entities", () => {
+    const roots = crossRootInputs(graph());
+    expect(roots.map((r) => r.root)).toEqual(["network", "api", "web"]);
+    const api = roots.find((r) => r.root === "api")!;
+    expect([...api.buildResult.entities.keys()].sort()).toEqual(["bucket", "deploy", "migrate"]);
+    expect(api.buildResult.entities.get("deploy")!.entityType).toBe("Chant::Op");
+  });
+
+  test("a target naming a declared Op passes; an unknown Op or a member not composed fails", () => {
+    const roots = crossRootInputs(graph());
+    const ok = runCrossRootChecks([ops019Check([{ member: "api", op: "deploy" }])], roots);
+    expect(ok).toEqual([]);
+    const bad = runCrossRootChecks([ops019Check([{ member: "api", op: "nope" }, { member: "docs", op: "deploy" }, { member: "ghost", op: "x" }])], roots);
+    expect(bad.map((d) => d.checkId)).toEqual(["OPS019", "OPS019", "OPS019"]);
+    expect(bad[0]!.message).toContain('declares no Op named "nope"');
+    expect(bad[0]!.message).toContain("deploy, migrate");
+    expect(bad[0]!.root).toBe("api");
+    expect(bad[1]!.message).toContain('member "docs" is not in the composed graph');
+    expect(bad[2]!.missing).toEqual({ kind: "member", scope: "ghost" });
+  });
+});
+
+describe("order and dependents", () => {
+  test("dependents follow member links transitively, nearest first", () => {
+    expect(dependentsOf("network", graph().links)).toEqual(["api", "web"]);
+    expect(dependentsOf("web", graph().links)).toEqual([]);
+  });
+
+  test("a producer's target runs before its consumers', whatever order they were named in", () => {
+    const order = orderTargets([{ member: "web", op: "deploy" }, { member: "network", op: "deploy" }, { member: "api", op: "deploy" }], graph().links);
+    expect(order.map((t) => t.member)).toEqual(["network", "api", "web"]);
+  });
+
+  test("unlinked targets keep the order given", () => {
+    const order = orderTargets([{ member: "web", op: "deploy" }, { member: "docs", op: "x" }], []);
+    expect(order.map((t) => t.member)).toEqual(["web", "docs"]);
+  });
+});
+
+// ── Runs, against a real chant/lifecycle branch ──────────────────────────────
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });
+});
+
+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(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-ws-run-")));
+  dirs.push(dir);
+  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"), "x\n");
+  git(["add", "."], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+  return dir;
+}
+
+/**
+ * A member runner that behaves like `chant run`: it writes the member's run
+ * record, citing the workspace run it found in its environment, and for a
+ * gated exit a pending gate fact with a plan digest.
+ */
+function fakeMembers(cwd: string, exits: Record<string, number>, seen: Array<{ member: string; argv: string[]; env: Record<string, string> }>) {
+  let n = 0;
+  return async (m: { name: string; dir: string }, argv: string[], env: Record<string, string>): Promise<MemberOpResult> => {
+    seen.push({ member: m.name, argv, env });
+    const op = argv[1]!;
+    const exitCode = exits[`${m.name}/${op}`] ?? 0;
+    const cite = resolveWorkspaceRun(env)!;
+    const id = `run-${++n}`;
+    const record = {
+      version: 1,
+      ...buildRunRecord({ name: op, labels: {} }, [], {
+        started: "2026-10-23T00:00:00Z",
+        ended: "2026-10-23T00:00:01Z",
+        status: exitCode === 3 ? "gated" : exitCode === 0 ? "ok" : "fail",
+        id,
+        workspaceRun: cite,
+        ...(exitCode === 3 ? { gate: { name: "approve", since: "2026-10-23T00:00:01Z" } } : {}),
+      }),
+    };
+    const files = [{ path: `_members/${m.name}/local/runs__${op}.jsonl`, content: `${JSON.stringify(record)}\n` }];
+    if (exitCode === 3) {
+      const pending = { version: 1, kind: "pending", op, gate: "approve", timestamp: "2026-10-23T00:00:01Z", expiresAt: "2026-10-30T00:00:01Z", runId: id, planDigest: m.name === "api" ? PLAN_A : PLAN_B };
+      files.push({ path: `_members/${m.name}/_gates/${op}.jsonl`, content: `${JSON.stringify(pending)}\n` });
+    }
+    await writeLedgerFiles(files, `fake run ${id}`, { cwd });
+    return { exitCode, stdout: `ran ${op}\n`, stderr: "" };
+  };
+}
+
+describe("chant workspace run", () => {
+  test("refuses before running anything when OPS019 finds a target that doesn't exist", async () => {
+    const seen: Array<{ member: string; argv: string[]; env: Record<string, string> }> = [];
+    const cwd = repo();
+    const out = await workspaceRun({ cwd, targets: ["api/deploy", "api/nope"], readGraph: async () => ({ graph: graph(), failed: false }), runMember: fakeMembers(cwd, {}, seen) });
+    expect(out.kind).toBe("refused");
+    if (out.kind === "refused") expect(out.findings.map((f) => f.checkId)).toEqual(["OPS019"]);
+    expect(seen).toEqual([]);
+  });
+
+  test("runs each target under the workspace run's id, in link order, and records it under _members/_workspace/", async () => {
+    const seen: Array<{ member: string; argv: string[]; env: Record<string, string> }> = [];
+    const cwd = repo();
+    const out = await workspaceRun({ cwd, targets: ["web/deploy", "api/deploy"], readGraph: async () => ({ graph: graph(), failed: false }), runMember: fakeMembers(cwd, {}, seen) });
+    expect(out.kind).toBe("ran");
+    if (out.kind !== "ran") return;
+    expect(seen.map((s) => s.member)).toEqual(["api", "web"]);
+    expect(seen[0]!.argv).toEqual(["run", "deploy"]);
+    expect(seen.every((s) => s.env[WORKSPACE_RUN_ENV] === out.record.id)).toBe(true);
+    expect(out.record.status).toBe("ok");
+    // Each member record cites the workspace run, and the workspace record names each member run.
+    expect(out.record.steps.map((s) => [s.target, s.status, s.memberRun])).toEqual([["api/deploy", "ok", "run-1"], ["web/deploy", "ok", "run-2"]]);
+    expect(out.ledgerError).toBeNull();
+    expect(git(["show", "chant/lifecycle:_members/_workspace/local/runs.jsonl"], cwd)).toContain(out.record.id);
+    const api = JSON.parse(git(["show", "chant/lifecycle:_members/api/local/runs__deploy.jsonl"], cwd)) as { workspaceRun: { id: string } };
+    expect(api.workspaceRun.id).toBe(out.record.id);
+    expect((await readWorkspaceRuns(cwd)).records.map((r) => r.id)).toEqual([out.record.id]);
+  });
+
+  test("stops at the first step that fails", async () => {
+    const seen: Array<{ member: string; argv: string[]; env: Record<string, string> }> = [];
+    const cwd = repo();
+    const out = await workspaceRun({ cwd, targets: ["network/deploy", "api/deploy", "web/deploy"], readGraph: async () => ({ graph: graph(), failed: false }), runMember: fakeMembers(cwd, { "api/deploy": 1 }, seen) });
+    if (out.kind !== "ran") throw new Error(out.kind);
+    expect(out.record.status).toBe("fail");
+    expect(out.record.steps.map((s) => s.status)).toEqual(["ok", "fail", "not-run"]);
+  });
+
+  test("--dependents-of runs the Op in every dependent, not in the member itself, and skips a dependent without it", async () => {
+    const g = graph();
+    g.nodes = g.nodes.filter((n) => n.id !== "web/deploy");
+    const seen: Array<{ member: string; argv: string[]; env: Record<string, string> }> = [];
+    const cwd = repo();
+    const planned = await workspaceRun({ cwd, targets: [], dependentsOf: "network", op: "deploy", dryRun: true, readGraph: async () => ({ graph: g, failed: false }), runMember: fakeMembers(cwd, {}, seen) });
+    expect(planned).toMatchObject({ kind: "planned", targets: ["api/deploy"], skipped: [{ member: "web", reason: 'declares no Op named "deploy"' }] });
+    expect(seen).toEqual([]);
+    const refused = await workspaceRun({ cwd, targets: [], dependentsOf: "network", readGraph: async () => ({ graph: g, failed: false }) });
+    expect(refused).toMatchObject({ kind: "refused", message: "--dependents-of needs the Op to run: --op <op>" });
+  });
+
+  test("with --gate, gated members are gathered into one workspace gate pending fact over their plans", async () => {
+    const seen: Array<{ member: string; argv: string[]; env: Record<string, string> }> = [];
+    const cwd = repo();
+    const out = await workspaceRun({ cwd, targets: ["api/deploy", "web/deploy"], gate: "release", readGraph: async () => ({ graph: graph(), failed: false }), runMember: fakeMembers(cwd, { "api/deploy": 3, "web/deploy": 3 }, seen) });
+    if (out.kind !== "ran") throw new Error(out.kind);
+    expect(seen.every((s) => s.env[WORKSPACE_GATE_ENV] === "release")).toBe(true);
+    expect(out.record.status).toBe("gated");
+    expect(out.record.steps.map((s) => s.status)).toEqual(["gated", "gated"]);
+    expect(out.pending?.covers).toEqual([
+      { member: "api", op: "deploy", gate: "approve", planDigest: PLAN_A },
+      { member: "web", op: "deploy", gate: "approve", planDigest: PLAN_B },
+    ]);
+    const approval = await approveWorkspaceGate(cwd, { gate: "release", approvedBy: "alice", timestamp: "2026-10-23T01:00:00Z" });
+    expect(approval.digest).toBe(out.pending!.digest);
+    expect((await readWorkspaceGate(cwd, "release")).approvals).toHaveLength(1);
+  });
+});
+
+describe("a workspace gate never satisfies a member gate unless it covers the plan and the member opts in at base (ws-039)", () => {
+  const covers = [{ member: "api", op: "deploy", gate: "approve", planDigest: PLAN_A }];
+  const approval: WorkspaceGateApproval = { version: 1, kind: "approval", gate: "release", digest: workspaceGateDigest(covers), covers, approvedBy: "alice", timestamp: "2026-10-23T01:00:00Z" };
+  const q = { op: "deploy", gate: "approve", planDigest: PLAN_A };
+
+  test("a member that has not opted in is never satisfied", () => {
+    expect(workspaceGateStandsIn(q, { member: "api", optedIn: false, approvals: [approval] })).toBeNull();
+  });
+
+  test("an opted-in member is satisfied only for the plan the approval covers", () => {
+    expect(workspaceGateStandsIn(q, { member: "api", optedIn: true, approvals: [approval] })).toBe(approval);
+    expect(workspaceGateStandsIn({ ...q, planDigest: PLAN_B }, { member: "api", optedIn: true, approvals: [approval] })).toBeNull();
+    expect(workspaceGateStandsIn(q, { member: "web", optedIn: true, approvals: [approval] })).toBeNull();
+    expect(workspaceGateStandsIn({ ...q, gate: "other" }, { member: "api", optedIn: true, approvals: [approval] })).toBeNull();
+  });
+
+  test("covers edited after the approval no longer hash to its digest, and count for nothing", () => {
+    const edited = { ...approval, covers: [{ ...covers[0]!, planDigest: PLAN_B }] };
+    expect(workspaceGateStandsIn({ ...q, planDigest: PLAN_B }, { member: "api", optedIn: true, approvals: [edited] })).toBeNull();
+  });
+
+  test("evaluateGate passes a plan-bound gate via the workspace only when the stand-in answers, and writes nothing to the member's ledger", async () => {
+    const port = memoryGateLedgerPort();
+    const standIn = { standIn: async () => ({ gate: "release", digest: approval.digest, approvedBy: "alice", timestamp: approval.timestamp }) };
+    const passed = await evaluateGate(port, { op: "deploy", gate: "approve", planDigest: PLAN_A, now: "2026-10-23T02:00:00Z", workspace: standIn });
+    expect(passed).toMatchObject({ satisfied: true, via: "workspace", resolution: { resolvedBy: "alice", workspaceGate: { gate: "release", digest: approval.digest } } });
+    expect(port.resolved).toEqual([]);
+
+    const refused = await evaluateGate(memoryGateLedgerPort(), { op: "deploy", gate: "approve", planDigest: PLAN_A, now: "2026-10-23T02:00:00Z", workspace: { standIn: async () => null } });
+    expect(refused.satisfied).toBe(false);
+  });
+
+  test("a gate bound to no plan never asks the workspace", async () => {
+    let asked = false;
+    const check = await evaluateGate(memoryGateLedgerPort(), { op: "deploy", gate: "approve", now: "2026-10-23T02:00:00Z", workspace: { standIn: async () => { asked = true; return null; } } });
+    expect(check.satisfied).toBe(false);
+    expect(asked).toBe(false);
+  });
+});
+
+describe("member run records cite the workspace run", () => {
+  test("the environment names the run and its gate; a plain run names neither", () => {
+    expect(resolveWorkspaceRun({ [WORKSPACE_RUN_ENV]: "ws-1", [WORKSPACE_GATE_ENV]: "release" })).toEqual({ id: "ws-1", gate: "release" });
+    expect(resolveWorkspaceRun({})).toBeUndefined();
+  });
+
+  test("buildRunRecord carries the citation only when given one", () => {
+    const base = { started: "a", ended: "b", status: "ok" as const };
+    expect(buildRunRecord({ name: "deploy" }, [], { ...base, workspaceRun: { id: "ws-1" } }).workspaceRun).toEqual({ id: "ws-1" });
+    expect("workspaceRun" in buildRunRecord({ name: "deploy" }, [], base)).toBe(false);
+  });
+});
+
+describe("release trains", () => {
+  const rel = (member: string, digest: string, label: string | null) => ({ member, releaseDigest: digest, commit: "c".repeat(40), label });
+  test("pins the newest release of every member", () => {
+    const picked = pickTrain([
+      { member: "api", releases: [rel("api", "sha256:2", "v2"), rel("api", "sha256:1", "v1")] },
+      { member: "web", releases: [rel("web", "sha256:9", null)] },
+    ]);
+    expect(picked).toEqual({ members: [rel("api", "sha256:2", "v2"), rel("web", "sha256:9", null)] });
+  });
+
+  test("a pin picks a release by label or digest", () => {
+    const picked = pickTrain([{ member: "api", releases: [rel("api", "sha256:2", "v2"), rel("api", "sha256:1", "v1")] }], new Map([["api", "v1"]]));
+    expect(picked).toEqual({ members: [rel("api", "sha256:1", "v1")] });
+  });
+
+  test("refuses when any member has no release, so a train never leaves one out", () => {
+    const picked = pickTrain([{ member: "api", releases: [rel("api", "sha256:2", "v2")] }, { member: "web", releases: [] }], new Map([["ghost", "v1"]]));
+    expect(picked).toEqual({ problems: ["--pin ghost: not a chant member of the workspace", "member web has no release; cut one with chant release cut in its directory"] });
+  });
+});
+
+describe("chant run at a declared root keeps the root's own Ops", () => {
+  test("Op discovery at the root finds the root's Ops and none of a member's", async () => {
+    const dir = repo();
+    const op = (name: string) => `export default { props: { name: ${JSON.stringify(name)}, overview: "t", phases: [{ name: "Run", steps: [] }] } };\n`;
+    writeFileSync(join(dir, "chant.config.json"), JSON.stringify({ lexicons: [] }));
+    writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "api", dir: "api", kind: "chant" }] }));
+    mkdirSync(join(dir, "ops"), { recursive: true });
+    writeFileSync(join(dir, "ops", "root.op.ts"), op("root-op"));
+    mkdirSync(join(dir, "api", "ops"), { recursive: true });
+    writeFileSync(join(dir, "api", "chant.config.json"), JSON.stringify({ lexicons: [] }));
+    writeFileSync(join(dir, "api", "ops", "deploy.op.ts"), op("deploy"));
+    const { discoverOps } = await import("../op/discover");
+    const { ops } = await discoverOps({ cwd: dir });
+    expect([...ops.keys()]).toEqual(["root-op"]);
+    // A root build is guarded (WSP000); `run` is not, so it runs the root's Ops above.
+    expect(decideRootCommand({ verb: "build", target: dir, workspaceDir: dir, rootOnly: false }).action).toBe("refuse");
+  });
+});