@intentius/chant 0.124.46 → 0.124.49

package/src/workspace/promote.ts

@@ -0,0 +1,302 @@
+/**
+ * `chant workspace promote <member>` (#3178): move one member one rung up the
+ * kind ladder, `other` or `terraform`, then `choudoufu`, then `chant`.
+ *
+ * The change is staged the way `workspace upgrade` stages one (#2550): in a
+ * git worktree at HEAD, so the tree is never touched until the gate passes.
+ * The gate is `workspace-promote/<member>` on the gate ledger and binds the
+ * digest of the patch the staging produced. The first run records a pending
+ * fact and exits 3. After `chant approve workspace-promote <member>`, the same
+ * command stages again, finds the approval for the same digest, applies the
+ * patch, and runs the rung's follow-up (for `choudoufu`, stamping the
+ * ownership markers with `live-import -approve`).
+ *
+ * Rungs:
+ *
+ * - `terraform` to `choudoufu`: `choudoufu live-check` in the member's
+ *   directory must pass, then `choudoufu live-import -state=<--state>
+ *   -estate=<member>` prints its ratification report (read-only: it stamps
+ *   nothing without `-approve`). The patch changes the member's kind.
+ * - `choudoufu` or `other` to `chant`: `chant import` writes TypeScript into
+ *   the member's directory. The patch holds those files and the kind change.
+ *
+ * Commands run through an injectable runner, so a test never starts a binary.
+ */
+
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { computePlanDigest } from "../lifecycle/plan-digest";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note";
+import { approveCommand, describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { WORKSPACE_PROMOTE_GATE_OP } from "../op/gate-name";
+import { DECLARATION_FILES, readDeclaration } from "./declaration";
+import { setProperty } from "./json-edit";
+import { workingTree } from "./tree";
+
+export const PROMOTE_PLAN_KIND = "workspace-promote";
+export const PROMOTE_GATED_EXIT = 3;
+const USAGE = "chant workspace promote <member> [--state <terraform.tfstate>] [--lexicon <lexicon>] [--dry-run] [--output <patch file>] [--json]";
+
+export class PromoteError extends Error {}
+
+/** The ladder, lowest rung first. `other` and `terraform` share the bottom rung. */
+export const LADDER = ["terraform", "choudoufu", "chant"] as const;
+
+export interface Rung {
+  from: string;
+  to: "choudoufu" | "chant";
+}
+
+/** The next rung for a member of `kind`, or undefined at the top or off the ladder. */
+export function nextRung(kind: string): Rung | undefined {
+  if (kind === "terraform") return { from: kind, to: "choudoufu" };
+  if (kind === "choudoufu" || kind === "other") return { from: kind, to: "chant" };
+  return undefined;
+}
+
+export interface CommandRun {
+  label: string;
+  argv: string[];
+  /** Directory relative to the project root. */
+  cwd: string;
+}
+export type PromoteRunner = (argv: string[], cwd: string) => Promise<{ exitCode: number; output: string }>;
+
+export const spawnRunner: PromoteRunner = (argv, cwd) =>
+  new Promise((done) => {
+    const [bin, ...rest] = argv;
+    const child = spawn(bin, rest, { cwd, stdio: ["ignore", "pipe", "pipe"], env: process.env });
+    const out: Buffer[] = [];
+    child.stdout.on("data", (c: Buffer) => out.push(c));
+    child.stderr.on("data", (c: Buffer) => out.push(c));
+    child.on("error", (e) => done({ exitCode: 127, output: String(e.message) }));
+    child.on("close", (code) => done({ exitCode: code ?? 1, output: Buffer.concat(out).toString("utf-8") }));
+  });
+
+/** The commands the rung runs in the staging worktree. */
+export function stagingRuns(rung: Rung, member: { name: string; dir: string }, opts: { state?: string; lexicon?: string }): CommandRun[] {
+  if (rung.to === "choudoufu") {
+    if (!opts.state) throw new PromoteError(`promoting ${member.name} to choudoufu reads its state for the adoption report: pass --state <terraform.tfstate>`);
+    return [
+      { label: "choudoufu live-check", argv: ["choudoufu", "live-check"], cwd: member.dir },
+      { label: "choudoufu live-import (report)", argv: ["choudoufu", "live-import", `-state=${opts.state}`, `-estate=${member.name}`], cwd: member.dir },
+    ];
+  }
+  const lexicon = opts.lexicon ?? (rung.from === "choudoufu" ? "terraform" : undefined);
+  if (!lexicon) throw new PromoteError(`promoting ${member.name} (kind other) to chant needs --lexicon <lexicon>: what chant import should read it as`);
+  return [{ label: "chant import", argv: ["chant", "import", ".", "--lexicon", lexicon, "--output", "src/"], cwd: member.dir }];
+}
+
+/** After the approved patch is applied: stamping ownership markers on the live resources. */
+export function followUpRuns(rung: Rung, member: { name: string; dir: string }, opts: { state?: string }): CommandRun[] {
+  if (rung.to !== "choudoufu") return [];
+  return [{ label: "choudoufu live-import -approve", argv: ["choudoufu", "live-import", `-state=${opts.state}`, `-estate=${member.name}`, "-approve"], cwd: member.dir }];
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+}
+
+export interface PromoteOptions {
+  root: string;
+  member: string;
+  state?: string;
+  lexicon?: string;
+  dryRun?: boolean;
+  output?: string;
+  json?: boolean;
+  /** For tests. */
+  runner?: PromoteRunner;
+  ledger?: GateLedgerPort;
+  now?: string;
+}
+
+export type PromoteOutcome = "top-of-ladder" | "checks-failed" | "dry-run" | "gated" | "applied";
+export interface PromoteResult {
+  outcome: PromoteOutcome;
+  exitCode: number;
+  member: string;
+  from?: string;
+  to?: string;
+  digest?: string;
+  patch?: string;
+  ran?: { label: string; exitCode: number }[];
+}
+
+function declarationFile(root: string): string {
+  const f = DECLARATION_FILES.find((n) => existsSync(join(root, n)));
+  if (!f) throw new PromoteError(`no ${DECLARATION_FILES.join(" or ")} in ${root}`);
+  return f;
+}
+
+/** Rewrite the member's `kind` in the declaration text. */
+export function setMemberKind(text: string, file: string, member: string, kind: string): string {
+  const raw = (file.endsWith(".jsonc") ? text.replace(/^\s*\/\/.*$/gm, "") : text);
+  const parsed = JSON.parse(raw) as { members?: { name?: string }[] };
+  const i = (parsed.members ?? []).findIndex((m) => m.name === member);
+  if (i < 0) throw new PromoteError(`the declaration has no member "${member}"`);
+  return setProperty(text, file.endsWith(".jsonc"), `/members/${i}`, "kind", kind);
+}
+
+export async function promoteCommand(opts: PromoteOptions): Promise<PromoteResult> {
+  const root = realpathSync(resolve(opts.root));
+  const run = opts.runner ?? spawnRunner;
+  const decl = readDeclaration(workingTree(root));
+  const found = decl.members.find((m) => m.name === opts.member);
+  if (!found) throw new PromoteError(`the declaration has no member "${opts.member}"; chant workspace ls lists them`);
+  const say = (m: string): void => {
+    if (!opts.json) console.error(m);
+  };
+  const rung = nextRung(found.kind);
+  if (!rung) {
+    say(formatInfo(`${found.name} is kind ${found.kind}, which has no rung above it on the ladder (terraform or other, choudoufu, chant)`));
+    return { outcome: "top-of-ladder", exitCode: 0, member: found.name, from: found.kind };
+  }
+  const member = { name: found.name, dir: found.dir === "." ? "" : found.dir };
+  const staging = stagingRuns(rung, member, opts);
+
+  let repo: string;
+  let head: string;
+  try {
+    repo = git(root, ["rev-parse", "--show-toplevel"]).trim();
+    head = git(root, ["rev-parse", "HEAD"]).trim();
+  } catch {
+    throw new PromoteError("chant workspace promote stages its change in a git worktree, so the project must be in a git repository with at least one commit");
+  }
+  const projectRel = relative(repo, root).split(sep).join("/");
+  const declFile = declarationFile(root);
+  const watched = [declFile, member.dir].filter(Boolean).map((p) => [projectRel, p].filter(Boolean).join("/"));
+  const dirty = git(repo, ["status", "--porcelain", "--untracked-files=all", "--", ...watched]).split("\n").filter(Boolean);
+  if (dirty.length > 0) {
+    throw new PromoteError(`${found.name} has uncommitted changes (${dirty.slice(0, 5).map((l) => l.slice(3)).join(", ")}). Commit them: promote stages from HEAD and applies its patch to the tree.`);
+  }
+
+  const holder = mkdtempSync(join(tmpdir(), "chant-promote-"));
+  const worktree = join(holder, "wt");
+  const dispose = (): void => {
+    try {
+      git(repo, ["worktree", "remove", "--force", worktree]);
+    } catch {
+      // Fall through to the directory removal and a prune.
+    }
+    rmSync(holder, { recursive: true, force: true });
+    try {
+      git(repo, ["worktree", "prune"]);
+    } catch {
+      // Nothing to prune.
+    }
+  };
+
+  try {
+    git(repo, ["worktree", "add", "-q", "--detach", worktree, head]);
+    const project = projectRel ? join(worktree, projectRel) : worktree;
+    const ran: { label: string; exitCode: number }[] = [];
+    for (const step of staging) {
+      const cwd = join(project, step.cwd);
+      mkdirSync(cwd, { recursive: true });
+      const result = await run(step.argv, cwd);
+      ran.push({ label: step.label, exitCode: result.exitCode });
+      if (!opts.json) say(formatInfo(`${step.label}: exit ${result.exitCode}`));
+      if (result.exitCode !== 0) {
+        say(formatError({ message: `${step.label} failed in the staging worktree`, hint: result.output.trimEnd().split("\n").slice(-20).join("\n") }));
+        say(formatError({ message: "the promotion was not gated: its checks must pass first. The tree is unchanged." }));
+        if (opts.json) console.log(JSON.stringify({ outcome: "checks-failed", member: found.name, ran }, null, 2));
+        return { outcome: "checks-failed", exitCode: 1, member: found.name, from: rung.from, to: rung.to, ran };
+      }
+    }
+    const declPath = join(project, declFile);
+    writeFileSync(declPath, setMemberKind(readFileSync(declPath, "utf-8"), declFile, found.name, rung.to));
+    git(worktree, ["add", "-A"]);
+    const patch = git(worktree, ["diff", "--cached", "--binary", "HEAD"]);
+    const digest = computePlanDigest(PROMOTE_PLAN_KIND, { member: found.name, from: rung.from, to: rung.to, patch });
+    const base: PromoteResult = { outcome: "dry-run", exitCode: 0, member: found.name, from: rung.from, to: rung.to, digest, patch, ran };
+    const report = (outcome: PromoteOutcome, exitCode: number, extra: Record<string, unknown> = {}): PromoteResult => {
+      if (opts.json) console.log(JSON.stringify({ outcome, member: found.name, from: rung.from, to: rung.to, digest, ran, ...extra }, null, 2));
+      return { ...base, outcome, exitCode };
+    };
+    say(formatInfo(`${found.name}: ${rung.from} to ${rung.to}, patch ${digest}`));
+    if (opts.output) writeFileSync(resolve(opts.output), patch);
+    if (opts.dryRun) {
+      say(formatInfo("--dry-run: staged and checked; no gate recorded, the tree is unchanged"));
+      return report("dry-run", 0);
+    }
+
+    const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: repo }), {
+      op: WORKSPACE_PROMOTE_GATE_OP,
+      gate: found.name,
+      description: `promote ${found.name} from ${rung.from} to ${rung.to}`,
+      planDigest: digest,
+      ...(opts.now ? { now: opts.now } : {}),
+    });
+    if (!check.satisfied) {
+      if (!opts.json) {
+        const sealed = await gateIsSealed(found.name);
+        if (check.mismatch) console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_PROMOTE_GATE_OP, found.name, check.mismatch, sealed) }));
+        if (isLifecycleLocalNote(check.pushWarning)) console.error(formatInfo(LIFECYCLE_LOCAL_NOTE));
+        else if (check.pushWarning) console.error(formatWarning({ message: check.pushWarning }));
+        console.error(
+          formatInfo(
+            `Gated: the patch ${digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_PROMOTE_GATE_OP, found.name, undefined, undefined, sealed)}\` and repeat this command to apply it.`,
+          ),
+        );
+      }
+      return report("gated", PROMOTE_GATED_EXIT, { pending: check.pending });
+    }
+
+    const patchDir = mkdtempSync(join(tmpdir(), "chant-promote-patch-"));
+    try {
+      const file = join(patchDir, "promote.patch");
+      writeFileSync(file, patch);
+      try {
+        git(repo, ["apply", "--binary", "--whitespace=nowarn", file]);
+      } catch (err) {
+        const stderr = (err as { stderr?: Buffer | string }).stderr?.toString().trim();
+        throw new PromoteError(`the approved patch no longer applies to the tree${stderr ? `: ${stderr}` : ""}`);
+      }
+    } finally {
+      rmSync(patchDir, { recursive: true, force: true });
+    }
+    for (const step of followUpRuns(rung, member, opts)) {
+      const result = await run(step.argv, join(root, step.cwd));
+      ran.push({ label: step.label, exitCode: result.exitCode });
+      if (result.exitCode !== 0) {
+        say(formatError({ message: `${step.label} failed after the patch was applied`, hint: result.output.trimEnd().split("\n").slice(-20).join("\n") }));
+        return report("applied", 1, { followUpFailed: step.label });
+      }
+    }
+    say(formatSuccess(`applied the approved promotion of "${found.name}" to ${rung.to} (${digest}). Review and commit it.`));
+    return report("applied", 0);
+  } finally {
+    dispose();
+  }
+}
+
+export async function runWorkspacePromote(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (!args.extraPositional || args.extraPositional2) {
+    console.error(formatError({ message: "promote takes exactly one member", hint: USAGE }));
+    return 1;
+  }
+  try {
+    const result = await promoteCommand({
+      root: process.cwd(),
+      member: args.extraPositional,
+      state: args.statePath,
+      lexicon: args.lexicon,
+      dryRun: args.dryRun,
+      output: args.output,
+      json: args.json,
+    });
+    return result.exitCode;
+  } catch (err) {
+    if (err instanceof PromoteError) {
+      console.error(formatError({ message: err.message, hint: USAGE }));
+      return 1;
+    }
+    throw err;
+  }
+}

