@intentius/chant 0.124.27 → 0.124.29

package/src/workspace/delivery-metrics.test.ts

@@ -0,0 +1,236 @@
+/**
+ * #4039: the four DORA metrics from the deploy records, the releases and the
+ * ci/revoked tags, with a failure window of 7 days. Against a temp repo;
+ * nothing is pushed.
+ *
+ * The fixture's prod ledger, one member, failure window 7 days:
+ *
+ *   api  09-01 R1 | 09-03 R2 (R2's commit revoked 09-05) | 09-06 R3
+ *   web  09-01 R1 | 09-10 R3 | 09-11 redeploy R3 | 09-14 rollback to R1 | 09-20 R4 | 09-30 rollback to R3
+ *   db   09-21 no release, commit c4
+ *
+ * api's 09-03 deploy fails by revocation and is restored by the 09-06 deploy.
+ * web's 09-10 deploy fails by the rollback 4 days later, which restores it;
+ * the redeploy between them neither restores it nor hides the rollback, and
+ * is counted apart from the deploys.
+ * web's 09-20 deploy is rolled back 10 days later, outside the window, so it
+ * did not fail.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import schema from "./delivery-metrics.schema.json";
+import { contract } from "./__fixtures__/contract-repo";
+import { deliveryMetrics, formatMetrics, type DeliveryMetricsDocument } from "./delivery-metrics";
+import { appendCut, makeRelease, persistRelease, type Release } from "../lifecycle/release-store";
+import { appendReleaseRecord, type ReleaseRecord, type ReleaseRecordInput } from "../lifecycle/release-ledger";
+import { environmentMetrics, rollbackOf, type MetricsLookups } from "../lifecycle/delivery-metrics";
+import { contentDigest } from "../content-digest";
+
+const { expectValid } = contract(schema);
+
+function git(cwd: string, env: Record<string, string>, ...args: string[]): string {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8", env: { ...process.env, ...env } });
+  if (r.status !== 0) throw new Error(`git ${args.join(" ")}: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+const DAY = 86_400;
+const t = (day: string) => `2026-09-${day}T00:00:00.000Z`;
+const dated = (iso: string) => ({ GIT_AUTHOR_DATE: iso, GIT_COMMITTER_DATE: iso });
+
+interface Fixture {
+  commits: string[];
+  releases: Release[];
+}
+
+/** Write the declaration, with `metrics` when given. Only the working tree's copy is read for it. */
+function declare(dir: string, metrics: object | undefined): void {
+  writeFileSync(
+    join(dir, "chant.workspace.json"),
+    JSON.stringify({ name: "acme", schema: 1, minReader: "0.80.0", members: [{ name: "root", dir: ".", kind: "other", because: "the fixture" }], ...(metrics ? { metrics } : {}) }, null, 2),
+  );
+}
+
+/** The workspace, its four commits and releases, and the prod ledger above. */
+async function setup(dir: string): Promise<Fixture> {
+  git(dir, {}, "init", "-q", "-b", "main");
+  git(dir, {}, "config", "user.email", "t@chant.dev");
+  git(dir, {}, "config", "user.name", "T");
+  declare(dir, { failureWindowDays: 7 });
+  git(dir, {}, "add", ".");
+  git(dir, dated("2026-08-30T00:00:00.000Z"), "commit", "-q", "-m", "c1");
+  const commits = [git(dir, {}, "rev-parse", "HEAD")];
+  for (const day of ["02", "05", "19"]) {
+    git(dir, dated(t(day)), "commit", "-q", "--allow-empty", "-m", `c ${day}`);
+    commits.push(git(dir, {}, "rev-parse", "HEAD"));
+  }
+  const releases = commits.map((commit) =>
+    makeRelease({ member: null, commit, artifactDigests: [], targets: [{ env: "prod", templates: [{ component: "api", path: "t.json", digest: `sha256:${"c".repeat(64)}` }], params: [] }] }),
+  );
+  for (const [i, r] of releases.entries()) {
+    await persistRelease(r, [], { cwd: dir });
+    await appendCut({ releaseDigest: r.releaseDigest, label: `v1.${i}.0`, actor: "alice", timestamp: t("01"), runOrigin: null }, { cwd: dir });
+  }
+
+  const [R1, R2, R3, R4] = releases;
+  const deploy = (component: string, day: string, release: Release | null, extra: Partial<ReleaseRecordInput> = {}): ReleaseRecordInput => ({
+    component,
+    env: "prod",
+    digest: contentDigest(`${component} ${release?.releaseDigest ?? "plain"}`),
+    gitSha: release?.commit ?? commits[3],
+    runId: `${component}-${day}`,
+    timestamp: t(day),
+    actor: "ci",
+    ...(release ? { releaseDigest: release.releaseDigest } : {}),
+    ...extra,
+  });
+  const ref = (component: string, day: string) => ({ env: "prod", runId: `${component}-${day}`, timestamp: t(day) });
+  const ledger: ReleaseRecordInput[] = [
+    deploy("api", "01", R1),
+    deploy("web", "01", R1),
+    deploy("api", "03", R2),
+    deploy("api", "06", R3),
+    deploy("web", "10", R3),
+    deploy("web", "11", R3, { redeploys: ref("web", "10") }),
+    deploy("web", "14", R1, { restores: ref("web", "01") }),
+    deploy("web", "20", R4),
+    deploy("db", "21", null),
+    deploy("web", "30", R3, { restores: ref("web", "10") }),
+  ];
+  for (const record of ledger) await appendReleaseRecord(record, { cwd: dir });
+
+  // R2's commit is revoked on 09-05, two days after api deployed it.
+  const record = { schema: 1, tag: "revoked", commit: commits[1], branch: "main", at: t("05"), phase: "test", run: { name: "test", id: 7, conclusion: "failure", url: null } };
+  git(dir, dated(t("05")), "tag", "-a", "-m", `ci: phase test failed\n\n${JSON.stringify(record)}\n`, `ci/revoked/${commits[1]}`, commits[1]);
+  return { commits, releases };
+}
+
+function result(doc: DeliveryMetricsDocument): Extract<DeliveryMetricsDocument, { members: unknown }> {
+  expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const NOW = "2026-10-01T00:00:00.000Z";
+
+// One fixture for the file: its ledger takes a commit per record. Each test
+// sets the declaration it needs.
+let dir: string;
+let fixture: Fixture;
+beforeAll(async () => {
+  dir = realpathSync(mkdtempSync(join(tmpdir(), "chant-4039-")));
+  fixture = await setup(dir);
+}, 60_000);
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+describe("DORA metrics from release, gate and revocation records (#4039)", () => {
+  test("with N = 7: a revoked release, a rollback inside the window, a rollback outside it, and the restore time of each failure", async () => {
+    declare(dir, { failureWindowDays: 7 });
+    const { commits, releases } = fixture;
+    const doc = result(await deliveryMetrics({ cwd: dir, since: t("01"), now: NOW }));
+    expect(doc.failureWindowDays).toBe(7);
+    expect(doc.workspace).toEqual({ name: "acme" });
+    expect(doc.window).toEqual({ since: t("01"), until: NOW, days: 30 });
+    const [prod] = doc.members[0].environments;
+    expect(doc.members[0]).toMatchObject({ member: "root", reason: null });
+
+    expect(prod.deployments).toEqual({ count: 9, redeploys: 1, runs: 9, fromRelease: 8, perWeek: 2.1 });
+
+    // R1 2 days after c1, R2, R3 and R4 a day after theirs, db's plain commit c4 2 days after it.
+    expect(prod.leadTime).toEqual({ changes: 5, fromRelease: 4, fromCommit: 1, unknown: 0, medianSeconds: DAY });
+
+    expect(prod.changeFailure).toEqual({ deployments: 9, failed: 2, revoked: 1, rolledBack: 1, rate: 0.2222 });
+    expect(prod.failures).toEqual([
+      {
+        component: "api",
+        timestamp: t("03"),
+        runId: "api-03",
+        releaseDigest: releases[1].releaseDigest,
+        label: "v1.1.0",
+        commit: commits[1],
+        causes: ["revoked"],
+        revoked: { tag: `ci/revoked/${commits[1]}`, tagged: expect.stringMatching(/^2026-09-05T00:00:00/) },
+        rolledBackBy: null,
+        restoredBy: { runId: "api-06", timestamp: t("06") },
+        restoreSeconds: 3 * DAY,
+      },
+      {
+        component: "web",
+        timestamp: t("10"),
+        runId: "web-10",
+        releaseDigest: releases[2].releaseDigest,
+        label: "v1.2.0",
+        commit: commits[2],
+        causes: ["rolled-back"],
+        revoked: null,
+        rolledBackBy: { runId: "web-14", timestamp: t("14") },
+        restoredBy: { runId: "web-14", timestamp: t("14") },
+        restoreSeconds: 4 * DAY,
+      },
+    ]);
+    // web's 09-20 deploy, rolled back on 09-30, is outside the 7 days and did not fail.
+    expect(prod.failures.some((f) => f.timestamp === t("20"))).toBe(false);
+    expect(prod.restore).toEqual({ restored: 2, open: 0, medianSeconds: 3.5 * DAY });
+
+    expect(formatMetrics(doc)).toContain("root prod: 9 deploys (2.1/week), lead time 1d, change failure 22.2% (2/9), restore 3.5d");
+  });
+
+  test("the declaration's failure window decides, and 7 is the default", async () => {
+    declare(dir, { failureWindowDays: 14 });
+    const wide = result(await deliveryMetrics({ cwd: dir, since: t("01"), now: NOW }));
+    // With 14 days the 09-30 rollback of the 09-20 deploy counts too.
+    expect(wide.members[0].environments[0].changeFailure).toMatchObject({ failed: 3, rolledBack: 2 });
+    expect(wide.members[0].environments[0].failures.at(-1)).toMatchObject({ timestamp: t("20"), restoredBy: { runId: "web-30" }, restoreSeconds: 10 * DAY });
+
+    declare(dir, undefined);
+    const doc = result(await deliveryMetrics({ cwd: dir, since: t("01"), now: NOW, env: "prod", members: ["root"] }));
+    expect(doc.failureWindowDays).toBe(7);
+    expect(doc.members[0].environments[0].changeFailure.failed).toBe(2);
+    expect(await deliveryMetrics({ cwd: dir, env: "../x" })).toMatchObject({ error: { code: "environment-invalid" } });
+    expect(await deliveryMetrics({ cwd: dir, members: ["nope"] })).toMatchObject({ error: { code: "declaration-invalid" } });
+  });
+});
+
+describe("environmentMetrics", () => {
+  const record = (component: string, day: string, extra: Partial<ReleaseRecord> = {}): ReleaseRecord => ({
+    version: 1,
+    component,
+    env: "prod",
+    digest: `sha256:${"a".repeat(64)}`,
+    gitSha: "c".repeat(40),
+    runId: `${component}-${day}`,
+    timestamp: t(day),
+    actor: "ci",
+    ...extra,
+  });
+  const lookups: MetricsLookups = {
+    releaseOf: (r) => r.releaseDigest,
+    commitOfRelease: () => null,
+    labelOf: () => null,
+    revocationOf: () => null,
+    commitTime: () => Date.parse("2026-08-31T00:00:00.000Z"),
+  };
+
+  test("a deploy before the window is not counted, and a failed deploy with no restore is open", () => {
+    const m = environmentMetrics(
+      "prod",
+      [record("api", "01"), record("api", "10"), record("api", "12", { restores: { env: "prod", runId: "api-01", timestamp: t("01") } })],
+      { ...lookups, revocationOf: (sha) => (sha === "c".repeat(40) ? { tag: "ci/revoked/c", tagged: null } : null) },
+      { since: t("05"), until: NOW },
+    );
+    // Every commit is revoked here, with a lightweight tag, so nothing restores.
+    expect(m.changeFailure).toEqual({ deployments: 2, failed: 2, revoked: 2, rolledBack: 1, rate: 1 });
+    expect(m.restore).toEqual({ restored: 0, open: 2, medianSeconds: null });
+    // The commit's first deploy was before the window, so it has no lead time here.
+    expect(m.leadTime.changes).toBe(0);
+  });
+
+  test("a rollback is a record with restores; nothing else is", () => {
+    expect(rollbackOf(record("api", "01"))).toBeNull();
+    expect(rollbackOf(record("api", "02", { restores: { env: "prod", runId: "x", timestamp: t("01") } }))).toEqual({ env: "prod", runId: "x", timestamp: t("01") });
+  });
+});

package/src/workspace/delivery-metrics.ts

@@ -0,0 +1,286 @@
+/**
+ * `chant workspace metrics [--env <env>] [--member <name>] [--since <date>] [--json]`
+ * (#4039): the four DORA metrics per member and environment, from the deploy
+ * records, the releases and their revocations on `chant/lifecycle`.
+ *
+ * The `--json` document is `delivery-metrics.schema.json`, a read-contract
+ * output, so behold, a Grafana panel and terragucci's own estate read the
+ * same numbers. The metrics are computed in `../lifecycle/delivery-metrics.ts`;
+ * this module reads what they need:
+ *
+ * - each member's `<env>/releases.jsonl`, every environment it has, read in
+ *   full, since deploys before the window decide lead times and deploys after
+ *   a failure decide its restore;
+ * - its releases, for the commit each was cut from, and the release gate's
+ *   resolutions, for a deploy that names its release only through its
+ *   admission (`releaseOfDeploy`, #4043);
+ * - the counted `ci/revoked/<sha>` tags, judged as `release cut` judges them
+ *   (`readRevokedCommits`, #4033), and each commit's committer time from git.
+ *
+ * Outside a workspace the project's own ledger is read as one member, `null`.
+ * It reads the local branch and the local tags, and never fetches.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { DEFAULT_FAILURE_WINDOW_DAYS, environmentMetrics, type EnvironmentMetrics, type MetricsWindow } from "../lifecycle/delivery-metrics";
+import type { LedgerLocation } from "../lifecycle/git";
+import { findWorkspaceRoot } from "../project-root";
+import { readDeclaration, readerVersion, WorkspaceReadError } from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import { gitTop, workingTree } from "./tree";
+import { handToRootChant } from "./which-chant";
+
+export const DELIVERY_METRICS_CONTRACT_VERSION = 1;
+export const DELIVERY_METRICS_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/delivery-metrics/v1/delivery-metrics.schema.json";
+
+/** The window when `--since` is not given: eight weeks back from now. */
+export const DEFAULT_METRICS_DAYS = 56;
+
+/** Why the read stopped. Closed. Outside a workspace there is no declaration to fail, so `declaration-missing` never comes back. */
+export const METRICS_ERROR_CODES = [
+  "declaration-ambiguous",
+  "declaration-unparseable",
+  "declaration-invalid",
+  "placement-invalid",
+  "reader-too-old",
+  "root-chant-required",
+  "not-a-git-repository",
+  "environment-invalid",
+] as const satisfies readonly ReasonCode[];
+export type MetricsErrorCode = (typeof METRICS_ERROR_CODES)[number];
+
+/** Why a member's metrics are missing or partial. Closed. */
+export const METRICS_REASON_CODES = ["ledger-unreadable", "ledger-malformed"] as const satisfies readonly ReasonCode[];
+export type MetricsReasonCode = (typeof METRICS_REASON_CODES)[number];
+
+const ENV_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+const USAGE = "chant workspace metrics [dir] [--env <env>] [--member <name>] [--since <date>] [--json]";
+
+/** One member's metrics. */
+export interface MemberMetrics {
+  /** The member's name, or null for a project outside a workspace. */
+  member: string | null;
+  /** Each environment with a deploy ledger, sorted by name. */
+  environments: EnvironmentMetrics[];
+  /** Null when everything was read. */
+  reason: { code: MetricsReasonCode; message: string } | null;
+}
+
+export type DeliveryMetricsDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      /** The workspace's name, or null for a project outside a workspace. */
+      workspace: { name: string } | null;
+      lifecycle: { ref: string; commit: string | null };
+      window: MetricsWindow & { days: number };
+      failureWindowDays: number;
+      members: MemberMetrics[];
+    }
+  | { $schema: string; contract: number; chant: string; error: { code: MetricsErrorCode; message: string } };
+
+export interface MetricsQuery {
+  cwd: string;
+  /** Only this environment. */
+  env?: string;
+  /** Only these members. */
+  members?: string[];
+  /** ISO-8601 date or time; the default is {@link DEFAULT_METRICS_DAYS} days before `now`. */
+  since?: string;
+  /** For tests: the end of the window. */
+  now?: string;
+}
+
+class MetricsError extends Error {
+  constructor(
+    readonly code: MetricsErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+function tryGit(cwd: string, args: string[]): string | null {
+  try {
+    return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Read the metrics document for the workspace or project holding `query.cwd`. */
+export async function deliveryMetrics(query: MetricsQuery): Promise<DeliveryMetricsDocument> {
+  const head = { $schema: DELIVERY_METRICS_SCHEMA_ID, contract: DELIVERY_METRICS_CONTRACT_VERSION, chant: readerVersion() };
+  try {
+    if (query.env !== undefined && (!ENV_PATTERN.test(query.env) || query.env.includes(".."))) {
+      throw new MetricsError("environment-invalid", `--env ${JSON.stringify(query.env)} can't be an environment: use letters, digits, ".", "_" and "-", starting with a letter or digit`);
+    }
+    const top = gitTop(query.cwd);
+    if (!top) throw new MetricsError("not-a-git-repository", `${query.cwd} is not in a git repository, so it has no chant/lifecycle branch to read`);
+
+    const found = findWorkspaceRoot(query.cwd);
+    const declaration = found ? readDeclaration(workingTree(found.dir), "", { rootChant: true }) : null;
+    const root = found?.dir ?? query.cwd;
+    const failureWindowDays = declaration?.metrics?.failureWindowDays ?? DEFAULT_FAILURE_WINDOW_DAYS;
+
+    const until = query.now ?? new Date().toISOString();
+    const since = query.since ?? new Date(Date.parse(until) - DEFAULT_METRICS_DAYS * 86_400_000).toISOString();
+    const window = { since: new Date(Date.parse(since)).toISOString(), until: new Date(Date.parse(until)).toISOString() };
+    const days = Math.round(((Date.parse(window.until) - Date.parse(window.since)) / 86_400_000) * 100) / 100;
+
+    // The revoked commits, judged against ci.green at base (#4033). Tags that
+    // can't be judged stop the read: the failure rate would be wrong otherwise.
+    const { readRevokedCommits } = await import("../lifecycle/release-revocation");
+    const revoked = await readRevokedCommits(root);
+
+    const commitTimes = new Map<string, number | null>();
+    const commitTime = (sha: string): number | null => {
+      if (!commitTimes.has(sha)) {
+        const iso = tryGit(top, ["show", "-s", "--format=%cI", `${sha}^{commit}`]);
+        commitTimes.set(sha, iso ? Date.parse(iso) : null);
+      }
+      return commitTimes.get(sha)!;
+    };
+
+    let ledgers: { member: string | null; loc: LedgerLocation }[];
+    if (declaration) {
+      const wanted = query.members && query.members.length > 0 ? new Set(query.members) : null;
+      if (wanted) {
+        const unknown = [...wanted].filter((n) => !declaration.members.some((m) => m.name === n));
+        if (unknown.length > 0) throw new WorkspaceReadError("declaration-invalid", `--member ${unknown.join(", ")} names no member of the workspace`);
+      }
+      ledgers = declaration.members
+        .filter((m) => !wanted || wanted.has(m.name))
+        .map((m) => ({ member: m.name, loc: { cwd: root, member: m.dir === "." ? "." : m.name } }));
+    } else {
+      ledgers = [{ member: null, loc: { cwd: query.cwd } }];
+    }
+
+    const members: MemberMetrics[] = [];
+    for (const l of ledgers) members.push(await memberMetrics(l.member, l.loc, { env: query.env, window, failureWindowDays, revoked, commitTime }));
+
+    return {
+      ...head,
+      workspace: declaration ? { name: declaration.name } : null,
+      lifecycle: { ref: "chant/lifecycle", commit: tryGit(top, ["rev-parse", "--verify", "--quiet", "refs/heads/chant/lifecycle"]) || null },
+      window: { ...window, days },
+      failureWindowDays,
+      members,
+    };
+  } catch (err) {
+    if (err instanceof WorkspaceReadError) return { ...head, error: { code: err.code as MetricsErrorCode, message: err.message } };
+    if (err instanceof MetricsError) return { ...head, error: { code: err.code, message: err.message } };
+    throw err;
+  }
+}
+
+async function memberMetrics(
+  member: string | null,
+  loc: LedgerLocation,
+  ctx: {
+    env: string | undefined;
+    window: MetricsWindow;
+    failureWindowDays: number;
+    revoked: ReadonlyMap<string, { tag: string; tagged: string | null }>;
+    commitTime: (sha: string) => number | null;
+  },
+): Promise<MemberMetrics> {
+  try {
+    const { listReleaseEnvironments, readReleaseLedger } = await import("../lifecycle/release-ledger");
+    const { readAllReleases, readCuts, labelsByDigest } = await import("../lifecycle/release-store");
+    const { readGateLedger } = await import("../lifecycle/gate-ledger");
+    const { releaseOfDeploy } = await import("../lifecycle/release-join");
+    const { RELEASE_GATE_OP } = await import("../op/gate-name");
+
+    let envs = (await listReleaseEnvironments(loc)).sort();
+    if (ctx.env !== undefined) envs = envs.filter((e) => e === ctx.env);
+    if (envs.length === 0) return { member, environments: [], reason: null };
+
+    const { releases, malformed: badReleases } = await readAllReleases(loc);
+    const commits = new Map(releases.map((r) => [r.releaseDigest, r.commit]));
+    const labels = labelsByDigest((await readCuts(loc)).cuts);
+    const { resolutions } = await readGateLedger(RELEASE_GATE_OP, loc);
+
+    const environments: EnvironmentMetrics[] = [];
+    let badLines = 0;
+    for (const env of envs) {
+      const { records, malformed } = await readReleaseLedger(env, loc);
+      badLines += malformed;
+      environments.push(
+        environmentMetrics(
+          env,
+          records,
+          {
+            releaseOf: (r) => releaseOfDeploy(r, resolutions),
+            commitOfRelease: (d) => commits.get(d) ?? null,
+            labelOf: (d) => labels.get(d) ?? null,
+            revocationOf: (sha) => {
+              const r = ctx.revoked.get(sha);
+              return r ? { tag: r.tag, tagged: r.tagged } : null;
+            },
+            commitTime: ctx.commitTime,
+          },
+          ctx.window,
+          ctx.failureWindowDays,
+        ),
+      );
+    }
+    const reason =
+      badLines + badReleases > 0
+        ? { code: "ledger-malformed" as const, message: `${badLines} deploy record line(s) and ${badReleases} release file(s) could not be read and are left out` }
+        : null;
+    return { member, environments, reason };
+  } catch (err) {
+    return { member, environments: [], reason: { code: "ledger-unreadable", message: `reading the ledger failed: ${err instanceof Error ? err.message : String(err)}` } };
+  }
+}
+
+const seconds = (s: number | null): string => {
+  if (s === null) return "none";
+  if (s < 3600) return `${Math.round(s / 60)}m`;
+  if (s < 86_400) return `${Math.round((s / 3600) * 10) / 10}h`;
+  return `${Math.round((s / 86_400) * 10) / 10}d`;
+};
+
+/** The text view: one line per member and environment. */
+export function formatMetrics(doc: Extract<DeliveryMetricsDocument, { members: unknown }>): string {
+  const lines = [`window ${doc.window.since} to ${doc.window.until} (${doc.window.days} days), failure window ${doc.failureWindowDays} days`];
+  for (const m of doc.members) {
+    if (m.reason) lines.push(`${m.member ?? "."}: ${m.reason.code}: ${m.reason.message}`);
+    for (const e of m.environments) {
+      const rate = e.changeFailure.rate === null ? "-" : `${Math.round(e.changeFailure.rate * 1000) / 10}%`;
+      lines.push(
+        `${m.member ?? "."} ${e.env}: ${e.deployments.count} deploys (${e.deployments.perWeek}/week), lead time ${seconds(e.leadTime.medianSeconds)}, ` +
+          `change failure ${rate} (${e.changeFailure.failed}/${e.changeFailure.deployments}), restore ${seconds(e.restore.medianSeconds)}` +
+          (e.restore.open > 0 ? `, ${e.restore.open} open` : ""),
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+export async function runWorkspaceMetrics(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.since !== undefined && (args.since === "" || Number.isNaN(Date.parse(args.since)))) {
+    console.error(formatError({ message: `--since ${JSON.stringify(args.since)} is not a date: give an ISO-8601 date such as 2026-09-01`, hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(args.extraPositional ?? ".");
+  if (!existsSync(cwd)) {
+    console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+    return 1;
+  }
+  const handed = await handToRootChant(cwd, undefined);
+  if (handed !== undefined) return handed;
+  const doc = await deliveryMetrics({ cwd, ...(args.env ? { env: args.env } : {}), ...(args.members ? { members: args.members } : {}), ...(args.since ? { since: args.since } : {}) });
+  if (args.json) console.log(JSON.stringify(doc, null, 2));
+  else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+  else console.log(formatMetrics(doc));
+  return "error" in doc ? 1 : 0;
+}

package/src/workspace/flags-read.ts

@@ -0,0 +1,121 @@
+/**
+ * Reading a workspace's feature flags (#4024): every flag of the declared
+ * flag kinds, and the flags of one member by parameter. Kept apart from
+ * `./flags.ts`, which `records.ts` loads, since reading goes through
+ * `records-cli.ts`.
+ */
+
+import { join, relative, resolve, sep } from "node:path";
+import { loadRecordKind } from "./records";
+import type { FlagValue, WorkspaceFlags } from "./flags";
+
+const str = (v: unknown): string | null => (typeof v === "string" && v !== "" ? v : null);
+
+/** A flag value as the record writes it, or undefined for one a build-time parameter can't hold. */
+function flagValue(v: unknown): FlagValue | undefined {
+  return typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? v : undefined;
+}
+
+/**
+ * Every flag of every flag kind the declaration at `root` names, read in the
+ * working tree. A kind without a flag block is skipped without reading its
+ * records. Throws a `RecordReadError` when a flag kind or its records can't
+ * be read, and a `WorkspaceReadError` when the declaration can't.
+ */
+export async function readWorkspaceFlags(root: string): Promise<WorkspaceFlags> {
+  const { readDeclaration, declaredRecordKinds } = await import("./declaration");
+  const { workingTree } = await import("./tree");
+  const declaration = readDeclaration(workingTree(root));
+  const out: WorkspaceFlags = { flags: [], invalid: [] };
+  const declared = declaredRecordKinds(declaration);
+  if (declared.length === 0) return out;
+  const { readRecordsFor } = await import("./records-cli");
+  for (const d of declared) {
+    const file = join(root, ...d.path.split("/"));
+    const loaded = await loadRecordKind(file, root);
+    const flag = loaded.kind.flag;
+    if (!flag) continue;
+    const { result, root: repo } = await readRecordsFor({ kind: file, cwd: root, current: true });
+    for (const r of result.records) {
+      const path = relative(root, join(repo, ...r.path.split("/"))).split(sep).join("/");
+      const member = r.data ? str(r.data[flag.member]) : null;
+      if (!r.valid || r.id === null || r.data === null) {
+        out.invalid.push({ kind: d.path, path, member, message: r.reasons.map((x) => `${x.code}: ${x.message}`).join("; ") || "the record can't be read" });
+        continue;
+      }
+      const values: Record<string, FlagValue> = {};
+      const raw = r.data[flag.values];
+      if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+        for (const [env, v] of Object.entries(raw as Record<string, unknown>)) {
+          const value = flagValue(v);
+          if (value !== undefined) values[env] = value;
+        }
+      }
+      out.flags.push({
+        id: r.id,
+        kind: d.path,
+        path,
+        member: member ?? "",
+        param: str(r.data[flag.param]) ?? "",
+        owner: str(r.data[flag.owner]) ?? "",
+        values,
+        work: r.flag?.work ?? null,
+        implements: r.flag?.implements ?? [],
+        stale: r.flag?.stale ?? false,
+      });
+    }
+  }
+  return out;
+}
+
+/** One flag-backed parameter, as a build in one environment reads it. */
+export interface FlagBinding {
+  /** The flag's name. */
+  flag: string;
+  /** The flag's value in the environment, or undefined when the record gives it none. */
+  value: FlagValue | undefined;
+}
+
+/** The flags that back the parameters of the member holding a directory. */
+export interface MemberFlagBindings {
+  /** The member's name in the declaration. */
+  member: string;
+  /** Each flag-backed parameter by name. */
+  byParam: Record<string, FlagBinding>;
+  /** Why a flag of this member can't be trusted: an invalid record that names it, or two flags for one parameter. */
+  errors: string[];
+}
+
+/**
+ * The flags that back parameters of the member holding `projectDir`, in the
+ * workspace whose declaration is in `root`, with each flag's value for `env`.
+ * Null when no member holds the directory, since only a member has flags.
+ */
+export async function memberFlagBindings(root: string, projectDir: string, env: string): Promise<MemberFlagBindings | null> {
+  const { readDeclaration, resolveGroups, ownerOf } = await import("./declaration");
+  const { workingTree } = await import("./tree");
+  const tree = workingTree(root);
+  const declaration = readDeclaration(tree);
+  const rel = relative(root, resolve(projectDir)).split(sep).join("/");
+  const owner = ownerOf(declaration, resolveGroups(declaration, tree), rel === "" ? "" : rel);
+  if (!owner || !("member" in owner)) return null;
+  const member = owner.member.name;
+  const read = await readWorkspaceFlags(root);
+  const errors: string[] = [];
+  for (const bad of read.invalid) {
+    if (bad.member === member || bad.member === null) errors.push(`flag record ${bad.path} is not valid, so no build reads it: ${bad.message}`);
+  }
+  const byParam: Record<string, FlagBinding> = {};
+  const seen = new Map<string, string>();
+  for (const f of read.flags) {
+    if (f.member !== member) continue;
+    const other = seen.get(f.param);
+    if (other !== undefined) {
+      errors.push(`flags ${other} and ${f.id} both set build parameter "${f.param}" of member ${member}; one flag backs one parameter`);
+      continue;
+    }
+    seen.set(f.param, f.id);
+    byParam[f.param] = { flag: f.id, value: f.values[env] };
+  }
+  return { member, byParam, errors };
+}