@intentius/chant 0.124.46 → 0.124.48

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

package/src/workspace/release-train.ts

@@ -0,0 +1,157 @@
+/**
+ * Release trains (#2554, #2524 D19, ws-043): one record that pins a release
+ * of every `chant` member, so several members move together.
+ *
+ * Releases stay per member (ws-043): each is a digest over its artifacts and
+ * a git commit, written to the member's own ledger by `chant release cut`. A
+ * train names one of them per member: by default the newest cut release, or
+ * the one `--pin <member>=<label|digest>` picks. It refuses unless every
+ * `chant` member of the declaration has a release, so a train never leaves a
+ * member out. It is written to `_members/_workspace/<env>/trains.jsonl`.
+ */
+
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { readAllReleases, readCuts } from "../lifecycle/release-store";
+import { readDeclaration, WorkspaceReadError } from "./declaration";
+import { locateWorkspace } from "./which-chant";
+import { appendWorkspaceLine, readWorkspaceLines } from "./workspace-ledger";
+
+export interface TrainMember {
+  member: string;
+  releaseDigest: string;
+  /** The release's git commit. */
+  commit: string;
+  /** The label its newest cut gave it, or null. */
+  label: string | null;
+}
+
+export interface ReleaseTrainRecord {
+  version: 1;
+  id: string;
+  env: string;
+  timestamp: string;
+  actor: string;
+  /** Every `chant` member, by name. */
+  members: TrainMember[];
+}
+
+const TRAINS_FILE = "trains.jsonl";
+
+/** What one member offers a train: its releases, newest cut first. */
+export interface MemberReleases {
+  member: string;
+  releases: TrainMember[];
+}
+
+/**
+ * Pick each member's release, pure. `pins` maps a member to a label or a
+ * digest; a member with no pin takes its newest. Returns the members, or
+ * the problems that stop the train.
+ */
+export function pickTrain(members: readonly MemberReleases[], pins: ReadonlyMap<string, string> = new Map()): { members: TrainMember[] } | { problems: string[] } {
+  const problems: string[] = [];
+  const picked: TrainMember[] = [];
+  for (const name of pins.keys()) {
+    if (!members.some((m) => m.member === name)) problems.push(`--pin ${name}: not a chant member of the workspace`);
+  }
+  for (const m of members) {
+    const pin = pins.get(m.member);
+    const r = pin === undefined ? m.releases[0] : m.releases.find((x) => x.releaseDigest === pin || x.label === pin);
+    if (!r) {
+      problems.push(pin === undefined ? `member ${m.member} has no release; cut one with chant release cut in its directory` : `member ${m.member} has no release ${pin}`);
+      continue;
+    }
+    picked.push(r);
+  }
+  return problems.length > 0 ? { problems } : { members: picked };
+}
+
+/** Every `chant` member's releases, newest cut first, read from its ledger. */
+export async function readMemberReleases(cwd: string): Promise<MemberReleases[]> {
+  const located = locateWorkspace(cwd);
+  const declaration = readDeclaration(located.tree, "", { rootChant: true });
+  const out: MemberReleases[] = [];
+  for (const m of declaration.members) {
+    if (m.kind !== "chant") continue;
+    const loc = { cwd: located.rootOnDisk, member: m.dir === "." ? "." : m.name };
+    const { releases } = await readAllReleases(loc);
+    const { cuts } = await readCuts(loc);
+    const newest = (digest: string) => cuts.filter((c) => c.releaseDigest === digest).map((c) => c.timestamp).sort().at(-1) ?? "";
+    const label = (digest: string) => cuts.filter((c) => c.releaseDigest === digest && c.label !== null).sort((a, b) => (a.timestamp < b.timestamp ? -1 : 1)).at(-1)?.label ?? null;
+    const list = releases
+      .filter((r) => newest(r.releaseDigest) !== "")
+      .sort((a, b) => (newest(b.releaseDigest) < newest(a.releaseDigest) ? -1 : newest(b.releaseDigest) > newest(a.releaseDigest) ? 1 : 0))
+      .map((r) => ({ member: m.name, releaseDigest: r.releaseDigest, commit: r.commit, label: label(r.releaseDigest) }));
+    out.push({ member: m.name, releases: list });
+  }
+  return out;
+}
+
+function isTrain(v: unknown): v is ReleaseTrainRecord {
+  const t = v as ReleaseTrainRecord;
+  return typeof t === "object" && t !== null && t.version === 1 && typeof t.id === "string" && typeof t.env === "string" && Array.isArray(t.members);
+}
+
+export async function readReleaseTrains(cwd: string, env: string): Promise<{ records: ReleaseTrainRecord[]; malformed: number }> {
+  return readWorkspaceLines(cwd, env, TRAINS_FILE, isTrain);
+}
+
+export async function appendReleaseTrain(cwd: string, record: ReleaseTrainRecord): Promise<string> {
+  return appendWorkspaceLine(cwd, record.env, TRAINS_FILE, record, `Release train: ${record.env} ${record.id}`);
+}
+
+const USAGE = "chant workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json] | chant workspace train list <env> [--json]";
+
+export async function runWorkspaceTrain(ctx: CommandContext): Promise<number> {
+  const words = ctx.args.positionals ?? [];
+  const rest = words[0] === "train" ? words.slice(1) : words;
+  const listing = rest[0] === "list";
+  const env = listing ? rest[1] : rest[0];
+  if (!env) {
+    console.error(formatError({ message: "chant workspace train needs an environment", hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(".");
+  try {
+    if (listing) {
+      const root = locateWorkspace(cwd).rootOnDisk;
+      const { records } = await readReleaseTrains(root, env);
+      if (ctx.args.json) console.log(JSON.stringify({ env, trains: records }, null, 2));
+      else if (records.length === 0) console.log(`No release train recorded for ${env}.`);
+      else for (const t of records) console.log(`${t.timestamp}  ${t.id}  ${t.members.map((m) => `${m.member}@${m.label ?? m.releaseDigest.slice(0, 19)}`).join(" ")}`);
+      return 0;
+    }
+    const pins = new Map<string, string>();
+    for (const p of ctx.args.pins ?? []) {
+      const at = p.indexOf("=");
+      if (at <= 0) {
+        console.error(formatError({ message: `--pin ${p}: expected <member>=<label|digest>`, hint: USAGE }));
+        return 1;
+      }
+      pins.set(p.slice(0, at), p.slice(at + 1));
+    }
+    const root = locateWorkspace(cwd).rootOnDisk;
+    const picked = pickTrain(await readMemberReleases(root), pins);
+    if ("problems" in picked) {
+      console.error(formatError({ message: `no release train for ${env}: every chant member needs a release`, hint: USAGE }));
+      for (const p of picked.problems) console.error(`  ${p}`);
+      return 1;
+    }
+    const actor = ctx.args.actor ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER ?? "unknown";
+    const record: ReleaseTrainRecord = { version: 1, id: `train-${randomUUID()}`, env, timestamp: new Date().toISOString(), actor, members: picked.members };
+    if (!ctx.args.dryRun) await appendReleaseTrain(root, record);
+    if (ctx.args.json) console.log(JSON.stringify({ ...record, written: !ctx.args.dryRun }, null, 2));
+    else {
+      console.log(`${ctx.args.dryRun ? "Would record" : "Recorded"} release train ${record.id} for ${env}:`);
+      for (const m of record.members) console.log(`  ${m.member.padEnd(24)} ${m.label ?? "(no label)"}  ${m.releaseDigest}  ${m.commit.slice(0, 12)}`);
+    }
+    return 0;
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    console.error(formatError({ message: `${err.code}: ${err.describe()}`, hint: USAGE }));
+    return 1;
+  }
+}

package/src/workspace/release-workflow.ts

@@ -16,6 +16,7 @@
  * there: it costs nothing, and with it what the job uploads carries
  * provenance whether or not the group requires it.
  */
+import { ACTION_PINS, tagComments, usesRef } from "../action-pins";
 import { GENERATED_MARKER } from "../discovery/files";
 import type { SecurityGroup } from "./security";
 
@@ -91,10 +92,10 @@ export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
     "    runs-on: ubuntu-latest",
     ...(root ? ["    defaults:", "      run:", `        working-directory: ${root}`] : []),
     "    steps:",
-    "      - uses: actions/checkout@v4",
+    `      - uses: ${usesRef(ACTION_PINS.checkout4)}`,
     "        with:",
     "          fetch-depth: 0",
-    "      - uses: actions/setup-node@v4",
+    `      - uses: ${usesRef(ACTION_PINS.setupNode4)}`,
     "        with:",
     "          node-version: 24",
     "          registry-url: https://registry.npmjs.org",
@@ -105,7 +106,7 @@ export function renderReleaseWorkflow(input: ReleaseWorkflowInput): string {
     ...(verify ? [`      - run: ${chant} release verify ${label}`] : []),
     `      - run: ${chant} release publish ${label} ${flags}`,
   ];
-  return `${lines.join("\n")}\n`;
+  return tagComments(`${lines.join("\n")}\n`);
 }
 
 /** The header that marks the file generated, naming the command that regenerates it. */

package/src/workspace/repo-ref.ts

@@ -0,0 +1,113 @@
+/**
+ * Another repository's workspace, named by URL and pinned revision (#3168).
+ *
+ * A member of kind `repo` is read the way a nested `workspace` member is
+ * (./nested-graph.ts): through that repository's own `chant workspace graph`,
+ * at the pinned revision, and nothing is ever written there. To have a tree
+ * to run that read in, chant fetches the revision into the user's cache
+ * directory, never under the workspace: one clone per URL, and one detached
+ * worktree per revision, which is immutable once made, so two reads of one
+ * revision share it and a read never moves another's checkout.
+ *
+ * This is the only place `chant workspace graph` reaches a remote, and only
+ * for repo members. `chant workspace check` never fetches.
+ *
+ * The read contract's identity names the repository a document came from
+ * (`workspace.repo`): the URL of the `origin` remote, credentials removed.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { CACHE_DIR_ENV } from "./graph-cache";
+import { urlCredential } from "./checks/org";
+import type { RepoRef } from "./declaration";
+
+/** A URL with any user name and password removed; scp-style and local paths are returned as they are. */
+export function redactUrl(url: string): string {
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) return url;
+  try {
+    const u = new URL(url);
+    if (u.username === "" && u.password === "") return url;
+    u.username = "";
+    u.password = "";
+    return u.toString();
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * The repository a workspace on disk came from (#3168): its git repository's
+ * `origin` URL, redacted, or null without git or an origin. Reads local git
+ * config only; never reaches the remote.
+ */
+export function repoIdentity(dir: string): string | null {
+  try {
+    const url = execFileSync("git", ["-C", dir, "config", "--get", "remote.origin.url"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return url ? redactUrl(url) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where fetched repositories live: `<cache>/repos`, with the cache dir as the graph cache finds it. */
+export function repoCacheDir(env: NodeJS.ProcessEnv = process.env): string {
+  const base = env[CACHE_DIR_ENV] || join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "chant");
+  return join(base, "repos");
+}
+
+/** The URL git is handed: a relative local path is resolved from the workspace root, since git runs in the cache. */
+export function fetchUrl(url: string, workspaceRoot: string): string {
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) return url;
+  if (/^(?:[^@/\s]+@)?[^:/\s]+:(?!\/\/)/.test(url) && !isAbsolute(url) && !/^[a-z]:[\\/]/i.test(url)) return url;
+  return resolve(workspaceRoot, url);
+}
+
+export type RepoFetch = { ok: true; dir: string; worktree: string } | { ok: false; message: string };
+
+const GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+
+function git(args: string[], cwd?: string): { ok: boolean; out: string } {
+  try {
+    const out = execFileSync("git", args, { cwd, encoding: "utf-8", env: GIT_ENV, stdio: ["ignore", "pipe", "pipe"], timeout: 120_000 });
+    return { ok: true, out };
+  } catch (err) {
+    const e = err as { stderr?: string | Buffer; message: string };
+    return { ok: false, out: String(e.stderr ?? e.message).trim().split("\n").slice(-3).join("; ") };
+  }
+}
+
+/**
+ * Make `ref`'s revision available in the cache, fetching it when the cache
+ * doesn't hold it, and return the directory of its workspace root there.
+ * Never throws; a failure says why.
+ */
+export function fetchRepoAt(ref: RepoRef, workspaceRoot: string, env: NodeJS.ProcessEnv = process.env): RepoFetch {
+  if (urlCredential(ref.url)) return { ok: false, message: `the repo url carries a credential, which chant refuses to use (WSP016)` };
+  const url = fetchUrl(ref.url, workspaceRoot);
+  const clone = join(repoCacheDir(env), createHash("sha256").update(url).digest("hex").slice(0, 24));
+  const worktree = join(clone, "at", ref.rev);
+  const dir = ref.workspace === "." ? worktree : join(worktree, ...ref.workspace.split("/"));
+  if (existsSync(join(worktree, ".git"))) return { ok: true, dir, worktree };
+  if (!existsSync(join(clone, ".git"))) {
+    mkdirSync(clone, { recursive: true });
+    const init = git(["init", "-q", clone]);
+    if (!init.ok) return { ok: false, message: `could not make the cache clone in ${clone}: ${init.out}` };
+    git(["-C", clone, "remote", "add", "origin", url]);
+  }
+  const has = () => git(["-C", clone, "cat-file", "-e", `${ref.rev}^{commit}`]).ok;
+  if (!has()) {
+    // A pinned commit by id first; a server that refuses unadvertised ids gets a full fetch.
+    const byId = git(["-C", clone, "fetch", "-q", "origin", ref.rev]);
+    if (!has()) {
+      const all = git(["-C", clone, "fetch", "-q", "origin", "+refs/heads/*:refs/remotes/origin/*", "+refs/tags/*:refs/tags/*"]);
+      if (!has()) return { ok: false, message: `could not fetch ${ref.rev} from ${redactUrl(ref.url)}: ${all.ok ? (byId.ok ? "the repository has no such commit" : byId.out) : all.out}` };
+    }
+  }
+  const add = git(["-C", clone, "worktree", "add", "-q", "--detach", worktree, ref.rev]);
+  if (!add.ok && !existsSync(join(worktree, ".git"))) return { ok: false, message: `could not check out ${ref.rev} in the cache: ${add.out}` };
+  return { ok: true, dir, worktree };
+}

package/src/workspace/run-event.schema.json

@@ -296,8 +296,8 @@
             "resolvedBy": { "type": "string", "description": "Who approved it." },
             "resolvedAt": { "type": "string", "description": "When the approval was recorded, ISO-8601." },
             "via": {
-              "enum": ["quorum", "policy", "point", "alias", "empty", null],
-              "description": "How the approval passed when it was more than one person's approval of this gate: a quorum, a policy permit, a decision point's answer, or an approval recorded under one of the gate's aliases. empty (added within contract 1 by #4045, chant 0.124.28 and newer): a release gate passed over an empty change set with no approval, on the resolution the promote wrote, whose resolvedBy is the actor running it."
+              "enum": ["quorum", "policy", "point", "alias", "empty", "workspace", null],
+              "description": "How the approval passed when it was more than one person's approval of this gate: a quorum, a policy permit, a decision point's answer, or an approval recorded under one of the gate's aliases. empty (added within contract 1 by #4045, chant 0.124.28 and newer): a release gate passed over an empty change set with no approval, on the resolution the promote wrote, whose resolvedBy is the actor running it. workspace (added within contract 1 by #2554, chant 0.124.47 and newer): a workspace gate's approval stood in for this member gate, because the member opts in at base and the approval covers this plan."
             },
             "url": { "type": "string", "description": "Where the approval was made, when known." }
           }

package/src/workspace/runs-cli.ts

@@ -49,6 +49,7 @@ import {
   type RunWriteContext,
 } from "./runs";
 import { RUN_TRAILER } from "./trailers";
+import { FilterError, matchesWhere, parseWhere, type FilterFields } from "../read-filter";
 import { locateWorkspace } from "./which-chant";
 import { idList } from "./work";
 import { AGENT_ENV } from "./write-scope";
@@ -71,7 +72,7 @@ export const RUNS_WRITE_SCHEMA_ID = "https://intentius.io/chant/schemas/workspac
 export const RUN_STATEMENT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/run-statement/v1/run-statement.schema.json";
 
 const USAGE = [
-  "chant workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--json]",
+  "chant workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--where <field><op><value>]... [--follow-squash] [--json]",
   "chant workspace runs start --from <file|->",
   "chant workspace runs end <run id> [--from <file|->]",
   "chant workspace runs record --from <file|->",
@@ -177,8 +178,36 @@ export interface RunsQuery {
   base?: string;
   /** Follow squash merges on HEAD to their pull requests' original commits, fetching missing pull request refs (#3035). */
   followSquash?: boolean;
+  /** Typed filters (#4363), each `<field><op><value>` over {@link RUN_FILTER_FIELDS}; every one has to hold. Applied before the totals. */
+  where?: readonly string[];
 }
 
+/** The fields `runs --where` filters on (#4363). */
+export const RUN_FILTER_FIELDS: FilterFields = {
+  id: "text",
+  state: "text",
+  startedAt: "time",
+  endedAt: "time",
+  outcome: "text",
+  by: "text",
+  agent: "text",
+  model: "text",
+  provider: "text",
+  lease: "text",
+  "harness.name": "text",
+  "harness.version": "text",
+  "unit.id": "text",
+  "unit.kind": "text",
+  "cost.amount": "number",
+  "cost.currency": "text",
+  "usage.inputTokens": "number",
+  "usage.outputTokens": "number",
+  ledger: "text",
+};
+
+/** Thrown for a `--where` that can't be applied: a usage error, before the ledger is read. */
+export class RunsFilterError extends Error {}
+
 export interface RunsReason {
   code: RunsReasonCode;
   message: string;
@@ -218,7 +247,7 @@ export type RunsDocument =
       workspace: { name: string; root: string };
       ledger: { branch: string; dir: string; commit: string | null };
       /** The options given. `followSquash` was added within contract 1 (#3035). */
-      filter: { unit: string | null; decision: string | null; by: string | null; since: string | null; followSquash?: boolean };
+      filter: { unit: string | null; decision: string | null; by: string | null; since: string | null; followSquash?: boolean; where?: string[] };
       /** The trust policy the run statements are judged by (#3192). */
       trust: RunsTrust;
       /** Newest first, by when each started. Each carries its `attestation`. */
@@ -281,6 +310,13 @@ function tryGit(top: string, args: string[]): string | undefined {
 /** Read the run ledger and build the document. Never throws a {@link WorkspaceReadError}. */
 export async function workspaceRuns(query: RunsQuery): Promise<RunsDocument> {
   const head = { $schema: RUNS_OUTPUT_SCHEMA_ID, contract: RUNS_CONTRACT_VERSION, chant: readerVersion() };
+  let clauses;
+  try {
+    clauses = parseWhere(query.where ?? [], RUN_FILTER_FIELDS);
+  } catch (err) {
+    if (err instanceof FilterError) throw new RunsFilterError(err.message);
+    throw err;
+  }
   try {
     const located = locateWorkspace(query.cwd);
     const declaration = readDeclaration(located.tree, "", { rootChant: true });
@@ -318,6 +354,7 @@ export async function workspaceRuns(query: RunsQuery): Promise<RunsDocument> {
       .filter((r) => wantDecision === undefined || r.decisions.some((d) => d === wantDecision || d.slice(d.indexOf("/") + 1) === wantDecision))
       .filter((r) => query.by === undefined || r.by === query.by)
       .filter((r) => !since || r.commits.some((c) => since!.commits.has(c.sha)) || Date.parse(r.startedAt) > since.date)
+      .filter((r) => matchesWhere(r, clauses))
       .sort((a, b) => (a.startedAt < b.startedAt ? 1 : a.startedAt > b.startedAt ? -1 : a.id < b.id ? 1 : -1));
 
     const byUnit = [...groupBy(selected, (r) => [r.unit?.id ?? null])].map(([unit, rs]) => ({ unit, ...totalRuns(rs) }));
@@ -327,7 +364,7 @@ export async function workspaceRuns(query: RunsQuery): Promise<RunsDocument> {
       ...head,
       workspace: { name: declaration.name, root: located.root },
       ledger: { branch: LEDGER_BRANCH, dir, commit: tip },
-      filter: { unit: query.unit ?? null, decision: query.decision ?? null, by: query.by ?? null, since: query.since ?? null, followSquash: query.followSquash === true },
+      filter: { unit: query.unit ?? null, decision: query.decision ?? null, by: query.by ?? null, since: query.since ?? null, followSquash: query.followSquash === true, ...(query.where && query.where.length > 0 ? { where: [...query.where] } : {}) },
       trust,
       runs: selected,
       totals: { all: totalRuns(selected), byUnit, byDecision, byPrincipal },
@@ -652,7 +689,14 @@ export async function runWorkspaceRuns(ctx: CommandContext): Promise<number> {
     console.error(formatError({ message: "runs is a read and takes no --from; write with runs start, end or record", hint: USAGE }));
     return 1;
   }
-  const doc = await workspaceRuns({ cwd, unit: args.unit, decision: args.decision, by: args.by, since: args.since, base: args.base, followSquash: args.followSquash });
+  let doc: RunsDocument;
+  try {
+    doc = await workspaceRuns({ cwd, unit: args.unit, decision: args.decision, by: args.by, since: args.since, base: args.base, followSquash: args.followSquash, where: args.where });
+  } catch (err) {
+    if (!(err instanceof RunsFilterError)) throw err;
+    console.error(formatError({ message: err.message, hint: USAGE }));
+    return 1;
+  }
   if (args.json) console.log(JSON.stringify(doc, null, 2));
   else if ("error" in doc) console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
   else console.log(formatRuns(doc));

package/src/workspace/runs.schema.json

@@ -111,6 +111,13 @@
             "followSquash": {
               "type": "boolean",
               "description": "Whether --follow-squash was given (#3035). Added within version 1."
+            },
+            "where": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "description": "Each --where clause, <field><op><value>, as given (#4363); every one held for each run listed, and the totals count only those runs. Absent without --where. Added within version 1."
             }
           }
         },