package/src/workspace/reason-codes.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, test } from "vitest";
 import { REPO } from "./__fixtures__/contract-repo";
 import { CHANGES_ERROR_CODES, CHANGES_FINDING_CODES, COMMIT_LINK_FINDING_CODES } from "./changes";
 import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
-import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
+import { COMPOSITES_ENVIRONMENT_REASON_CODES, COMPOSITES_ERROR_CODES, COMPOSITES_EXECUTOR_REASON_CODES, COMPOSITES_REASON_CODES, COMPOSITES_RUNTIME_REASON_CODES } from "./composites";
 import { WORKSPACE_ERROR_CODES } from "./declaration";
 import { GRAPH_ERROR_CODES } from "./graph-cli";
 import { INTENT_ERROR_CODES, INTENT_FINDING_CODES, INTENT_REASON_CODES, INTENT_WHY_CODES } from "./intent";
@@ -30,9 +30,12 @@ import { BOX_FINDING_CODES } from "./checks/boxes";
 import { DIAGRAM_FINDING_CODES } from "./checks/diagrams";
 import { SECURITY_FINDING_CODES } from "./checks/security";
 import { CI_WORKFLOW_FINDING_CODES } from "./ci-workflow";
+import { CI_BRANCH_FINDING_CODES } from "./checks/ci-branch";
+import { GATE_APPROVAL_FINDING_CODES } from "./checks/gate-approval";
 import { WORK_ERROR_CODES, WORK_HISTORY_ERROR_CODES, WORK_LEASE_REFUSALS } from "./work-cli";
 import { RUN_STATEMENT_ERROR_CODES, RUNS_ERROR_CODES, RUNS_REASON_CODES, RUNS_WRITE_ERROR_CODES } from "./runs-cli";
 import { RUN_STATEMENT_FAILURE_CODES } from "./trust/run-statement";
