@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/nested-graph.ts

@@ -22,6 +22,7 @@
 
 import { spawn } from "node:child_process";
 import type { ParsedArgs } from "../cli/registry";
+import { isViewDocument, prefixView, VIEW_DOCUMENT_VERSION } from "../capabilities/view";
 import { danglingKey, SCOPED_GROUPS, type ComposedMember, type ComposedNode, type WorkspaceGraph } from "./compose-graph";
 
 export type { NestedWorkspace } from "./compose-graph";
@@ -45,6 +46,7 @@ export function nestedArgv(dir: string, args: Partial<ParsedArgs>, at: string |
     ...(args.traffic !== undefined ? ["--traffic", String(args.traffic)] : []),
     ...(args.detail !== undefined ? ["--detail", String(args.detail)] : []),
     ...(args.noCache ? ["--no-cache"] : []),
+    ...(args.capabilityView ? ["--capability-view"] : []),
   ];
 }
 
@@ -97,10 +99,21 @@ export async function readNested(
   contract: number,
   toolchain: Toolchain | undefined = undefined,
 ): Promise<NestedRead & { stderr: string }> {
-  const r = await spawnRead((toolchain ?? readerToolchain()).command, nestedArgv(abs, args, at), abs);
+  const command = (toolchain ?? readerToolchain()).command;
+  let r = await spawnRead(command, nestedArgv(abs, args, at), abs);
+  // A nested chant from before #4378 has no --capability-view: read it
+  // without, and its members carry no view.
+  if (args.capabilityView && r.exitCode !== 0 && refusedCapabilityView(r.stderr)) {
+    r = await spawnRead(command, nestedArgv(abs, { ...args, capabilityView: false }, at), abs);
+  }
   return { ...readNestedDocument(r.stdout, r.exitCode, r.stderr, schemaId, contract), stderr: r.stderr };
 }
 
