@intentius/chant 0.124.28 → 0.124.30

package/src/workspace/status.ts

@@ -39,7 +39,10 @@ import type { CommandContext } from "../cli/registry";
 import { GATES_DIR } from "../lifecycle/gate-ledger";
 import { readPathSha } from "../lifecycle/git";
 import { latestPerComponent, readReleaseLedger, type ReleaseRecord } from "../lifecycle/release-ledger";
+import { describeRevocation, revokedCommitsAt, revokedReleaseLookup, type ReleaseRevocation, type RevokedRelease } from "../lifecycle/release-revocation";
 import { readReleasePlan, type ReleasePlan } from "../lifecycle/plan-ledger";
+import { readDeployOutcomes, type DeployOutcome } from "../lifecycle/deploy-outcome";
+import { mixedEnvironment, releaseRollbackLine, rollbackTarget, type MixedEnvironment, type ReleaseCheck } from "../lifecycle/mixed-environment";
 import { listWorkLeases, type WorkLeaseState } from "../lifecycle/work-lease";
 import { readCheckoutHead, worktreeChanges, type CheckoutHead } from "./records-checkout";
 import { policyView, replicationState, type ReplicationState } from "./wip";
@@ -50,6 +53,9 @@ import { loadKindRegistry, resolveMemberFields, type MemberFields } from "./kind
 import { factoryView, listingView, plantability, treeBytes, type FactoryView, type ListingView, type Plantable } from "./box-factory";
 import { declaredRecordKinds, extensionsAt, readDeclaration, readerVersion, WorkspaceReadError, type Declaration, type ErrorLocation, type Member } from "./declaration";
 import type { ReasonCode } from "./reason-codes";
+import type { FlagDecision, FlagValue } from "./flags";
+import type { OverlapChangeSetRef, OverlapReport } from "./overlap";
+import type { WorkLink } from "./work";
 import { readMemberPromotionOrder, type PromotionStep } from "./promotion-order";
 import { gateAdmissionFrom, releaseRuleFrom } from "./identity";
 import { checkReleaseSignature, type GateAdmissionRule, type ReleaseSignatureCheck } from "./identity-gate-rule";