+import { LEDGER_READ_ERROR_CODES } from "../lifecycle/ledger-read";
 import { WORK_EVIDENCE_ERROR_CODES } from "./work-evidence";
 import { RECORD_FINDING_CODES } from "./checks/records";
 import { ANSWER_WARNING_CODES } from "./points";
@@ -49,6 +52,7 @@ import { DECLARATION_WRITE_ERROR_CODES } from "./declaration-write";
 import { TRUST_WRITE_ERROR_CODES } from "./trust/trust-write";
 import { BOX_PUBLISH_ERROR_CODES } from "./box-publish";
 import { WRITE_LOCK_ERROR_CODES } from "./write-lock-cli";
+import { EXIT_CODES } from "./exit";
 import { WIP_ERROR_CODES, WIP_WRITE_ERROR_CODES } from "./wip";
 import { CI_GREEN_ERROR_CODES } from "./ci-green";
 import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
@@ -72,6 +76,8 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   DIAGRAM_FINDING_CODES,
   SECURITY_FINDING_CODES,
   CI_WORKFLOW_FINDING_CODES,
+  CI_BRANCH_FINDING_CODES,
+  GATE_APPROVAL_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,
@@ -100,6 +106,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   COMPOSITES_REASON_CODES,
   COMPOSITES_RUNTIME_REASON_CODES,
   COMPOSITES_ENVIRONMENT_REASON_CODES,
