@intentius/chant 0.124.27 → 0.124.29

package/src/lifecycle/change-set-store.ts

@@ -0,0 +1,113 @@
+/**
+ * Stored change sets (#4022): each change-set document a gate binds, kept on
+ * `chant/lifecycle` under its digest so the plan an approval bound can be read
+ * once the run that planned it is gone.
+ *
+ * A pull-request gate, a release gate and an `empty` resolution (ws-104
+ * question 2 and 6) bind the change-set document's `digest`
+ * (`../change-set.ts`) in `planDigest`. Only that value reaches the gate
+ * ledger, so this store keeps the document beside it:
+ *
+ *   _change-sets/<digest>.json    the document, written once and never rewritten
+ *
+ * `:` is written as `_` in the file name, as `_plans/`, `_builds/` and
+ * `_releases/` do. A workspace member's copy sits under
+ * `_members/<member>/_change-sets/` through the same `ledgerDir` prefix the
+ * gate ledger uses, so a gate and its change set are read from one member.
+ *
+ * The stored document is the one the gate bound, with each entry's graph
+ * `node` (`../change-set-graph.ts`) and the `graph` it came from. Neither is
+ * hashed, so the stored document still verifies against its digest. A
+ * component gate in a plain `run --components` binds a lifecycle-plan digest
+ * and stores nothing here.
+ *
+ * `chant lifecycle gc` removes a stored change set from the branch's tree
+ * once #4036's retention policy lets it go (./retention.ts); history keeps it.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID, verifyChangeSetDigest, type ChangeSetDocument } from "../change-set";
+import { ledgerDir, readBlobFromPath, readPathSha, RefCASConflictError, writeLedgerFiles, type LedgerLocation } from "./git";
+
+/** The directory on `chant/lifecycle` that holds stored change sets. */
+export const CHANGE_SETS_DIR = "_change-sets";
+
+/** The file a change set with `digest` is stored in, inside {@link CHANGE_SETS_DIR}. */
+export function changeSetFile(digest: string): string {
+  return `${digest.replace(/:/g, "_")}.json`;
+}
+
+/** Thrown when a document can't be stored: it is not a change-set document, or its content does not hash to its digest. */
+export class ChangeSetStoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ChangeSetStoreError";
+  }
+}
+
+/**
+ * Store a change-set document under its digest. A document already stored
+ * under the digest is never rewritten. Refuses a document whose content does
+ * not hash to its own `digest`. Does not push: call `pushLifecycleReport`
+ * (./git.ts) after, or let the gate's own pending fact push it.
+ */
+export async function persistChangeSet(
+  doc: ChangeSetDocument,
+  opts?: { cwd?: string },
+): Promise<{ commit: string | null; written: boolean }> {
+  if (doc?.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT) {
+    throw new ChangeSetStoreError(`not a change-set document: its $schema is not ${CHANGE_SET_SCHEMA_ID} with contract ${CHANGE_SET_CONTRACT}`);
+  }
+  if (!verifyChangeSetDigest(doc)) {
+    throw new ChangeSetStoreError(`change set ${doc.digest} does not hash to its own digest; refusing to store it`);
+  }
+  const file = changeSetFile(doc.digest);
+  if ((await readPathSha(CHANGE_SETS_DIR, file, opts)) !== null) return { commit: null, written: false };
+  const dir = await ledgerDir(CHANGE_SETS_DIR, opts);
+  try {
+    const commit = await writeLedgerFiles(
+      [{ path: `${dir}/${file}`, content: `${JSON.stringify(doc, sortedJsonReplacer)}\n`, expectPriorSha: null }],
+      `Change set ${doc.digest}`,
+      opts,
+    );
+    return { commit, written: true };
+  } catch (err) {
+    // Another writer stored the same digest first; what is there is the same document.
+    if (err instanceof RefCASConflictError) return { commit: null, written: false };
+    throw err;
+  }
+}
+
+/** What reading one stored change set found. */
+export type StoredChangeSetRead =
+  | { status: "found"; document: ChangeSetDocument }
+  | { status: "missing" }
+  /** A file is stored under the digest, and it is not a change-set document whose content hashes to that digest. */
+  | { status: "malformed"; message: string };
+
+/** Parse a stored file, checking it is the document `digest` names. */
+export function parseStoredChangeSet(text: string, digest: string): StoredChangeSetRead {
+  let doc: ChangeSetDocument;
+  try {
+    doc = JSON.parse(text) as ChangeSetDocument;
+  } catch (err) {
+    return { status: "malformed", message: `the file stored under ${digest} is not JSON: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (!doc || typeof doc !== "object" || doc.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT || !Array.isArray(doc.entries) || !Array.isArray(doc.members)) {
+    return { status: "malformed", message: `the file stored under ${digest} is not a change-set document` };
+  }
+  if (doc.digest !== digest || !verifyChangeSetDigest(doc)) {
+    return { status: "malformed", message: `the change set stored under ${digest} does not hash to that digest` };
+  }
+  return { status: "found", document: doc };
+}
+
+/**
+ * Read the change set stored under `digest`. Reads the local `chant/lifecycle`
+ * branch and never fetches. Throws only when git itself fails.
+ */
+export async function readStoredChangeSet(digest: string, opts?: LedgerLocation): Promise<StoredChangeSetRead> {
+  const text = await readBlobFromPath(CHANGE_SETS_DIR, changeSetFile(digest), opts);
+  if (text === null) return { status: "missing" };
+  return parseStoredChangeSet(text, digest);
+}

package/src/lifecycle/commit-sha.ts

@@ -0,0 +1,23 @@
+/**
+ * The commit a run, a gate or a deploy is for (#4020), as one answer for every
+ * record that carries it. The checkout's `HEAD` is what the process builds
+ * from, so it comes first; a CI job whose checkout has no git (a bare
+ * artifact job) falls back to the commit the forge says it started for.
+ * Undefined when neither is known, so a record leaves the field out rather
+ * than guessing.
+ */
+
+import { ciCommitFromEnv } from "../op/gate-run-locator";
+import { getHeadCommit } from "./git";
+
+export async function resolveCommitSha(
+  opts: { cwd?: string; env?: Record<string, string | undefined> } = {},
+): Promise<string | undefined> {
+  try {
+    const head = await getHeadCommit(opts.cwd ? { cwd: opts.cwd } : undefined);
+    if (/^[0-9a-f]{40,64}$/.test(head)) return head;
+  } catch {
+    // Not a checkout, or no git on the path: the environment may still say.
+  }
+  return ciCommitFromEnv(opts.env);
+}

package/src/lifecycle/delivery-metrics.ts

@@ -0,0 +1,263 @@
+/**
+ * The four DORA metrics of one environment's deploy records (#4039): how
+ * often it deploys, the lead time from commit to running release, the change
+ * failure rate and the time to restore.
+ *
+ * Everything here is pure. The caller reads the ledgers, the release files
+ * and the ci tags, and hands this module one environment's records with
+ * lookups for the rest; `workspace/delivery-metrics.ts` does that for
+ * `chant workspace metrics`.
+ *
+ * A deploy is one record in `<env>/releases.jsonl`: one component deployed
+ * once. A redeploy, which puts the running release back, is counted apart and
+ * is not a deploy for the metrics. A deploy fails when, within the failure window after it, the commit
+ * it deployed is revoked (a counted `ci/revoked/<sha>` tag, #4033) or the
+ * environment is rolled back from it. Which records are rollbacks, and which
+ * put the current release back, is decided in {@link rollbackOf} and
+ * {@link isRedeploy} and nowhere else, so a new kind of rollback record
+ * (#4035) changes those two functions only.
+ */
+
+import type { ReleaseRecord, ReleaseRef } from "./release-ledger";
+
+/** The failure window when the declaration's `metrics.failureWindowDays` is not set. */
+export const DEFAULT_FAILURE_WINDOW_DAYS = 7;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * The earlier deploy a rollback record restores, or null when the record is
+ * not a rollback. Today a rollback is a record `chant components rollback`
+ * wrote, which names what it restores in `restores` (#2531). Every rule below
+ * that asks whether a record rolled an environment back asks this function.
+ */
+export function rollbackOf(record: Pick<ReleaseRecord, "restores">): ReleaseRef | null {
+  return record.restores ?? null;
+}
+
+/**
+ * Whether the record put the current release back (`chant components
+ * redeploy`, #2604). A redeploy deploys the same release again, so it neither
+ * restores a failed deploy nor stands between a deploy and its rollback.
+ */
+export function isRedeploy(record: Pick<ReleaseRecord, "redeploys">): boolean {
+  return record.redeploys !== undefined;
+}
+
+/** A counted revoked tag on a commit, with the time it was made, or null for a lightweight tag. */
+export interface CommitRevocation {
+  tag: string;
+  tagged: string | null;
+}
+
+/** What the caller knows beyond the records, as lookups. */
+export interface MetricsLookups {
+  /** The release a deploy record names: its `releaseDigest`, else the one its release-gate admission names. Undefined when it names none. */
+  releaseOf: (record: ReleaseRecord) => string | undefined;
+  /** The commit a release was cut from, or null when its file can't be read here. */
+  commitOfRelease: (releaseDigest: string) => string | null;
+  /** The release's label, or null. */
+  labelOf: (releaseDigest: string) => string | null;
+  /** The counted revoked tag on a commit, or null when the commit is not revoked. */
+  revocationOf: (commit: string) => CommitRevocation | null;
+  /** The commit's committer time in milliseconds, or null when the commit is not in this repository. */
+  commitTime: (commit: string) => number | null;
+}
+
+/** The span of time the metrics count deploys in. */
+export interface MetricsWindow {
+  /** ISO-8601, inclusive. */
+  since: string;
+  /** ISO-8601, inclusive. */
+  until: string;
+}
+
+/** A record named the way `restores` names one. */
+export interface DeployRef {
+  runId: string;
+  timestamp: string;
+}
+
+/** One failed deploy, and how it was restored. */
+export interface DeployFailure {
+  component: string;
+  timestamp: string;
+  runId: string;
+  /** The release the deploy came from, or null for a deploy made from no release. */
+  releaseDigest: string | null;
+  label: string | null;
+  /** The commit it deployed: the release's commit, or the record's `gitSha` for a deploy made from no release. */
+  commit: string;
+  /** Why it counts as failed: `revoked`, `rolled-back`, or both. */
+  causes: Array<"revoked" | "rolled-back">;
+  /** The revoked tag on the commit, when that is a cause. */
+  revoked: CommitRevocation | null;
+  /** The rollback record that rolled the environment back from it, when that is a cause. */
+  rolledBackBy: DeployRef | null;
+  /** The next deploy of the component in the environment whose commit is not revoked, or null while there is none. */
+  restoredBy: DeployRef | null;
+  /** Seconds from the failed deploy to `restoredBy`, or null while it is not restored. */
+  restoreSeconds: number | null;
+}
+
+/** The four metrics of one environment. */
+export interface EnvironmentMetrics {
+  env: string;
+  deployments: {
+    /** Deploy records in the window, one per component deployed, leaving out redeploys. Rollbacks count. */
+    count: number;
+    /** Redeploys in the window: records that put the running release back, counted apart from `count`. */
+    redeploys: number;
+    /** Distinct `runId` values among them, so a run that deploys several components counts once. */
+    runs: number;
+    /** Of `count`, the deploys made from a release. */
+    fromRelease: number;
+    /** `count` over the window in weeks, to two decimals. */
+    perWeek: number;
+  };
+  leadTime: {
+    /** Changes whose first deploy here falls in the window and whose commit time is known. */
+    changes: number;
+    /** Of `changes`, releases (the first deploy naming the release). */
+    fromRelease: number;
+    /** Of `changes`, commits deployed from no release (the first deploy with that `gitSha`). */
+    fromCommit: number;
+    /** Changes left out because their commit is not in this repository. */
+    unknown: number;
+    /** The median, in seconds, or null when `changes` is 0. */
+    medianSeconds: number | null;
+  };
+  changeFailure: {
+    deployments: number;
+    failed: number;
+    /** Failed deploys whose commit was revoked within the window after them. */
+    revoked: number;
+    /** Failed deploys the environment was rolled back from within the window after them. */
+    rolledBack: number;
+    /** `failed` over `deployments`, to four decimals, or null with no deployments. */
+    rate: number | null;
+  };
+  restore: {
+    restored: number;
+    open: number;
+    medianSeconds: number | null;
+  };
+  /** The failed deploys in the window, oldest first. */
+  failures: DeployFailure[];
+}
+
+function median(values: number[]): number | null {
+  if (values.length === 0) return null;
+  const s = [...values].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return Math.round(s.length % 2 === 1 ? s[mid] : (s[mid - 1] + s[mid]) / 2);
+}
+
+const at = (iso: string): number => Date.parse(iso);
+const ref = (r: ReleaseRecord): DeployRef => ({ runId: r.runId, timestamp: r.timestamp });
+
+/**
+ * The metrics of one environment's records. `records` is the whole ledger of
+ * the environment, every component, in ledger order: deploys before the
+ * window still decide lead times, and deploys after a failure decide its
+ * restore. Only deploys whose `timestamp` falls in `window` are counted.
+ */
+export function environmentMetrics(
+  env: string,
+  records: readonly ReleaseRecord[],
+  lookups: MetricsLookups,
+  window: MetricsWindow,
+  failureWindowDays: number = DEFAULT_FAILURE_WINDOW_DAYS,
+): EnvironmentMetrics {
+  // Ledger order breaks timestamp ties, as `latestPerComponent` does.
+  const sorted = records.map((r, i) => ({ r, i })).sort((a, b) => at(a.r.timestamp) - at(b.r.timestamp) || a.i - b.i).map((x) => x.r);
+  const since = at(window.since);
+  const until = at(window.until);
+  const failureMs = failureWindowDays * DAY_MS;
+  const inWindow = (r: ReleaseRecord) => at(r.timestamp) >= since && at(r.timestamp) <= until;
+
+  const facts = sorted.map((r) => {
+    const releaseDigest = lookups.releaseOf(r) ?? null;
+    const commit = (releaseDigest !== null ? lookups.commitOfRelease(releaseDigest) : null) ?? r.gitSha;
+    return { r, releaseDigest, commit, revocation: lookups.revocationOf(commit) };
+  });
+
+  // A redeploy puts the running release back: it is counted apart, and
+  // neither fails nor restores on its own.
+  const deployments = facts.filter((f) => inWindow(f.r) && !isRedeploy(f.r));
+  const failures: DeployFailure[] = [];
+  for (const [i, f] of facts.entries()) {
+    if (!inWindow(f.r) || isRedeploy(f.r)) continue;
+    const t = at(f.r.timestamp);
+    const later = facts.slice(i + 1).filter((g) => g.r.component === f.r.component);
+
+    // Revoked within the window after the deploy. A tag with no time, or one
+    // made before the deploy, revokes what was deployed all the same.
+    const revoked = f.revocation !== null && (f.revocation.tagged === null || at(f.revocation.tagged) - t <= failureMs) ? f.revocation : null;
+
+    // Rolled back from it: the next deploy of the component that is not a
+    // redeploy is a rollback, within the window.
+    const next = later.find((g) => !isRedeploy(g.r));
+    const rolledBack = next !== undefined && rollbackOf(next.r) !== null && at(next.r.timestamp) - t <= failureMs ? next.r : null;
+
+    if (!revoked && !rolledBack) continue;
+    const restore = later.find((g) => !isRedeploy(g.r) && g.revocation === null);
+    failures.push({
+      component: f.r.component,
+      timestamp: f.r.timestamp,
+      runId: f.r.runId,
+      releaseDigest: f.releaseDigest,
+      label: f.releaseDigest !== null ? lookups.labelOf(f.releaseDigest) : null,
+      commit: f.commit,
+      causes: [...(revoked ? (["revoked"] as const) : []), ...(rolledBack ? (["rolled-back"] as const) : [])],
+      revoked,
+      rolledBackBy: rolledBack ? ref(rolledBack) : null,
+      restoredBy: restore ? ref(restore.r) : null,
+      restoreSeconds: restore ? Math.round((at(restore.r.timestamp) - t) / 1000) : null,
+    });
+  }
+
+  // Lead time: one change per release, or per commit deployed from no
+  // release, timed at its first deploy in this environment.
+  const firstDeploy = new Map<string, (typeof facts)[number]>();
+  for (const f of facts) {
+    const key = f.releaseDigest !== null ? `release:${f.releaseDigest}` : `commit:${f.r.gitSha}`;
+    if (!firstDeploy.has(key)) firstDeploy.set(key, f);
+  }
+  const leads: number[] = [];
+  let fromRelease = 0;
+  let unknown = 0;
+  for (const f of firstDeploy.values()) {
+    if (!inWindow(f.r)) continue;
+    const committed = lookups.commitTime(f.commit);
+    if (committed === null) {
+      unknown++;
+      continue;
+    }
+    leads.push(Math.max(0, (at(f.r.timestamp) - committed) / 1000));
+    if (f.releaseDigest !== null) fromRelease++;
+  }
+
+  const weeks = Math.max(until - since, DAY_MS) / (7 * DAY_MS);
+  const restored = failures.filter((x) => x.restoreSeconds !== null);
+  return {
+    env,
+    deployments: {
+      count: deployments.length,
+      redeploys: facts.filter((f) => inWindow(f.r) && isRedeploy(f.r)).length,
+      runs: new Set(deployments.map((f) => f.r.runId)).size,
+      fromRelease: deployments.filter((f) => f.releaseDigest !== null).length,
+      perWeek: Math.round((deployments.length / weeks) * 100) / 100,
+    },
+    leadTime: { changes: leads.length, fromRelease, fromCommit: leads.length - fromRelease, unknown, medianSeconds: median(leads) },
+    changeFailure: {
+      deployments: deployments.length,
+      failed: failures.length,
+      revoked: failures.filter((x) => x.revoked !== null).length,
+      rolledBack: failures.filter((x) => x.rolledBackBy !== null).length,
+      rate: deployments.length === 0 ? null : Math.round((failures.length / deployments.length) * 10_000) / 10_000,
+    },
+    restore: { restored: restored.length, open: failures.length - restored.length, medianSeconds: median(restored.map((x) => x.restoreSeconds!)) },
+    failures,
+  };
+}

package/src/lifecycle/deploy-outcome.ts

@@ -0,0 +1,147 @@
+/**
+ * What a promote, rollback or redeploy left behind when it did not deploy
+ * every component it planned (#4035).
+ *
+ * The release ledger records a component only once its deploy succeeded, so
+ * after a run that applied partly it still names the earlier release for
+ * every component that failed, and nothing says that component may be
+ * running part of the new one. A deploy outcome is the record of that run:
+ * one line per run in `<env>/outcomes.jsonl` on `chant/lifecycle`, beside
+ * the environment's `releases.jsonl` and under the same member prefix,
+ * naming each planned component and what happened to it.
+ *
+ * It is written only when the run ended with some components deployed and
+ * others not, or with a component that failed. A run that stopped at a gate
+ * before deploying anything changed nothing in the environment; its pending
+ * gate is what `workspace status` shows for it.
+ *
+ * The file is append-only, like the release ledger. Whether the environment
+ * is still mixed is derived when it is read ({@link ./mixed-environment.ts}):
+ * a component the outcome names as failed or gated stays unsettled until the
+ * release ledger has a newer record of it, which a redeploy, a rollback or
+ * the same promote run again writes.
+ */
+
+import { sortedJsonReplacer } from "../utils";
+import type { PromotionPlan } from "../components/promote";
+import type { DriverRunResult } from "../components/driver";
+
+/** The file a deploy outcome is appended to, under the environment's directory. */
+export const OUTCOMES_FILE = "outcomes.jsonl";
+
+/** What a run did to one component it planned. */
+export type DeployOutcomeState = "deployed" | "failed" | "gated" | "not-run";
+
+export interface DeployOutcomeComponent {
+  component: string;
+  /** `deployed` (a release record was written), `failed`, `gated` (stopped at a gate after the steps before it ran), or `not-run`. */
+  outcome: DeployOutcomeState;
+  /** The artifact digest the run was deploying. */
+  digest: string;
+  /** The release the run was deploying for this component, or null when it named none. */
+  releaseDigest: string | null;
+}
+
+/** One line of `<env>/outcomes.jsonl`. */
+export interface DeployOutcome {
+  version: 1;
+  env: string;
+  verb: "promote" | "rollback" | "redeploy";
+  /** The run id the run's release records carry. */
+  runId: string;
+  /** The timestamp the run's release records carry. */
+  timestamp: string;
+  actor: string;
+  /** The release the run deployed under (`--release`), or null. */
+  releaseDigest: string | null;
+  /** How the run ended. */
+  status: "fail" | "gated";
+  components: DeployOutcomeComponent[];
+}
+
+/**
+ * The outcome to record for a run, or null when there is nothing to record:
+ * every planned component deployed, or the run stopped at a gate with
+ * nothing deployed and nothing failed.
+ */
+export function deployOutcomeOf(input: {
+  verb: DeployOutcome["verb"];
+  plan: PromotionPlan;
+  run: Pick<DriverRunResult, "status" | "results">;
+  /** The release the run deployed under, if any. */
+  releaseDigest: string | null;
+  runId: string;
+  timestamp: string;
+  actor: string;
+}): DeployOutcome | null {
+  const { plan, run } = input;
+  if (run.status === "ok") return null;
+  const components: DeployOutcomeComponent[] = plan.items.map((item) => {
+    const result = run.results.find((r) => r.component === item.component);
+    const outcome: DeployOutcomeState = !result ? "not-run" : result.status === "ok" ? "deployed" : result.status === "gated" ? "gated" : "failed";
+    return {
+      component: item.component,
+      outcome,
+      digest: item.digest,
+      releaseDigest: input.releaseDigest ?? item.source.releaseDigest ?? null,
+    };
+  });
+  const deployed = components.some((c) => c.outcome === "deployed");
+  const failed = components.some((c) => c.outcome === "failed");
+  if (!deployed && !failed) return null;
+  return {
+    version: 1,
+    env: plan.to,
+    verb: input.verb,
+    runId: input.runId,
+    timestamp: input.timestamp,
+    actor: input.actor,
+    releaseDigest: input.releaseDigest,
+    status: run.status,
+    components,
+  };
+}
+
+const STATES: readonly string[] = ["deployed", "failed", "gated", "not-run"];
+
+function isOutcome(v: unknown): v is DeployOutcome {
+  const o = v as Partial<DeployOutcome> | null;
+  return (
+    o !== null &&
+    typeof o === "object" &&
+    o.version === 1 &&
+    typeof o.env === "string" &&
+    typeof o.runId === "string" &&
+    typeof o.timestamp === "string" &&
+    Array.isArray(o.components) &&
+    o.components.every((c) => c && typeof c.component === "string" && STATES.includes(c.outcome) && typeof c.digest === "string")
+  );
+}
+
+/** Parse the lines of an `outcomes.jsonl`, oldest first. A line that is not an outcome is counted and skipped. */
+export function parseDeployOutcomes(text: string | null): { outcomes: DeployOutcome[]; malformed: number } {
+  const outcomes: DeployOutcome[] = [];
+  let malformed = 0;
+  for (const line of (text ?? "").split("\n").map((l) => l.trim()).filter(Boolean)) {
+    try {
+      const parsed = JSON.parse(line) as unknown;
+      if (isOutcome(parsed)) outcomes.push(parsed);
+      else malformed++;
+    } catch {
+      malformed++;
+    }
+  }
+  return { outcomes, malformed };
+}
+
+/** Append one outcome to `<env>/outcomes.jsonl`. Does not push; the caller pushes with the release records. */
+export async function appendDeployOutcome(outcome: DeployOutcome, opts?: { cwd?: string }): Promise<string> {
+  const { appendLedgerLine } = await import("./git");
+  return appendLedgerLine(outcome.env, OUTCOMES_FILE, JSON.stringify(outcome, sortedJsonReplacer), "Deploy outcome", opts);
+}
+
+/** Every outcome recorded for `env`, oldest first, read where `readReleaseLedger` reads; `[]` when none is. */
+export async function readDeployOutcomes(env: string, opts?: import("./git").LedgerLocation): Promise<DeployOutcome[]> {
+  const { readBlobFromPath } = await import("./git");
+  return parseDeployOutcomes(await readBlobFromPath(env, OUTCOMES_FILE, opts)).outcomes;
+}

package/src/lifecycle/gate-change-set.e2e.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Stored change sets mapped onto a real graph (#4022).
+ *
+ * The estate is the aws source `__fixtures__/change-set/lifecycle-v2.ts.txt`
+ * as a workspace member, and the change set is
+ * `__fixtures__/change-set/lifecycle-plan.floci.json`, chant's real plan of
+ * that source against floci (see `../change-set.test.ts`). The graph is the
+ * member's own `chant graph --format ir`, run by `storeGateChangeSet` as a
+ * pull-request apply runs it, and the ids are checked against `chant
+ * workspace graph`, which is what behold reads. The stored document is then
+ * read back through `chant change-set show --json`, and the gate that binds
+ * it through `workspace status`'s gate reader.
+ */
+
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { composeChangeSet, lifecyclePlanPart } from "../change-set";
+import type { ChangeSet as LifecycleChangeSet } from "./change-set";
+import { storeGateChangeSet } from "./gate-change-set";
+import { appendPendingGate } from "./gate-ledger";
+import { clearMemberLedgerCache } from "./member-ledger";
+import { readMemberGates } from "../workspace/status-gates";
+
+const REPO = realpathSync(join(import.meta.dirname, "..", "..", "..", ".."));
+const LOADER = join(REPO, "node_modules", "tsx", "dist", "loader.mjs");
+const MAIN = join(REPO, "packages", "core", "src", "cli", "main.ts");
+const FIXTURES = join(import.meta.dirname, "..", "__fixtures__", "change-set");
+const TIMEOUT = 240_000;
+
+function chant(cwd: string, ...args: string[]): { code: number | null; stdout: string; stderr: string } {
+  const r = spawnSync(process.execPath, ["--import", `file://${LOADER}`, MAIN, ...args], { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  return { code: r.status, stdout: r.stdout, stderr: r.stderr };
+}
+
+describe("a change set stored by a gate, on a real estate's graph", () => {
+  let root: string;
+  let member: string;
+  const git = (...a: string[]) => {
+    const r = spawnSync("git", a, { cwd: root, encoding: "utf8" });
+    if (r.status !== 0) throw new Error(`git ${a.join(" ")}: ${r.stderr}`);
+    return r.stdout.trim();
+  };
+  const plan = JSON.parse(readFileSync(join(FIXTURES, "lifecycle-plan.floci.json"), "utf8")) as LifecycleChangeSet;
+  const doc = composeChangeSet([lifecyclePlanPart({ member: "queues", plan })]);
+
+  beforeAll(() => {
+    root = realpathSync(mkdtempSync(join(tmpdir(), "chant-change-set-graph-")));
+    member = join(root, "delivery");
+    mkdirSync(member);
+    symlinkSync(join(REPO, "node_modules"), join(root, "node_modules"));
+    writeFileSync(join(root, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [{ name: "delivery", dir: "delivery", kind: "chant" }] }));
+    writeFileSync(join(member, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+    writeFileSync(join(member, "queues.ts"), readFileSync(join(FIXTURES, "lifecycle-v2.ts.txt"), "utf8"));
+    writeFileSync(join(root, ".gitignore"), "node_modules\n");
+    git("init", "-q", "-b", "main");
+    git("config", "user.email", "ci@example.test");
+    git("config", "user.name", "ci");
+    git("add", "-A");
+    git("commit", "-qm", "queues");
+    clearMemberLedgerCache();
+  });
+
+  afterAll(() => {
+    if (root) rmSync(root, { recursive: true, force: true });
+  });
+
+  test("each entry carries the node chant workspace graph gives its address", async () => {
+    const head = git("rev-parse", "HEAD");
+    const stored = await storeGateChangeSet({ doc, cwd: member, at: head });
+    expect(stored.warning).toBeUndefined();
+    expect(stored).toMatchObject({ digest: doc.digest, written: true, graph: { member: "delivery", at: head } });
+
+    const graph = chant(root, "workspace", "graph");
+    expect(graph.code, graph.stderr).toBe(0);
+    const nodeIds = new Set((JSON.parse(graph.stdout) as { nodes: Array<{ id: string }> }).nodes.map((n) => n.id));
+
+    const shown = chant(member, "change-set", "show", doc.digest, "--json");
+    expect(shown.code, shown.stderr).toBe(0);
+    const out = JSON.parse(shown.stdout);
+    expect(out).toMatchObject({ contract: 1, member: "delivery", digest: doc.digest, reason: null });
+    expect(out.changeSet.digest).toBe(doc.digest);
+    expect(out.changeSet.graph).toEqual({ member: "delivery", at: head });
+    const nodes = Object.fromEntries((out.changeSet.entries as Array<{ address: string; node: string | null }>).map((e) => [e.address, e.node]));
+    // jobs, events and dlq are declared; alerts is a live topic v2 no longer declares, so it has no node.
+    expect(nodes).toEqual({ alerts: null, dlq: "delivery/dlq", events: "delivery/events", jobs: "delivery/jobs" });
+    for (const node of Object.values(nodes)) if (node !== null) expect(nodeIds.has(node), node).toBe(true);
+
+    // From the workspace root, by --member.
+    const fromRoot = chant(root, "change-set", "show", doc.digest, "--member", "delivery", "--json");
+    expect(JSON.parse(fromRoot.stdout)).toEqual(out);
+
+    // Without --json: the grouped summary, then each change on its node.
+    const text = chant(member, "change-set", "show", doc.digest);
+    expect(text.code, text.stderr).toBe(0);
+    expect(text.stdout).toContain(`Nodes from the graph of delivery at ${head.slice(0, 12)}:`);
+    expect(text.stdout).toMatch(/create\s+queues {2}dlq {2}delivery\/dlq/);
+  }, TIMEOUT);
+
+  test("the gate that binds it links to it in workspace status", async () => {
+    const now = new Date().toISOString();
+    const later = new Date(Date.now() + 3_600_000).toISOString();
+    await appendPendingGate({ op: "pr-7-delivery", gate: "pr-apply", planDigest: doc.digest, timestamp: now, expiresAt: later }, { cwd: member });
+    const { gates } = await readMemberGates("_members/delivery/_gates", "members", git("rev-parse", "chant/lifecycle"), [], root, now);
+    expect(gates).toEqual([expect.objectContaining({ component: "pr-7-delivery", state: "pending", planDigest: doc.digest, changeSet: doc.digest })]);
+
+    const status = chant(root, "workspace", "status", "dev", "--json");
+    expect(status.stdout, status.stderr).not.toBe("");
+    const gate = (JSON.parse(status.stdout).members as Array<{ name: string; gates?: Array<{ component: string; changeSet?: string }> }>)
+      .find((m) => m.name === "delivery")
+      ?.gates?.find((g) => g.component === "pr-7-delivery");
+    expect(gate?.changeSet, status.stderr).toBe(doc.digest);
+  }, TIMEOUT);
+
+  test("a digest nothing is stored under shows no change set and exits 1", () => {
+    const missing = chant(member, "change-set", "show", `jcs1-sha256:${"0".repeat(64)}`, "--json");
+    expect(missing.code).toBe(1);
+    expect(JSON.parse(missing.stdout)).toMatchObject({ member: "delivery", changeSet: null, reason: null });
+  }, TIMEOUT);
+});