@@ -126,6 +132,10 @@ export interface StatusRelease {
   approver: string | null;
   /** The gate resolution that admitted the release (#4020): the gate and when it was resolved. Null for an ungated release and for one recorded before chant 0.124.28. */
   admission: { op: string; gate: string; resolvedAt: string } | null;
+  /** The release this deploy was made from (#4043): the `releaseDigest` of `_releases/<releaseDigest>.json`. Null for a deploy that named no release and for one recorded before chant 0.124.29. */
+  releaseDigest: string | null;
+  /** The label that release was cut with (#4043), or null when it has none, when no release is named, or when the cut can't be read. Chant 0.124.29 and newer write it. */
+  releaseLabel: string | null;
   /** Read flags, such as `legacy-digest` (#2514). */
   flags: string[];
   /**
@@ -137,6 +147,25 @@ export interface StatusRelease {
    * hasn't fetched yet.
    */
   plan: ReleasePlan | null;
+  /**
+   * Set when the deploy names a release (`releaseDigest` on its record) that
+   * was cut from a revoked commit (#4033, ws-105): the revoked tag on that
+   * commit, the release and its label, and the line that rolls the component
+   * back. Absent otherwise, and from chant older than 0.124.29.
+   */
+  revoked?: StatusRevokedRelease;
+}
+
+/** A release an environment runs that was cut from a revoked commit (#4033). */
+export interface StatusRevokedRelease extends RevokedRelease {
+  /**
+   * The command that rolls the environment back, run in the member's
+   * directory: `chant components rollback <env> --release <label|digest>`
+   * naming the newest release the environment ran before this one that is
+   * still kept and not revoked (#4035), or `chant components rollback <env>
+   * --component <component>` when there is none.
+   */
+  rollback: string;
 }
 
 export interface StatusLedger {
@@ -154,6 +183,14 @@ export interface StatusEnvironment {
   /** The latest release of each component in the ledger, sorted by component. */
   releases: StatusRelease[];
   reason: { code: StatusReasonCode; message: string } | null;
+  /**
+   * Set when the environment runs a mix (#4035): a promote, rollback or
+   * redeploy left a component failed or gated and nothing has been recorded
+   * for it since, or its components' latest records name more than one
+   * release. Each component with what it runs, and the lines that settle it.
+   * Absent otherwise, and from chant older than 0.124.29.
+   */
+  mixed?: MixedEnvironment;
 }
 
 export type CompareState = "same" | "differs" | "only-env" | "only-compare";
@@ -207,6 +244,35 @@ export interface StatusMember {
    * cuts could not be read. Added in contract 1 by chant 0.124.28.
    */
   releaseCuts: StatusReleaseCut[] | null;
+  /**
+   * The member's feature flags (#4024): each record of a declared flag kind
+   * that names this member, with its value per environment and the work item
+   * it hides. Sorted by id. `[]` when none names it, null when the flag
+   * records could not be read. Called `featureFlags` because a release
+   * record's `flags` already means something else. Added in contract 1 by
+   * chant 0.124.29.
+   */
+  featureFlags: StatusFeatureFlag[] | null;
+}
+
+/** One feature flag of a member (#4024), as `status --json` lists it. */
+export interface StatusFeatureFlag {
+  /** The flag's name, its record's id. */
+  id: string;
+  /** The build parameter of the member the flag sets. */
+  param: string;
+  owner: string;
+  /** The value per environment, as the record writes it. An environment it leaves out builds with the parameter's default. */
+  values: Record<string, FlagValue>;
+  /** The work item the flag hides, with its state (null when no record has it), or null when the record names none. */
+  work: WorkLink | null;
+  /** Each decision the work item implements, with its state and whether it is confirmed. */
+  implements: FlagDecision[];
+  /** True when every decision the work item implements is confirmed: the flag is due for removal (check WSP118). */
+  stale: boolean;
+  /** The kind file and the record file, from the workspace root. */
+  kind: string;
+  path: string;
 }
 
 /** One cut of a member's release (#4031), as `status --json` lists it. */
@@ -328,6 +394,14 @@ export type StatusDocument =
       acceptance: StatusAcceptance[];
       /** How far each ref the box's replicate policy names is from its remote (#3172), read locally; null when no box declares one. */
       replication: ReplicationState | null;
+      /**
+       * Overlap between in-flight work items (#4025): pairs of items whose
+       * linked commits touch the same files, or that both reach one entry of
+       * a change set a pending or approved gate binds. A report, never a
+       * lock. Null when no work kind is declared or the work records or
+       * history can't be read. Added in contract 1 by chant 0.124.29.
+       */
+      overlap: OverlapReport | null;
       summary: { members: number; released: number; unreadable: number; differing: number | null };
     }
   | {
@@ -346,6 +420,8 @@ export interface StatusQuery {
   compareTo?: string;
   /** Reads one ledger; the lifecycle reader unless a test swaps it. */
   readLedger?: LedgerReader;
+  /** Reads the deploy outcomes beside one ledger (#4035), given the ledger's path; the lifecycle reader unless a test swaps it. */
+  readOutcomes?: OutcomeReader;
   /** Reads one member's gate ledger directory; git unless a test swaps it. */
   readGates?: GateLedgerReader;
   /** The instant a gate's expiry is measured against; now by default. */
@@ -448,7 +524,27 @@ async function shipView(member: Member, cwd: string, read: LedgerReader): Promis
 
 const defaultReader: LedgerReader = (path, cwd) => readReleaseLedger(path.slice(0, -"/releases.jsonl".length), { cwd });
 
-async function readEnvironment(member: Member, env: string, cwd: string, read: LedgerReader): Promise<StatusEnvironment> {
+/** Reads the deploy outcomes (#4035) in the directory of the ledger at `path`. */
+type OutcomeReader = (path: string, cwd: string) => Promise<DeployOutcome[]>;
+
+const defaultOutcomeReader: OutcomeReader = (path, cwd) => readDeployOutcomes(path.slice(0, -"/releases.jsonl".length), { cwd }).catch(() => []);
+
+/** A release digest's revocation, for one member, or null (#4033). */
+type RevokedOf = (releaseDigest: string) => Promise<RevokedRelease | null>;
+
+/** The per-component rollback line, for a component an environment runs from a revoked release when no earlier release can be named (#4033). */
+export function rollbackLine(env: string, component: string): string {
+  return `chant components rollback ${env} --component ${component}`;
+}
+
+async function readEnvironment(
+  member: Member,
+  env: string,
+  cwd: string,
+  read: LedgerReader,
+  revokedOf: RevokedOf = async () => null,
+  readOutcomes: OutcomeReader = defaultOutcomeReader,
+): Promise<StatusEnvironment> {
   const ledger = await ledgerFor(member, env, cwd);
   let records: ReleaseRecord[];
   let malformed: number;
@@ -470,6 +566,37 @@ async function readEnvironment(member: Member, env: string, cwd: string, read: L
   // member (see plan-ledger.ts's readReleasePlan doc).
   const planPrefix = ledger.layout === "members" ? `${MEMBERS_DIR}/${member.name}/` : "";
   const latest = [...latestPerComponent(records).values()].sort((a, b) => (a.component < b.component ? -1 : a.component > b.component ? 1 : 0));
+  // #4043: a release item names the label of the release it was deployed from.
+  const memberDir = resolve(cwd, member.dir);
+  let labels = new Map<string, string>();
+  let labelsRead = false;
+  const readLabels = async (): Promise<Map<string, string>> => {
+    if (labelsRead) return labels;
+    labelsRead = true;
+    try {
+      const { readCuts, labelsByDigest } = await import("../lifecycle/release-store");
+      labels = labelsByDigest((await readCuts({ cwd: memberDir })).cuts);
+    } catch {
+      // The label is a convenience; the digest is the join key.
+    }
+    return labels;
+  };
+  if (latest.some((r) => r.releaseDigest !== undefined)) await readLabels();
+  // #4035: whether a release a rollback could go back to is kept and not revoked.
+  const checks = new Map<string, Promise<ReleaseCheck>>();
+  const check = (digest: string): Promise<ReleaseCheck> => {
+    let found = checks.get(digest);
+    if (!found) {
+      found = (async () => {
+        const { readRelease } = await import("../lifecycle/release-store");
+        const kept = (await readRelease(digest, { cwd: memberDir }).catch(() => null)) !== null;
+        return { kept, revoked: kept && (await revokedOf(digest)) !== null };
+      })();
+      checks.set(digest, found);
+    }
+    return found;
+  };
+  const back = { records, check, label: async (digest: string) => (await readLabels()).get(digest) };
   const releases: StatusRelease[] = await Promise.all(
     latest.map(async (r) => ({
       component: r.component,
@@ -481,10 +608,14 @@ async function readEnvironment(member: Member, env: string, cwd: string, read: L
       actor: r.actor,
       approver: r.approver ?? null,
       admission: r.admission ? { op: r.admission.op, gate: r.admission.gate, resolvedAt: r.admission.resolvedAt } : null,
+      releaseDigest: r.releaseDigest ?? null,
+      releaseLabel: (r.releaseDigest !== undefined ? labels.get(r.releaseDigest) : undefined) ?? null,
       flags: [...(r.flags ?? [])],
       plan: await readReleasePlan(r.digest, { cwd, prefix: planPrefix }),
+      ...(await revokedItem(r, env, revokedOf, back)),
     })),
   );
+  const mixed = await mixedEnvironment({ env, records, outcomes: await readOutcomes(ledger.path, cwd), label: back.label, check });
   return {
     env,
     ledger: { ...ledger, shared: false },
@@ -493,9 +624,47 @@ async function readEnvironment(member: Member, env: string, cwd: string, read: L
       malformed > 0
         ? { code: "ledger-malformed", message: `${ledger.path}: ${malformed} line${malformed === 1 ? " is" : "s are"} not a release record and ${malformed === 1 ? "was" : "were"} skipped` }
         : null,
+    ...(mixed ? { mixed } : {}),
   };
 }
 
+/**
+ * `{ revoked }` when the record names a release cut from a revoked commit
+ * (#4033), else nothing. Its rollback line names the newest release the
+ * environment ran before this one that is kept and not revoked (#4035).
+ */
+async function revokedItem(
+  r: ReleaseRecord,
+  env: string,
+  revokedOf: RevokedOf,
+  back: { records: readonly ReleaseRecord[]; check: (digest: string) => Promise<ReleaseCheck>; label: (digest: string) => Promise<string | undefined> },
+): Promise<{ revoked?: StatusRevokedRelease }> {
+  if (r.releaseDigest === undefined) return {};
+  const revoked = await revokedOf(r.releaseDigest);
+  if (!revoked) return {};
+  const target = await rollbackTarget({ records: back.records, exclude: new Set([r.releaseDigest]), before: r.timestamp, check: back.check });
+  const rollback = target ? releaseRollbackLine(env, target, await back.label(target)) : rollbackLine(env, r.component);
+  return { revoked: { ...revoked, rollback } };
+}
+
+/**
+ * A release gate whose release was cut from a revoked commit is superseded
+ * (#4033): `chant approve` refuses it and the promote refuses the release, so
+ * neither an approval nor a pending fact will pass it. An expired gate stays
+ * expired. The gate carries the revocation.
+ */
+async function supersedeRevokedGates(gates: StatusGate[], revokedOf: RevokedOf): Promise<StatusGate[]> {
+  return Promise.all(
+    gates.map(async (g) => {
+      if (g.releaseDigest === undefined) return g;
+      const revoked = await revokedOf(g.releaseDigest);
+      if (!revoked) return g;
+      const { releaseDigest: _d, label: _l, ...revocation } = revoked;
+      return { ...g, state: g.state === "expired" ? g.state : "superseded", revoked: revocation };
+    }),
+  );
+}
+
 /** The digest two environments are compared on: the input side when there is one. */
 const compareKey = (r: StatusRelease): string => r.inputDigest ?? r.digest;
 
@@ -545,10 +714,17 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
     const ruleSource = scopeSource(found.dir);
     const rules = (gate: string) => gateAdmissionFrom(ruleSource, gate);
     const releaseRule = releaseRuleFrom(ruleSource).rule;
+    // #4033 (ws-105): revoked commits, read from local tags once and only when a release is met.
+    // Tags that can't be judged read as none revoked; workspace check reports the declaration.
+    let revokedCommits: Promise<ReadonlyMap<string, ReleaseRevocation>> | undefined;
+    const revoked = () => (revokedCommits ??= revokedCommitsAt(top, ruleSource.declaration?.ci?.green ?? null).catch(() => new Map()));
+    // #4024: the flag records, read once for every member. Unreadable records list as null.
+    const flags = await readStatusFlags(declaration, found.dir);
     const members: StatusMember[] = [];
     for (const m of declaration.members) {
+      const revokedOf = revokedReleaseLookup(resolve(found.dir, m.dir), revoked);
       const environments: StatusEnvironment[] = [];
-      for (const env of envs) environments.push(await readEnvironment(m, env, found.dir, read));
+      for (const env of envs) environments.push(await readEnvironment(m, env, found.dir, read, revokedOf, query.readOutcomes));
       const own = await hasMemberLedger(m, found.dir);
       const gates = await readMemberGates(own ? `${MEMBERS_DIR}/${m.name}/${GATES_DIR}` : GATES_DIR, own ? "members" : "flat", commit, envs, found.dir, now, query.readGates, rules);
       const stewards = await (query.readStewards ?? readMemberStewards)(resolve(found.dir, m.dir), query.env, now, m.kind, m.box);
@@ -565,7 +741,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
         compare: query.compareTo === undefined ? null : compareEnvironments(environments[0], environments[environments.length - 1]),
         readable: environments.every((e) => e.reason === null),
         gateLedger: gates.ledger,
-        gates: gates.gates,
+        gates: await supersedeRevokedGates(gates.gates, revokedOf),
         box:
           m.box === null
             ? null
@@ -594,6 +770,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
         stewardReasons: stewards.reasons,
         promotionOrder: await (query.readPromotionOrder ?? readMemberPromotionOrder)(resolve(found.dir, m.dir)),
         releaseCuts: await readReleaseCuts(resolve(found.dir, m.dir), releaseRule),
+        featureFlags: flags === null ? null : flags.filter((f) => f.member === m.name).map(({ member: _member, ...f }) => f),
         ...x(m.pointer),
       });
     }
@@ -606,6 +783,16 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
 
     const leases = await readWorkspaceLeases(declaration.members, found.dir, new Date(now));
     const acceptance = await readWorkspaceAcceptance(declaration, found.dir);
+    // #4025: the change sets still waiting to apply, the ones a pending or approved gate binds.
+    const pendingChangeSets: OverlapChangeSetRef[] = [];
+    for (const m of members) {
+      const own = m.gateLedger.layout === "members";
+      for (const g of m.gates) {
+        if (g.changeSet === undefined || (g.state !== "pending" && g.state !== "approved")) continue;
+        pendingChangeSets.push({ digest: g.changeSet, cwd: resolve(found.dir, m.dir), ledgerMember: own ? m.name : null, gitSha: g.gitSha ?? null });
+      }
+    }
+    const overlap = await readStatusOverlap(declaration, found.dir, top, pendingChangeSets);
 
     return {
       ...head,
@@ -619,6 +806,7 @@ export async function workspaceStatus(query: StatusQuery): Promise<StatusDocumen
       leases,
       acceptance,
       replication: replicationOf(declaration, top),
+      overlap,
       summary: {
         members: members.length,
         released: members.filter((m) => m.environments[0].releases.length > 0).length,
@@ -680,6 +868,31 @@ async function readWorkspaceLeases(members: Member[], cwd: string, now: Date): P
   return out;
 }
 
+/** Every flag of the declared flag kinds (#4024), read in the working tree, sorted by id; null when they can't be read. */
+async function readStatusFlags(declaration: Declaration, root: string): Promise<Array<StatusFeatureFlag & { member: string }> | null> {
+  if (declaredRecordKinds(declaration).length === 0) return [];
+  try {
+    const { readWorkspaceFlags } = await import("./flags-read");
+    const { flags } = await readWorkspaceFlags(root);
+    return flags
+      .map((f) => ({ id: f.id, member: f.member, param: f.param, owner: f.owner, values: f.values, work: f.work, implements: f.implements, stale: f.stale, kind: f.kind, path: f.path }))
+      .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  } catch {
+    return null;
+  }
+}
+
+/** The overlap report (#4025); null when no work kind is declared or it can't be read. */
+async function readStatusOverlap(declaration: Declaration, root: string, top: string, changeSets: OverlapChangeSetRef[]): Promise<OverlapReport | null> {
+  if (declaredRecordKinds(declaration).length === 0) return null;
+  try {
+    const { readOverlap } = await import("./overlap");
+    return await readOverlap({ declaration, root, top, changeSets });
+  } catch {
+    return null;
+  }
+}
+
 /** The acceptance counts of every declared work kind with criteria (#2772), read in the working tree. */
 async function readWorkspaceAcceptance(declaration: Declaration, root: string): Promise<StatusAcceptance[]> {
   if (declaredRecordKinds(declaration).length === 0) return [];
@@ -765,6 +978,22 @@ export function formatStatus(doc: Extract<StatusDocument, { members: unknown }>)
       for (const e of m.environments) {
         if (e.reason) memberNotes.push(`  ${e.reason.code}: ${e.reason.message}`);
         else if (e.ledger.shared && e.releases.length > 0) memberNotes.push(`  ${e.env} is read from the shared flat ledger ${e.ledger.path}`);
+        // #4033: a component running a release cut from a revoked commit, and the way back.
+        for (const r of e.releases) {
+          if (!r.revoked) continue;
+          const name = r.revoked.label ?? r.revoked.releaseDigest;
+          memberNotes.push(`  ${e.env}: ${r.component} runs release ${name}, revoked by ${r.revoked.tag} (${describeRevocation(r.revoked)}); roll back: ${r.revoked.rollback}`);
+        }
+        // #4035: an environment running a mix, what each component runs, and the lines that settle it.
+        if (e.mixed) {
+          const what = e.mixed.components.map((c) => {
+            const runs = c.releaseDigest ? `release ${c.releaseLabel ?? c.releaseDigest.slice(0, 24)}` : c.digest ? "no release" : "nothing recorded";
+            return c.state === "settled" ? `${c.component} runs ${runs}` : `${c.component} ${c.state} (${c.attempt!.verb} ${c.attempt!.runId}), recorded ${runs}`;
+          });
+          memberNotes.push(`  ${e.env} is mixed: ${what.join("; ")}`);
+          for (const line of e.mixed.redeploy) memberNotes.push(`    redeploy: ${line}`);
+          if (e.mixed.rollback) memberNotes.push(`    roll back: ${e.mixed.rollback}`);
+        }
       }
       if (memberNotes.length > 0) notes.set(rows.length - 1, memberNotes);
     }
@@ -794,6 +1023,28 @@ export function formatStatus(doc: Extract<StatusDocument, { members: unknown }>)
     }
     lines.push(...table(rows));
   }
+  const flagged = doc.members.filter((m) => (m.featureFlags ?? []).length > 0);
+  if (flagged.length > 0) {
+    lines.push("");
+    const rows: string[][] = [["FLAG", "PARAM", doc.env.toUpperCase(), "WORK ITEM", ""]];
+    for (const m of flagged) {
+      for (const f of m.featureFlags!) {
+        const value = f.values[doc.env];
+        rows.push([`${m.name}/${f.id}`, f.param, value === undefined ? "default" : JSON.stringify(value), f.work ? `${f.work.id} (${f.work.state ?? "unknown"})` : "-", f.stale ? "due for removal" : ""]);
+      }
+    }
+    lines.push(...table(rows));
+  }
+  // #4025: in-flight work items that changed the same thing.
+  if (doc.overlap && doc.overlap.pairs.length > 0) {
+    lines.push("");
+    const rows: string[][] = [["OVERLAP", "FILES", "ADDRESSES"]];
+    for (const p of doc.overlap.pairs) {
+      const list = (xs: string[]) => (xs.length === 0 ? "-" : xs.length <= 2 ? xs.join(", ") : `${xs.slice(0, 2).join(", ")} and ${xs.length - 2} more`);
+      rows.push([`${p.items[0]} and ${p.items[1]}`, list(p.files), list([...new Set(p.addresses.map((x) => x.node ?? x.address))])]);
+    }
+    lines.push(...table(rows));
+  }
   const boxes = doc.members.filter((m) => m.box?.isolation);
   if (boxes.length > 0) {
     lines.push("");

package/src/workspace/wip.ts

@@ -38,7 +38,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { copyFileSync, existsSync, lstatSync, mkdtempSync, rmSync, unlinkSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, rmSync, statSync, unlinkSync, utimesSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { KEPT_REF_PREFIX } from "../lifecycle/work-lease";
@@ -348,7 +348,16 @@ function worktreeTree(top: string): string {
     const index = join(dir, "index");
     // Start from the checkout's index so git reuses its stat data; the original is never written.
     const own = out(top, ["rev-parse", "--git-path", "index"]);
-    if (own && existsSync(resolve(top, own))) copyFileSync(resolve(top, own), index);
+    if (own && existsSync(resolve(top, own))) {
+      const source = resolve(top, own);
+      copyFileSync(source, index);
+      // Keep the index's own timestamps on the copy. git treats an entry whose
+      // file is as new as the index as racily clean and reads its content; a
+      // copy stamped now would make a same-size edit made in the same second as
+      // the last index write look unchanged, and the snapshot would miss it.
+      const { atime, mtime } = statSync(source);
+      utimesSync(index, atime, mtime);
+    }
     const env = { GIT_INDEX_FILE: index };
     const add = git(top, ["add", "--all", "--", ":/"], { env });
     if (!add.ok) throw new Error(`wip: git add into a temporary index failed: ${add.stderr.trim()}`);