+  COMPOSITES_EXECUTOR_REASON_CODES,
   WORK_ERROR_CODES,
   WORK_HISTORY_ERROR_CODES,
   WORK_LEASE_REFUSALS,
@@ -108,6 +115,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   RUNS_WRITE_ERROR_CODES,
   RUN_STATEMENT_ERROR_CODES,
   RUN_STATEMENT_FAILURE_CODES,
+  LEDGER_READ_ERROR_CODES,
   WORK_EVIDENCE_ERROR_CODES,
   RECORD_FINDING_CODES,
   FLAG_WARNING_CODES,
@@ -139,6 +147,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   SEARCH_MEMBER_REASON_CODES,
   CAPABILITIES_ERROR_CODES,
   CAPABILITY_SUPPORT_CODES,
+  EXIT_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

package/src/workspace/reason-codes.ts

@@ -66,6 +66,9 @@ export const REASONS = {
   // A ledger status can't fully read.
   "ledger-unreadable": "Reading the ledger failed, so nothing from it is listed.",
   "ledger-malformed": "Some lines of the ledger aren't release records; the rest are listed.",
+  // chant ledger (#4363): a read that can't start.
+  "filter-invalid": "A --where or --since names a field the read doesn't have, an operator its type doesn't take, or a value not of its type; nothing was read.",
+  "table-unknown": "chant ledger was given a table that is not one of resources, snapshots, runs, gates, deploys, releases or cuts.",
   // A member's gates status can't list (status, #2674).
   "gates-no-ledger": "The checkout has no chant/lifecycle branch, so there is no gate ledger to read.",
   "gates-no-gate-ledger": "The branch has no gate ledger for the member: no run of it has reached a gate.",
@@ -237,6 +240,9 @@ export const REASONS = {
   "environments-ledger-undeclared": "The member's ledger has releases in an environment its config's environments don't cover, so chant run --env would refuse it and it is not listed.",
   "environments-ledger-unreadable": "The chant/lifecycle branch exists and the member's ledger environments could not be listed.",
   "environments-component-undeclared": "A component declares an environment its member's chant.config.ts environments don't cover, so chant run --env would refuse it and it is not listed (#3153).",
+  // The forge workflow that deploys an environment (graph --composites, #4402): an environment row's executor.reason.
+  "executor-none-declared": "The member's chant.config.ts declares no executor for the environment, so nothing names the forge workflow that deploys it.",
+  "executor-config-unreadable": "The member's chant.config.ts could not be read, so whether a forge workflow deploys the environment is unknown.",
   // A declared diagram's source or render (check, #2764). Each is also a WSP finding.
   "diagram-source-missing": "A declared diagram's source file does not exist in the tree read.",
   "diagram-render-missing": "A declared diagram's render file does not exist in the tree read.",
@@ -269,6 +275,8 @@ export const REASONS = {
   "ci-workflow-pipeline-missing": "Under ci.workflow, no pipeline file runs the plan job, the merge job or chant ci tick.",
   "ci-workflow-pipeline-differs": "Under ci.workflow, the pipeline does not match the workflow: it applies on merge under trunk-curated, records under trunk-curated+apply-on-merge, or applies before merge, or fails to, against apply-before-merge.",
   "ci-workflow-publish-missing": "Under ci.workflow, no pipeline file runs chant release publish.",
+  "gate-approval-unbased": "An Op gate's approval block sets a quorum, policy, mode or context that identity.gates does not set at base, so the change being run can edit it.",
+  "ci-branch-route-differs": "A member's generated pull-request pipeline targets a branch other than the one ci.branches routes the member to.",
   // A box that holds a credential (check, #2726). Each is also a WSP finding.
   "box-credential-declared": "A file in a box member's directory carries a literal secret: a credential's shape, or a literal where a credential goes. A variable or secret-manager reference is not one.",
   "box-capability-unbrokered": "A capability in a member's box block names no broker, so the box would hold its credential.",
@@ -291,6 +299,10 @@ export const REASONS = {
   "lease-held": "Someone holds a live lease on the work item: another worker, or, for a claim, the same one.",
   "lease-not-held": "Nobody holds a live lease on the work item: it expired, was released or was never claimed.",
   "lease-token-mismatch": "The live lease on the work item carries another fencing token than the one given.",
+  // Evidence that cites an ops result (work evidence, #3171): why the citation was refused. Nothing is written.
+  "work-evidence-ops-missing": "Work evidence cites a run, deploy, gate answer or release plan the local chant/lifecycle branch does not hold.",
+  "work-evidence-ops-mismatch": "Work evidence cites an ops record that does not hash to the sha256 given, or a run whose outcome disagrees with the evidence's result.",
+  "work-evidence-ops-unfinished": "Work evidence cites a run that is still gated or waiting, so it has no outcome to show.",
   "lease-race": "Another writer changed the lease between this command's read and its write.",
   "lease-push-rejected": "The remote refused the lease push: another clone claimed the item first, or the remote could not be reached.",
   // The agent run record (chant workspace runs, #3033): why a write was refused, and what a read could not see. Nothing is written on a refusal.
@@ -365,6 +377,19 @@ export const REASONS = {
   // The lineage lock (check).
   "lock-invalid": "The lineage lock can't be read.",
   "manual-step-open": "A scope in the lineage lock has an open manual step.",
+  // workspace exit (#3177): why a member can't be exited, and what the exit drill finds wrong with one that was.
+  "missing-dir": "The chant member's directory does not exist, so there is nothing to build.",
+  "no-lexicon": "No lexicon is named in the member's chant.config.* or package.json, so there is nothing to build.",
+  "lexicon-unsupported": "A lexicon the member uses has no native target in workspace exit.",
+  "exit-failed": "The member's exit did not finish: its build failed, or it was refused.",
+  "choudoufu-steps-missing": "A choudoufu member's exit listed no roundtrip steps.",
+  "native-missing": "A native file the exit wrote is missing or empty.",
+  "native-unreadable": "A native file the exit wrote is not valid JSON, or has no content.",
+  "no-deploy-command": "A native file that can be deployed has no stock deploy command.",
+  "chant-config-left": "A chant.config.* file is still in the exited member.",
+  "chant-dependency": "The member's package.json still has a chant dependency, or a script that calls chant.",
+  "chant-in-ci": "A CI file of the exited member still calls chant.",
+  "declaration-not-other": "The declaration still gives the exited member a kind other than other.",
 } as const;
 
 export type ReasonCode = keyof typeof REASONS;

package/src/workspace/records-cli.ts

@@ -56,6 +56,7 @@ import {
 } from "./records";
 import { readCheckoutHead, worktreeStates, type CheckoutView, type WorktreeState } from "./records-checkout";
 import { lastWriteReader, type LastWrite } from "./write-lock";
+import { FilterError, matchesWhere, parseWhere, type FilterFields, type WhereClause } from "../read-filter";
 
 function readTextOrNull(file: string): string | null {
   try {
@@ -78,7 +79,7 @@ export const RECORDS_CONTRACT_VERSION = 1;
 export const RECORDS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/records/v1/records.schema.json";
 
 const USAGE =
-  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> [--kind <kind file>] | chant workspace records new|amend|review|close (#2670, #2693)";
+  "chant workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--where <field><op><value>]... [--json] | chant workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json] | chant workspace records pin <path> [--kind <kind file>] | chant workspace records new|amend|review|close (#2670, #2693)";
 
 /** Exit code when the read worked and a record falls below `--require`. */
 export const EXIT_BELOW_REQUIRED = 2;
@@ -196,6 +197,8 @@ export type RecordsDocument =
       summary: { total: number; valid: number; invalid: number; superseded: number };
       /** For a work kind (#2683): each decision its decision kind reads, with the work records implementing it. */
       decisions?: DecisionWork[];
+      /** The `--where` clauses the records were filtered with (#4363); absent without one. `summary` then counts the records listed. */
+      where?: string[];
     }
   | { $schema: string; contract: number; error: { code: ReadErrorCode; message: string } };
 
@@ -697,7 +700,12 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: pairing, hint: USAGE }));
     return 1;
   }
-  if (!args.kind) return runDeclaredRecords(args);
+  const filter = recordsWhere(args);
+  if ("error" in filter) {
+    console.error(formatError({ message: filter.error, hint: USAGE }));
+    return 1;
+  }
+  if (!args.kind) return runDeclaredRecords(args, filter.clauses);
   if (args.require !== undefined && args.require !== "attested") {
     console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
     return 1;
@@ -715,7 +723,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     else console.log(formatSince(since));
     return "error" in since ? 1 : 0;
   }
-  const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
+  const doc = filterRecordsDocument(await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true }), filter.clauses, args.where ?? []);
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
@@ -756,7 +764,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
  * declaration-level code the schema doesn't carry (`declaration-invalid` and
  * the rest of `WorkspaceErrorCode`) still prints text on stderr only.
  */