+/** Whether a chant refused `--capability-view` as a flag it doesn't know (#4378): one from before it. */
+export function refusedCapabilityView(stderr: string): boolean {
+  return /Unknown flag:?\s*--capability-view/i.test(stderr);
+}
+
 const prefixed = (outer: string, id: string): string => `${outer}/${id}`;
 
 function prefixRefs(value: unknown, outer: string): unknown {
@@ -141,6 +154,24 @@ export function foldNested(graph: WorkspaceGraph, member: ComposedMember, inner:
   for (const e of inner.exports ?? []) graph.exports.push({ ...e, ...(e.node ? { node: prefixed(outer, e.node) } : {}), member: outer });
   for (const i of inner.imports ?? []) graph.imports.push({ ...i, node: prefixed(outer, i.node), member: outer });
   graph.groups.byMember[outer] = ids.sort();
+  // The capability view (#4378): each nested member's, under the outer id. A
+  // nested member that read without one leaves the outer member without one.
+  const composedInner = inner.members.filter((m) => m.status === "composed");
+  if (composedInner.some((m) => m.capabilityView !== undefined)) {
+    const views = composedInner.map((m) => m.capabilityView);
+    if (views.every(isViewDocument)) {
+      const ps = views.map((v) => prefixView(v, `${outer}/`));
+      member.capabilityView = {
+        version: VIEW_DOCUMENT_VERSION,
+        lexicons: [...new Set(ps.flatMap((v) => v.lexicons))].sort(),
+        nodes: ps.flatMap((v) => v.nodes),
+        edges: ps.flatMap((v) => v.edges),
+        unresolved: ps.flatMap((v) => v.unresolved),
+      };
+    } else {
+      member.capabilityView = null;
+    }
+  }
   const groups = graph.groups as unknown as Record<string, Record<string, string[]> | undefined>;
   const innerGroups = inner.groups as unknown as Record<string, Record<string, string[]> | undefined>;
   for (const key of ["byLexicon", "byComposite"] as const) {

package/src/workspace/org-scope.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Org scope (#3168): a member of kind repo names another repository's
+ * workspace by URL and pinned revision, read read-only through that
+ * repository's own read contract; an org workspace holds only such members;
+ * `chant workspace check --forge-repos` compares them with the forge's list;
+ * and the read contract's identity names the repository a document came
+ * from. Every remote here is a local bare repository: nothing reaches a forge.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { runDeclarationChecks } from "./checks";
+import { parseForgeRepos, repoKey, urlCredential } from "./checks/org";
+import { readDeclaration, repoMemberDir } from "./declaration";
+import { workspaceGraph } from "./graph-cli";
+import { listWorkspace } from "./ls";
+import { fetchRepoAt, redactUrl, repoIdentity } from "./repo-ref";
+import { workingTree } from "./tree";
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+function tmp(prefix = "chant-3168-"): string {
+  const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
+  scratch.push(d);
+  return d;
+}
+const git = (cwd: string, ...args: string[]) =>
+  execFileSync("git", ["-c", "user.email=t@example.com", "-c", "user.name=t", "-c", "commit.gpgsign=false", ...args], { cwd, encoding: "utf-8" }).trim();
+function write(root: string, files: Record<string, string>): void {
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+}
+
+/** A repository with a workspace, pushed to a local bare remote. Returns the bare URL and the commit. */
+function remoteWorkspace(name: string): { url: string; rev: string } {
+  const work = tmp();
+  git(work, "init", "-q", "-b", "main");
+  write(work, { "chant.workspace.json": JSON.stringify({ name, schema: 1, members: [{ name: "docs", dir: "docs", kind: "other", because: "prose" }] }), "docs/README.md": "" });
+  git(work, "add", "-A");
+  git(work, "commit", "-q", "-m", "init");
+  const bare = join(tmp(), `${name}.git`);
+  git(work, "clone", "-q", "--bare", work, bare);
+  return { url: bare, rev: git(work, "rev-parse", "HEAD") };
+}
+
+/** An org workspace in a git repository of its own, with origin set. */
+function orgWorkspace(members: unknown[], extra: Record<string, unknown> = {}): string {
+  const root = tmp();
+  git(root, "init", "-q");
+  git(root, "remote", "add", "origin", "https://bot:secret@forge.example/acme/org.git");
+  write(root, { "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, scope: "org", members, ...extra }) });
+  return root;
+}
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+const repoMember = (name: string, url: string, rev = SHA) => ({ name, kind: "repo", repo: { url, rev } });
+
+describe("the declaration: repo members and scope", () => {
+  test("a repo member has repo and no dir, and reads with a marker dir", () => {
+    const root = orgWorkspace([repoMember("chant", "https://github.com/INTENTIUS/chant"), { ...repoMember("ops", "git@github.com:INTENTIUS/ops.git"), repo: { url: "git@github.com:INTENTIUS/ops.git", rev: SHA, workspace: "infra" } }]);
+    const d = readDeclaration(workingTree(root));
+    expect(d.scope).toBe("org");
+    expect(d.members.map((m) => [m.dir, m.repo])).toEqual([
+      [repoMemberDir("chant"), { url: "https://github.com/INTENTIUS/chant", rev: SHA, workspace: "." }],
+      [repoMemberDir("ops"), { url: "git@github.com:INTENTIUS/ops.git", rev: SHA, workspace: "infra" }],
+    ]);
+  });
+
+  test("refuses a repo member with a dir, another kind with repo, and a revision that isn't a full commit id", () => {
+    const read = (members: unknown[]) => () => readDeclaration(workingTree(orgWorkspace(members)));
+    expect(read([{ ...repoMember("a", "x"), dir: "a" }])).toThrow(/a member of kind repo has no dir/);
+    expect(read([{ name: "a", dir: "a", kind: "other", because: "x", repo: { url: "x", rev: SHA } }])).toThrow(/only a member of kind repo has repo/);
+    expect(read([repoMember("a", "x", "main")])).toThrow(/"main" is not allowed here/);
+    expect(read([{ name: "a", kind: "repo" }])).toThrow(/needs "repo"/);
+  });
+});
+
+describe("repoKey and credentials", () => {
+  test("https, ssh and scp-style URLs of one repository compare equal", () => {
+    const keys = ["https://github.com/INTENTIUS/Chant.git", "https://github.com/intentius/chant/", "git@github.com:INTENTIUS/chant.git", "ssh://git@github.com/INTENTIUS/chant"].map((u) => repoKey(u));
+    expect(new Set(keys)).toEqual(new Set(["github.com/intentius/chant"]));
+    expect(repoKey("./x.git", "/base")).toBe("/base/x");
+    expect(repoKey("file:///srv/x.git")).toBe("/srv/x");
+  });
+
+  test("a password, or a user on https, is a credential; ssh's git user is not", () => {
+    expect(urlCredential("https://bot:tok@forge.example/a/b")).toBe(true);
+    expect(urlCredential("https://tok@forge.example/a/b")).toBe(true);
+    expect(urlCredential("ssh://git@forge.example/a/b")).toBe(false);
+    expect(urlCredential("git@forge.example:a/b")).toBe(false);
+    expect(redactUrl("https://bot:tok@forge.example/a/b")).toBe("https://forge.example/a/b");
+  });
+});
+
+describe("parseForgeRepos", () => {
+  test("reads an object with repos, a bare array, strings and objects", () => {
+    expect(parseForgeRepos(JSON.stringify({ forge: "github", org: "acme", repos: ["https://f/a/x", { url: "https://f/a/y", archived: true }] }), "f.json").repos).toEqual([
+      { url: "https://f/a/x", archived: false },
+      { url: "https://f/a/y", archived: true },
+    ]);
+    expect(parseForgeRepos(JSON.stringify(["https://f/a/x"]), "f.json").repos).toHaveLength(1);
+    expect(() => parseForgeRepos("{}", "f.json")).toThrow(/repos array/);
+    expect(() => parseForgeRepos("[1]", "f.json")).toThrow(/repos\[0\]/);
+    expect(() => parseForgeRepos("nope", "f.json")).toThrow(/not JSON/);
+  });
+});
+
+describe("chant workspace check on an org workspace", () => {
+  const ids = async (root: string, forge?: unknown) =>
+    (await runDeclarationChecks(root, (f) => f, forge ? { forgeRepos: parseForgeRepos(JSON.stringify(forge), "forge.json") } : {})).diagnostics
+      .filter((d) => /^WSP0(0[1-9]|1[0-6])$/.test(d.ruleId))
+      .map((d) => `${d.ruleId}:${d.entity ?? ""}`);
+
+  test("repo members need no directory: no WSP004, and nothing else fires", async () => {
+    expect(await ids(orgWorkspace([repoMember("a", "https://forge.example/acme/a")]))).toEqual([]);
+  });
+
+  test("WSP013: an org workspace holds only repo members", async () => {
+    const root = orgWorkspace([repoMember("a", "https://forge.example/acme/a"), { name: "docs", dir: "docs", kind: "other", because: "x" }]);
+    mkdirSync(join(root, "docs"));
+    expect(await ids(root)).toContain("WSP013:docs");
+  });
+
+  test("WSP014 names a repository the forge has and the declaration lacks; WSP015 one the forge dropped; archived ones need not be declared", async () => {
+    const root = orgWorkspace([repoMember("a", "git@forge.example:acme/a.git"), repoMember("gone", "https://forge.example/acme/gone")]);
+    const forge = { repos: ["https://forge.example/acme/a", "https://forge.example/acme/new", { url: "https://forge.example/acme/old", archived: true }] };
+    const report = await runDeclarationChecks(root, (f) => f, { forgeRepos: parseForgeRepos(JSON.stringify(forge), "forge.json") });
+    const found = report.diagnostics.filter((d) => d.ruleId === "WSP014" || d.ruleId === "WSP015").map((d) => `${d.ruleId}: ${d.message}`);
+    expect(found).toEqual([
+      expect.stringMatching(/^WSP014: the forge lists https:\/\/forge.example\/acme\/new \(forge.json\), and no repo member names it/),
+      expect.stringMatching(/^WSP015: member gone names https:\/\/forge.example\/acme\/gone, which the forge no longer lists/),
+    ]);
+    expect(report.ok).toBe(false);
+    // Without the list, neither runs: check never asks the forge.
+    expect(await ids(root)).toEqual([]);
+  });
+
+  test("WSP016: a repo url never carries a credential", async () => {
+    expect(await ids(orgWorkspace([repoMember("a", "https://bot:tok@forge.example/acme/a")]))).toEqual(["WSP016:a"]);
+  });
+});
+
+describe("the read contract's identity names the repository", () => {
+  test("ls prints workspace.repo, redacted, and each repo member's reference", () => {
+    const root = orgWorkspace([repoMember("a", "https://forge.example/acme/a")]);
+    const doc = listWorkspace({ cwd: root });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.workspace.repo).toBe("https://forge.example/acme/org.git");
+    expect(doc.members[0]).toMatchObject({ name: "a", kind: "repo", readable: true, reason: null, repo: { url: "https://forge.example/acme/a", rev: SHA, workspace: "." } });
+  });
+
+  test("is null without an origin, or outside git", () => {
+    const plain = tmp();
+    git(plain, "init", "-q");
+    expect(repoIdentity(plain)).toBeNull();
+    expect(repoIdentity(tmp())).toBeNull();
+  });
+});
+
+describe("fetching a repo member's revision into the cache", () => {
+  test("fetches the pinned commit from a local bare remote into the user cache, once, and reports a commit it lacks", () => {
+    const remote = remoteWorkspace("payments");
+    const cache = tmp("chant-3168-cache-");
+    const env = { ...process.env, CHANT_CACHE_DIR: cache };
+    const first = fetchRepoAt({ url: remote.url, rev: remote.rev, workspace: "." }, "/", env);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    expect(first.dir.startsWith(join(cache, "repos"))).toBe(true);
+    expect(JSON.parse(readFileSync(join(first.dir, "chant.workspace.json"), "utf-8")).name).toBe("payments");
+    expect(git(first.dir, "rev-parse", "HEAD")).toBe(remote.rev);
+    expect(fetchRepoAt({ url: remote.url, rev: remote.rev, workspace: "." }, "/", env)).toEqual(first);
+    const missing = fetchRepoAt({ url: remote.url, rev: SHA, workspace: "." }, "/", env);
+    expect(missing).toMatchObject({ ok: false, message: expect.stringContaining(SHA) });
+  });
+});
+
+describe("chant workspace graph reads a repo member through its own read contract", () => {
+  test("runs the other repository's workspace graph at the pinned revision and folds it in, writing nothing in the workspace", async () => {
+    const remote = remoteWorkspace("payments");
+    const root = orgWorkspace([repoMember("payments", remote.url, remote.rev)]);
+    // A stand-in for the other repository's chant: it prints a graph document of the contract, with its argv and identity.
+    const bin = join(tmp(), "fake-chant.mjs");
+    writeFileSync(
+      bin,
+      `import { execFileSync } from "node:child_process";
+const argv = process.argv.slice(2);
+const at = argv[argv.indexOf("--at") + 1];
+const repo = execFileSync("git", ["config", "--get", "remote.origin.url"], { encoding: "utf-8" }).trim();
+const member = { name: "docs", dir: "docs", kind: "other", status: "composed", reason: null, chant: "9.9.9", irVersion: 1, live: false };
+console.log(JSON.stringify({ $schema: "https://intentius.io/chant/schemas/workspace/graph/v1/graph.schema.json", contract: 1, chant: "9.9.9", at, version: 1,
+  workspace: { name: "payments", root: ".", repo }, members: [member],
+  nodes: [{ id: "docs/Page", kind: "Page", lexicon: "x", attrs: {}, member: "docs" }], edges: [], groups: { byMember: { docs: ["docs/Page"] } },
+  exports: [], imports: [], links: [], collectors: [], records: [] }));
+`,
+    );
+    const cache = tmp("chant-3168-cache-");
+    const before = process.env.CHANT_CACHE_DIR;
+    process.env.CHANT_CACHE_DIR = cache;
+    try {
+      const { doc } = await workspaceGraph({ cwd: root, reader: { command: [process.execPath, bin], identity: bin, source: "path" } as never });
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.workspace).toMatchObject({ name: "acme", repo: "https://forge.example/acme/org.git" });
+      const m = doc.members.find((x) => x.name === "payments")!;
+      expect(m).toMatchObject({ kind: "repo", status: "composed", repo: { url: remote.url, rev: remote.rev, workspace: ".", read: remote.url } });
+      expect(m.nested?.name).toBe("payments");
+      expect(m.nested?.members.map((x) => x.name)).toEqual(["docs"]);
+      expect(doc.nodes.map((n) => n.id)).toEqual(["payments/docs/Page"]);
+      expect(existsSync(join(root, "@repo"))).toBe(false);
+      expect(git(root, "status", "--porcelain")).toBe("?? chant.workspace.json");
+    } finally {
+      if (before === undefined) delete process.env.CHANT_CACHE_DIR;
+      else process.env.CHANT_CACHE_DIR = before;
+    }
+  });
+
+  test("a revision the remote lacks fails the member with command-failed", async () => {
+    const remote = remoteWorkspace("payments");
+    const root = orgWorkspace([repoMember("payments", remote.url, SHA)]);
+    const before = process.env.CHANT_CACHE_DIR;
+    process.env.CHANT_CACHE_DIR = tmp("chant-3168-cache-");
+    try {
+      const { doc, failed } = await workspaceGraph({ cwd: root, reader: { command: ["false"], identity: "false", source: "path" } as never });
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(failed).toBe(true);
+      expect(doc.members[0]).toMatchObject({ status: "failed", reason: { code: "command-failed", message: expect.stringContaining(SHA) } });
+    } finally {
+      if (before === undefined) delete process.env.CHANT_CACHE_DIR;
+      else process.env.CHANT_CACHE_DIR = before;
+    }
+  });
+});

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,11 @@ 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 { 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";
@@ -55,6 +57,8 @@ import { ROTATION_REFUSAL_CODES } from "./trust/rotation";
 import { SIGNERS_ERROR_CODES } from "./trust/signers-cli";
 import { EVIDENCE_ERROR_CODES } from "./trust/evidence";
 import { METRICS_ERROR_CODES, METRICS_REASON_CODES } from "./delivery-metrics";
+import { SEARCH_ERROR_CODES, SEARCH_MEMBER_REASON_CODES, WORKSPACE_SEARCH_ERROR_CODES } from "./search-contract";
+import { CAPABILITIES_ERROR_CODES, CAPABILITY_SUPPORT_CODES } from "./capabilities-contract";
 
 const HERE = import.meta.dirname;
 
@@ -70,6 +74,7 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   DIAGRAM_FINDING_CODES,
   SECURITY_FINDING_CODES,
   CI_WORKFLOW_FINDING_CODES,
+  CI_BRANCH_FINDING_CODES,
   STATUS_REASON_CODES,
   STATUS_ERROR_CODES,
   STATUS_GATE_REASON_CODES,
@@ -98,6 +103,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,
@@ -106,6 +112,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,
@@ -132,6 +139,11 @@ const PER_COMMAND: Record<string, readonly string[]> = {
   EVIDENCE_ERROR_CODES,
   METRICS_ERROR_CODES,
   METRICS_REASON_CODES,
+  SEARCH_ERROR_CODES,
+  WORKSPACE_SEARCH_ERROR_CODES,
+  SEARCH_MEMBER_REASON_CODES,
+  CAPABILITIES_ERROR_CODES,
+  CAPABILITY_SUPPORT_CODES,
 };
 
 /** Every string in an `enum` under a property named `code`, anywhere in a schema. */

package/src/workspace/reason-codes.ts

@@ -51,9 +51,24 @@ export const REASONS = {
   "command-failed": "The member's own command exited with a failure, or the lexicon that reads the member through its kind's graph block isn't installed where the workspace resolves its pin.",
   "output-unreadable": "The member's command printed something that isn't the document asked for.",
   "ir-version-unsupported": "The member's IR has a version this chant can't read.",
+  // search and workspace search (#4374): why no answer was printed, and why a member has none.
+  "query-invalid": "search was given no query, a term its grammar can't parse, or a --count-by that is not a grouping.",
+  "usage-invalid": "search was given a flag that needs another one it lacks, or two that don't go together, such as --check-live without --snapshot.",
+  "environment-unknown": "--env names an environment the project's chant config does not declare.",
+  "snapshot-unavailable": "--snapshot names a snapshot chant can't replay: none is recorded for the environment, or the ref is one replay does not take.",
+  "build-failed": "The project's build, or one of its build roots, failed, so the graph search would answer over is incomplete.",
+  "snapshot-at-revision": "workspace search was given --snapshot and --at: a snapshot replays the estate as recorded over the source in the working tree, not at a revision.",
+  "member-chant-too-old": "The member's chant predates the document asked for: it has no such command, or prints it without the read contract.",
+  // the capabilities catalog (#4375): why a lexicon can't supply a capability.
+  "lexicon-has-no-mapping": "The lexicon ships no capability mapping, so no capability rule can read its resources.",
+  "capability-not-derivable": "The lexicon's capability mapping labels none of the kinds the capability's rule needs.",
+  "lexicon-not-loaded": "The lexicon isn't installed where the chant that wrote the catalog runs, so its mapping wasn't read.",
   // 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.",
@@ -225,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.",
@@ -257,6 +275,7 @@ 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.",
+  "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.",
@@ -279,6 +298,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.

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}`]);