-async function runDeclaredRecords(args: CommandContext["args"]): Promise<number> {
+async function runDeclaredRecords(args: CommandContext["args"], clauses: readonly WhereClause[] = []): Promise<number> {
   if (args.require !== undefined && args.require !== "attested") {
     console.error(formatError({ message: `--require takes one level, attested, not ${JSON.stringify(args.require)}`, hint: USAGE }));
     return 1;
@@ -779,7 +787,9 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
     return 1;
   }
   if (args.since !== undefined) return runDeclaredSince(declared, args);
-  const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
+  const read = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
+  // The spec stays the whole current spec; --where narrows only the records each kind lists.
+  const set = { ...read, kinds: read.kinds.map((k) => filterRecordsDocument(k, clauses, args.where ?? [])) };
   if (args.json) console.log(JSON.stringify(set, null, 2));
   for (const doc of args.json ? [] : set.kinds) {
     if ("error" in doc) {
@@ -854,6 +864,49 @@ export function belowRequired(records: RecordView[], required: ProvenanceLevel):
 }
 
 /** Why `--uncommitted` can't be given with the other flags given, or undefined when it can (#3160). */
+/**
+ * The fields `records --where` filters on (#4363). `data` is the record's
+ * own fields, so `data.<key>` names any of them.
+ */
+export const RECORD_FILTER_FIELDS: FilterFields = {
+  id: "text",
+  path: "text",
+  state: "text",
+  valid: "boolean",
+  supersededBy: "text",
+  digest: "text",
+  ready: "boolean",
+  attested: "boolean",
+  worktree: "text",
+  ledger: "text",
+  "provenance.level": "text",
+  data: "json",
+};
+
+/** Keep the records every clause matches, counting `summary` over the records listed. A failure is left as it is. */
+export function filterRecordsDocument<D extends RecordsDocument>(doc: D, clauses: readonly WhereClause[], where: readonly string[]): D {
+  if (where.length === 0 || "error" in doc) return doc;
+  const records = doc.records.filter((r) => matchesWhere(r, clauses));
+  return {
+    ...doc,
+    records,
+    summary: { ...doc.summary, total: records.length, valid: records.filter((r) => r.valid).length, invalid: records.filter((r) => !r.valid).length },
+    where: [...where],
+  };
+}
+
+/** The `--where` clauses, or a message for a person. */
+function recordsWhere(args: CommandContext["args"]): { clauses: WhereClause[] } | { error: string } {
+  const where = args.where ?? [];
+  if (where.length > 0 && args.since !== undefined) return { error: "--where filters a records read and takes no --since: --since compares two revisions" };
+  try {
+    return { clauses: parseWhere(where, RECORD_FILTER_FIELDS) };
+  } catch (err) {
+    if (err instanceof FilterError) return { error: err.message };
+    throw err;
+  }
+}
+
 function uncommittedPairing(args: CommandContext["args"]): string | undefined {
   if (!args.uncommitted) return undefined;
   if (args.at !== undefined) return "--uncommitted reads the working tree against HEAD, and takes no --at";

package/src/workspace/records.schema.json

@@ -152,6 +152,11 @@
           "description": "Added in contract 1 by #2683, for a work kind only. Every decision the kind file named in the work kind's work.decisions reads at the same revision, whether or not a work record names it, each with the work records implementing it. A decision with an empty implementedBy has no work item yet.",
           "type": "array",
           "items": { "$ref": "#/$defs/decisionWork" }
+        },
+        "where": {
+          "description": "Added in contract 1 by #4363. Each --where clause, <field><op><value>, as given; every one held for each record listed, and summary's total, valid and invalid count the records listed. Absent without --where.",
+          "type": "array",
+          "items": { "type": "string" }
         }
       },
       "allOf": [

package/src/workspace/release-candidates.ts

@@ -39,7 +39,7 @@ import { latestPerComponent, readReleaseLedger } from "../lifecycle/release-ledg
 import { readAllReleases, readCuts } from "../lifecycle/release-store";
 import { resolveMemberLedger } from "../lifecycle/member-ledger";
 import { readBlobFromPath } from "../lifecycle/git";
-import { readerVersion } from "./declaration";
+import { greenBranches, readerVersion } from "./declaration";
 
 export const RELEASE_CANDIDATES_CONTRACT_VERSION = 1;
 export const RELEASE_CANDIDATES_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/release-candidates/v1/release-candidates.schema.json";
@@ -145,6 +145,8 @@ export interface ReleaseCandidatesQuery {
   /** Only this environment's view: the walk stops at what it runs, and `newFor` names only it. */
   env?: string;
   limit?: number;
+  /** Walk this branch of `ci.green.branch` (#4325) instead of the first. */
+  branch?: string;
 }
 
 function git(top: string, args: string[]): string {
@@ -218,7 +220,10 @@ export async function releaseCandidatesDocument(query: ReleaseCandidatesQuery):
     const { commitDetails } = await import("./intent");
     const source = scopeSource(cwd);
     const green = source.declaration?.ci?.green ?? null;
-    const trunk = resolveTrunk(top, green?.branch ?? null);
+    if (query.branch !== undefined && !(green && greenBranches(green).includes(query.branch))) {
+      throw new Error(`--branch ${query.branch} is not a branch ci.green judges${green ? ` (${greenBranches(green).join(", ")})` : ", and the declaration has no ci.green"}`);
+    }
+    const trunk = resolveTrunk(top, query.branch ?? green?.branch ?? null);
     const tip =
       tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/remotes/${trunk.remote}/${trunk.branch}^{commit}`]) ??
       tryGit(top, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk.branch}^{commit}`]);