@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/member-run.ts

@@ -0,0 +1,146 @@
+/**
+ * `chant workspace member-run` (#2537): the one process a toolchain runs for
+ * `chant workspace build|lint|audit|graph`.
+ *
+ * `member-commands.ts` groups the members by the chant each one resolves
+ * (#2524 D3, "one process per toolchain identity") and spawns that chant's
+ * `workspace member-run` once per group. The request arrives as JSON on
+ * stdin: the level-0 command line for each member, and the member's
+ * directory. This process runs them one after another, in-process, from
+ * inside each directory, so every member gets what `chant <verb> .` would
+ * print there. It answers on stdout with one {@link PROTOCOL_PREFIX} line per
+ * member, after a header line naming the protocol and this chant's version.
+ *
+ * A chant older than this command has no header to print. The caller sees
+ * that and falls back to one level-0 process per member.
+ *
+ * Internal: not listed in `chant --help`, and the protocol may change with
+ * the caller, which is always a chant of the same or a newer release.
+ */
+
+import { ENV_VAR } from "../env";
+import type { CommandContext } from "../cli/registry";
+import { readerVersion } from "./declaration";
+
+/** Marks the lines of this protocol on stdout; anything else there is stray output. */
+export const PROTOCOL_PREFIX = "@@chant-member-run@@ ";
+export const MEMBER_RUN_PROTOCOL = 1;
+
+export interface MemberRunRequest {
+  protocol: number;
+  units: MemberRunUnit[];
+}
+
+export interface MemberRunUnit {
+  /** Echoed back on the answer line. */
+  id: string;
+  /** The member's directory, absolute. The command runs from inside it. */
+  dir: string;
+  /** The level-0 command line, such as `["lint", ".", "--format", "sarif"]`. */
+  argv: string[];
+  /**
+   * Directories (relative to `dir`) to leave out of discovery. Set for member
+   * `.`, whose project is the root minus every other member. Kept in the
+   * protocol for a member-run from before #2527, which applied it itself;
+   * from #2527 on, discovery reads the same set from the declaration.
+   */
+  exclude?: string[];
+}
+
+export type MemberRunLine =
+  | { type: "header"; protocol: number; chant: string }
+  | { type: "result"; id: string; exitCode: number; stdout: string; stderr: string };
+
+/** A `process.exit` inside a command, turned into a value. */
+class ExitRequest extends Error {
+  constructor(readonly code: number) {
+    super(`process.exit(${code})`);
+  }
+}
+
+type Write = typeof process.stdout.write;
+
+/**
+ * Run `fn` with stdout, stderr and `process.exit` captured. Commands print
+ * through `console`, which writes through the stream's `write` at call time,
+ * so replacing `write` catches everything they print.
+ */
+export async function captureRun(fn: () => Promise<number>): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  const out: string[] = [];
+  const err: string[] = [];
+  const sink =
+    (into: string[]): Write =>
+    ((chunk: string | Uint8Array, encoding?: unknown, cb?: unknown) => {
+      into.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+      const done = typeof encoding === "function" ? encoding : cb;
+      if (typeof done === "function") (done as () => void)();
+      return true;
+    }) as Write;
+  const saved = { out: process.stdout.write, err: process.stderr.write, exit: process.exit };
+  process.stdout.write = sink(out);
+  process.stderr.write = sink(err);
+  process.exit = ((code?: number) => {
+    throw new ExitRequest(typeof code === "number" ? code : 0);
+  }) as typeof process.exit;
+  let exitCode: number;
+  try {
+    exitCode = await fn();
+  } catch (e) {
+    if (e instanceof ExitRequest) {
+      exitCode = e.code;
+    } else {
+      err.push(`${e instanceof Error ? e.message : String(e)}\n`);
+      exitCode = 1;
+    }
+  } finally {
+    process.stdout.write = saved.out;
+    process.stderr.write = saved.err;
+    process.exit = saved.exit;
+  }
+  return { exitCode, stdout: out.join(""), stderr: err.join("") };
+}
+
+function emit(line: MemberRunLine): void {
+  process.stdout.write(`${PROTOCOL_PREFIX}${JSON.stringify(line)}\n`);
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** Run each unit of `request` in turn, answering on stdout. */
+export async function runMemberUnits(request: MemberRunRequest, run: (argv: string[]) => Promise<number>): Promise<number> {
+  emit({ type: "header", protocol: MEMBER_RUN_PROTOCOL, chant: readerVersion() });
+  const startDir = process.cwd();
+  const startEnv = process.env[ENV_VAR];
+  for (const unit of request.units) {
+    const result = await captureRun(async () => {
+      process.chdir(unit.dir);
+      // `unit.exclude` needs no action here: discovery reads the declaration
+      // itself and leaves member `.`'s exclusions out of every walk (#2527).
+      return run(unit.argv);
+    });
+    if (startEnv === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = startEnv;
+    process.chdir(startDir);
+    emit({ type: "result", id: unit.id, ...result });
+  }
+  return 0;
+}
+
+export async function runWorkspaceMemberRun(_ctx: CommandContext, run: (argv: string[]) => Promise<number>): Promise<number> {
+  let request: MemberRunRequest;
+  try {
+    request = JSON.parse(await readStdin()) as MemberRunRequest;
+  } catch (err) {
+    console.error(`chant workspace member-run: the request on stdin is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+  if (request.protocol !== MEMBER_RUN_PROTOCOL || !Array.isArray(request.units)) {
+    console.error(`chant workspace member-run: this chant speaks protocol ${MEMBER_RUN_PROTOCOL}, and the request asks for ${String(request.protocol)}`);
+    return 1;
+  }
+  return runMemberUnits(request, run);
+}

package/src/workspace/read-contract.test.ts

@@ -0,0 +1,129 @@
+/**
+ * The read contract as a whole (#2536, #2524 D15): every output schema, run
+ * against the reference workspace (#2543) in this checkout.
+ *
+ * `reference-workspace/` is a nested workspace of the chant repo, with a
+ * `chant` member (`delivery`), three `other` members and decision records.
+ * Each read-contract command reads it here, and its output must validate
+ * against the command's schema: `ls`, `graph` (running delivery's real
+ * `chant graph`), `check`, `status` and `records`, in the working tree and,
+ * for `ls`, `graph` and `check`, at `HEAD` through `--at`.
+ *
+ * The schemas themselves are checked here too: each is a draft 2020-12
+ * document under `https://intentius.io/chant/schemas/workspace/<command>/v1/`,
+ * at the contract version this chant writes, naming the chant floor.
+ */
+
+import { realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { describe, expect, test } from "vitest";
+import { contract, git, REPO, validSchema } from "./__fixtures__/contract-repo";
+import checkSchema from "./check.schema.json";
+import { workspaceGraph } from "./graph-cli";
+import graphSchema from "./graph.schema.json";
+import { runChecks } from "./lineage-check";
+import { listWorkspace } from "./ls";
+import lsSchema from "./ls.schema.json";
+import { readerBin, type Toolchain } from "./member-commands";
+import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION } from "./reason-codes";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import { workspaceStatus } from "./status";
+import statusSchema from "./status.schema.json";
+
+const FIXTURE = join(REPO, "reference-workspace");
+const TIMEOUT = 240_000;
+
+const SCHEMAS = { ls: lsSchema, graph: graphSchema, check: checkSchema, status: statusSchema, records: recordsSchema };
+
+/** This checkout's chant, started the way the CLI starts it, for members with no toolchain of their own. */
+const reader: Toolchain = {
+  command: [process.execPath, "--import", pathToFileURL(join(REPO, "node_modules", "tsx", "dist", "loader.mjs")).href, join(REPO, "packages", "core", "src", "cli", "main.ts")],
+  identity: realpathSync(readerBin()),
+  source: "reader",
+};
+
+describe("the read contract's schemas", () => {
+  test.each(Object.entries(SCHEMAS))("%s is a valid draft 2020-12 document at the contract version, naming the floor", (name, schema) => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(`https://intentius.io/chant/schemas/workspace/${name}/v${READ_CONTRACT_VERSION}/${name}.schema.json`);
+    for (const branch of ["result", "failure"] as const) {
+      const props = (schema.$defs as Record<string, { properties: Record<string, unknown> }>)[branch].properties;
+      expect(props.contract, `${name} ${branch}`).toEqual({ const: READ_CONTRACT_VERSION });
+      expect(props.$schema, `${name} ${branch}`).toEqual({ const: schema.$id });
+    }
+    expect(schema.description).toContain(`chant ${READ_CONTRACT_FLOOR} and newer`);
+  });
+});
+
+describe("every schema against the reference workspace (#2543)", () => {
+  const head = git(REPO, "rev-parse", "HEAD");
+
+  test("ls, in the working tree and at HEAD", () => {
+    const { expectValid } = contract(lsSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const doc = listWorkspace({ cwd: join(FIXTURE, "delivery"), at });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.workspace).toMatchObject({ name: "reference", root: "reference-workspace" });
+      expect(doc.at).toBe(at ? head : null);
+      expect(doc.members.map((m) => [m.name, m.readable])).toEqual([
+        ["app", true],
+        ["delivery", true],
+        ["design-client", true],
+        ["design", true],
+      ]);
+    }
+  });
+
+  test(
+    "graph runs delivery's own chant graph, in the working tree and at HEAD",
+    async () => {
+      const { expectValid } = contract(graphSchema);
+      for (const at of [undefined, "HEAD"]) {
+        const { doc, failed } = await workspaceGraph({ cwd: FIXTURE, at, reader });
+        expectValid(doc);
+        if ("error" in doc) throw new Error(doc.error.message);
+        expect(failed, JSON.stringify(doc.members)).toBe(false);
+        expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+        expect(doc.at).toBe(at ? head : null);
+        const delivery = doc.members.find((m) => m.name === "delivery");
+        expect(delivery).toMatchObject({ status: "composed", reason: null, irVersion: 1 });
+        expect(doc.groups.byMember.delivery.length).toBeGreaterThan(0);
+        expect(doc.nodes.every((n) => n.id.startsWith("delivery/") && n.member === "delivery")).toBe(true);
+      }
+    },
+    TIMEOUT,
+  );
+
+  test("check, in the working tree and at HEAD", async () => {
+    const { expectValid } = contract(checkSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const doc = await runChecks(FIXTURE, at);
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.workspace).toEqual({ name: "reference", root: "reference-workspace" });
+      expect(doc.declaration?.diagnostics.filter((d) => d.severity === "error")).toEqual([]);
+    }
+  });
+
+  test("status", async () => {
+    const doc = await workspaceStatus({ cwd: FIXTURE, env: "dev" });
+    contract(statusSchema).expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.workspace).toMatchObject({ name: "reference", root: "reference-workspace" });
+    expect(doc.members.map((m) => m.name)).toEqual(["app", "delivery", "design-client", "design"]);
+  });
+
+  test("records, in the working tree and at HEAD", async () => {
+    const { expectValid } = contract(recordsSchema);
+    for (const at of [undefined, "HEAD"]) {
+      const doc = await queryRecords({ kind: "decisions/decision.kind.mjs", cwd: FIXTURE, at });
+      expectValid(doc);
+      if ("error" in doc) throw new Error(doc.error.message);
+      expect(doc.summary.invalid).toBe(0);
+      expect(doc.records.map((r) => r.id)).toContain("ref-001");
+    }
+  });
+});

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

@@ -0,0 +1,113 @@
+/**
+ * One closed list of reason codes (#2536, #2524 D15): every command's own
+ * list is a subset of `REASON_CODES`, together they cover it, the output
+ * schemas name nothing outside it, and no source file under `workspace/`
+ * emits a code outside it. The read-contract page documents every code.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./__fixtures__/contract-repo";
+import { MEMBER_RUN_REASON_CODES } from "./compose-graph";
+import { WORKSPACE_ERROR_CODES } from "./declaration";
+import { GRAPH_ERROR_CODES } from "./graph-cli";
+import { CHECK_CODES, CHECK_ERROR_CODES } from "./lineage-check";
+import { GROUP_REASON_CODES, MEMBER_REASON_CODES } from "./ls";
+import { isReasonCode, REASON_CODES, REASONS } from "./reason-codes";
+import { READ_ERROR_CODES, RECORD_REASON_CODES } from "./records";
+import { STATUS_ERROR_CODES, STATUS_REASON_CODES } from "./status";
+
+const HERE = import.meta.dirname;
+
+const PER_COMMAND: Record<string, readonly string[]> = {
+  WORKSPACE_ERROR_CODES,
+  MEMBER_REASON_CODES,
+  GROUP_REASON_CODES,
+  MEMBER_RUN_REASON_CODES,
+  GRAPH_ERROR_CODES,
+  CHECK_CODES,
+  CHECK_ERROR_CODES,
+  STATUS_REASON_CODES,
+  STATUS_ERROR_CODES,
+  RECORD_REASON_CODES,
+  READ_ERROR_CODES,
+};
+
+/** Every string in an `enum` under a property named `code`, anywhere in a schema. */
+function schemaCodes(node: unknown, underCode = false, out = new Set<string>()): Set<string> {
+  if (Array.isArray(node)) {
+    for (const n of node) schemaCodes(n, underCode, out);
+  } else if (node !== null && typeof node === "object") {
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "enum" && underCode) for (const e of v as unknown[]) out.add(String(e));
+      schemaCodes(v, k === "code" || (underCode && k !== "properties"), out);
+    }
+  }
+  return out;
+}
+
+function sourceFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const d of readdirSync(dir, { withFileTypes: true })) {
+    if (d.isDirectory() && d.name !== "__fixtures__") out.push(...sourceFiles(join(dir, d.name)));
+    else if (d.isFile() && d.name.endsWith(".ts") && !d.name.endsWith(".test.ts")) out.push(join(dir, d.name));
+  }
+  return out;
+}
+
+/** Codes that are someone else's: zod's issue codes. */
+const NOT_OURS = new Set(["custom"]);
+
+describe("the closed list of reason codes", () => {
+  test("has no duplicates, and every code says what it means", () => {
+    expect(new Set(REASON_CODES).size).toBe(REASON_CODES.length);
+    for (const c of REASON_CODES) {
+      expect(c).toMatch(/^[a-z]+(-[a-z0-9]+)*$/);
+      expect(REASONS[c].length).toBeGreaterThan(10);
+    }
+    expect(isReasonCode("dir-missing")).toBe(true);
+    expect(isReasonCode("toString")).toBe(false);
+  });
+
+  test("each command's list is a subset, and together they are the whole list", () => {
+    const union = new Set<string>();
+    for (const [name, codes] of Object.entries(PER_COMMAND)) {
+      for (const c of codes) {
+        expect(isReasonCode(c), `${name} has ${c}, which is not in reason-codes.ts`).toBe(true);
+        union.add(c);
+      }
+    }
+    expect([...union].sort()).toEqual([...REASON_CODES].sort());
+  });
+
+  test("the output schemas name exactly these codes", () => {
+    const named = new Set<string>();
+    for (const f of readdirSync(HERE).filter((f) => f.endsWith(".schema.json") && !f.startsWith("declaration") && !f.startsWith("workspace-kinds"))) {
+      for (const c of schemaCodes(JSON.parse(readFileSync(join(HERE, f), "utf-8")))) {
+        expect(isReasonCode(c), `${f} names ${c}, which is not in reason-codes.ts`).toBe(true);
+        named.add(c);
+      }
+    }
+    expect([...named].sort()).toEqual([...REASON_CODES].sort());
+  });
+
+  test("no source file emits a code outside the list", () => {
+    const emitted = /(?:\bcode:\s*|(?:WorkspaceReadError|RecordReadError|StatusError)\(\s*)"([a-z0-9-]+)"/g;
+    let seen = 0;
+    for (const file of sourceFiles(HERE)) {
+      const text = readFileSync(file, "utf-8");
+      for (const m of text.matchAll(emitted)) {
+        if (NOT_OURS.has(m[1])) continue;
+        seen++;
+        expect(isReasonCode(m[1]), `${file.slice(HERE.length + 1)} emits ${m[1]}, which is not in reason-codes.ts`).toBe(true);
+      }
+    }
+    expect(seen).toBeGreaterThan(30);
+  });
+
+  test("the read-contract page documents every code", () => {
+    const page = readFileSync(join(REPO, "docs", "src", "content", "docs", "reference", "workspace-read-contract.mdx"), "utf-8");
+    for (const c of REASON_CODES) expect(page, c).toContain(`| \`${c}\` |`);
+  });
+});

package/src/workspace/reason-codes.ts

@@ -0,0 +1,81 @@
+/**
+ * The workspace read contract's closed list of reason codes (#2536, #2524
+ * D15, ws-017, ws-020).
+ *
+ * Every code a `chant workspace` read prints is here: the error that stops a
+ * read, the reason an unreadable member, group, ledger or record is listed
+ * with, and the lineage lock findings of `check`. Each command's own list
+ * (`WORKSPACE_ERROR_CODES`, `MEMBER_REASON_CODES`, `STATUS_REASON_CODES`,
+ * `RECORD_REASON_CODES` and the rest) is a subset of this one, which the
+ * compiler checks through `satisfies`. `reason-codes.test.ts` checks that the
+ * output schemas and the source emit nothing outside it.
+ *
+ * The list is closed: a reader may switch on a code, and a new code is a
+ * contract change. Within contract version 1, before the floor release, codes
+ * may still be added; after it, a new code means a new contract version.
+ *
+ * `chant workspace check` also reports `WSP` ids. Those are the declaration
+ * check catalog (`checks.ts`), a separate closed list, and a finding whose
+ * cause is one of the codes here carries that code too.
+ */
+
+/** The version of the read contract this chant writes: the declaration format, the output schemas and these codes. */
+export const READ_CONTRACT_VERSION = 1;
+
+/** The first chant release that writes contract version 1. A reader that needs the contract refuses an older chant. */
+export const READ_CONTRACT_FLOOR = "0.81.0";
+
+/** Each code and what it means. The key order is the order the docs list them in. */
+export const REASONS = {
+  // Reading the declaration (ls, graph, check, status).
+  "declaration-missing": "No chant.workspace.json or .jsonc between the directory and the git root.",
+  "declaration-ambiguous": "Both chant.workspace.json and chant.workspace.jsonc exist.",
+  "declaration-unparseable": "The declaration is not valid JSON, or not valid JSONC for .jsonc.",
+  "declaration-invalid": "The declaration does not match its schema, repeats a name, or --member names no entry.",
+  "placement-invalid": "A member or group match breaks a placement rule.",
+  "reader-too-old": "The declaration's minReader is newer than the chant reading it.",
+  "root-chant-required": "The declaration pins a chant version other than the reader's, and that chant is not installed at the workspace root.",
+  // --at and git.
+  "not-a-git-repository": "--at, or a ledger read, needs a git repository and there is none.",
+  "revision-unknown": "--at names no commit.",
+  // status.
+  "environment-invalid": "An environment name that can't name a ledger directory.",
+  // A member or group that can't be read (ls, graph).
+  "dir-missing": "The member's directory does not exist.",
+  "unknown-kind": "No built-in kind or pinned package supplies the member's kind.",
+  "kind-probe-failed": "The member's directory is not what its kind reads.",
+  "no-matches": "An example group matches no directory holding a chant project.",
+  // A member graph leaves out (graph, and the other per-member commands).
+  "kind-not-run": "The member's kind is one the per-member commands don't run, such as other.",
+  "command-failed": "The member's own command exited with a failure.",
+  "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.",
+  // 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.",
+  // A record that isn't valid (records).
+  "record-unparseable": "No front matter, a YAML error, or a value outside the JSON subset of YAML.",
+  "record-schema-invalid": "The front matter does not match the kind's schema.",
+  "record-id-duplicate": "Another record earlier in path order has the same id.",
+  "record-supersedes-unknown": "A supersedes link names an id no record has.",
+  "record-supersedes-conflict": "A second closed record supersedes a record another one already superseded.",
+  // A records read that fails (records).
+  "kind-unreadable": "The record kind file is missing or could not be imported.",
+  "kind-invalid": "The record kind file exports no recordKind, or its shape is wrong.",
+  "schema-unreadable": "The schema file the record kind names is missing or is not JSON.",
+  "schema-id-mismatch": "The schema's $id differs from the id the record kind names.",
+  "schema-invalid": "The record schema itself does not compile.",
+  "location-missing": "The records directory does not exist, in the tree or at the revision.",
+  // 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.",
+} as const;
+
+export type ReasonCode = keyof typeof REASONS;
+
+/** Every code, in the order of {@link REASONS}. */
+export const REASON_CODES = Object.keys(REASONS) as ReasonCode[];
+
+export function isReasonCode(value: unknown): value is ReasonCode {
+  return typeof value === "string" && Object.prototype.hasOwnProperty.call(REASONS, value);
+}

package/src/workspace/records-cli.ts

@@ -1,6 +1,7 @@
 /**
- * `chant workspace records --kind <path> [--current] [--at <rev>] [--json]`,
- * the first-test slice of the records query (#2546, #2536).
+ * `chant workspace records --kind <path> [--current] [--at <rev>] [--base <rev>]
+ * [--require attested] [--json]`, the first-test slice of the records query
+ * (#2546, #2536), with each record's provenance level (#2547).
  *
  * It reads every record the kind file locates and prints them, with reason
  * codes for any that are invalid. An invalid record never fails the command:
@@ -11,11 +12,14 @@
  * nothing is inferred (#2525 rule 1).
  */
 
+import { realpathSync } from "node:fs";
 import { relative } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { gitRevisionSource, gitRoot, resolveRevision, workingTreeSource } from "./record-source";
 import { loadRecordKind, readRecords, RecordReadError, type ReadErrorCode, type RecordEntry } from "./records";
+import { activeAttestors, type ProvenanceLevel } from "./trust/attestor";
+import { policyAtBase, recordProvenance, resolveBase, type BaseSource, type RecordProvenance } from "./trust/provenance";
 
 /** The version of the `records` output this chant writes. */
 export const RECORDS_CONTRACT_VERSION = 1;
@@ -23,16 +27,35 @@ export const RECORDS_CONTRACT_VERSION = 1;
 /** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
 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] [--at <rev>] [--json]";
+const USAGE = "chant workspace records --kind <kind file> [--current] [--at <rev>] [--base <rev>] [--require attested] [--json]";
+
+/** Exit code when the read worked and a record falls below `--require`. */
+export const EXIT_BELOW_REQUIRED = 2;
 
 export interface RecordsQuery {
   kind: string;
   current?: boolean;
   at?: string;
+  /** The revision the trust policy is read at (#2547). Defaults to the target branch tip. */
+  base?: string;
   /** Where `kind` is resolved from and the repository is found. */
   cwd: string;
 }
 
+/** A record as the output carries it: the entry plus its provenance (#2547). */
+export type RecordView = RecordEntry & { provenance: RecordProvenance };
+
+/** Where provenance was judged from (#2547). */
+export interface TrustView {
+  /** The full commit id the policy was read at, or null when there is no base. */
+  base: string | null;
+  baseFrom: BaseSource | null;
+  /** Whether a signers file exists at base. False means every record is `unattested`. */
+  active: boolean;
+  signersPath: string;
+  problems: string[];
+}
+
 /** The `records` output: a result, or a failure with one error code. */
 export type RecordsDocument =
   | {
@@ -41,17 +64,21 @@ export type RecordsDocument =
       kind: { name: string; schema: string; file: string };
       at: string | null;
       current: boolean;
-      records: RecordEntry[];
+      trust: TrustView;
+      records: RecordView[];
       summary: { total: number; valid: number; invalid: number; superseded: number };
     }
   | { $schema: string; contract: number; error: { code: ReadErrorCode; message: string } };
 
 /** Run the query and build the document `--json` prints. Never throws a {@link RecordReadError}. */
 export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument> {
-  const top = gitRoot(query.cwd);
-  const root = top ?? query.cwd;
+  // git reports its top through symlinks resolved (/var is /private/var on
+  // macOS), so the directory has to be too, or record paths leave the repository.
+  const cwd = realpathOr(query.cwd);
+  const top = gitRoot(cwd);
+  const root = top ?? cwd;
   try {
-    const loaded = await loadRecordKind(query.kind, query.cwd);
+    const loaded = await loadRecordKind(query.kind, cwd);
     let at: string | null = null;
     let source = workingTreeSource(root);
     if (query.at !== undefined) {
@@ -60,6 +87,16 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       source = gitRevisionSource(top, at);
     }
     const result = await readRecords(loaded, { root, source, current: !!query.current });
+    // Provenance, judged by the policy at base and never by the tree read (#2547).
+    const base = top ? resolveBase(top, query.base) : { commit: null, from: null };
+    const policy = top ? policyAtBase(top, base) : policyAtBase(root, base);
+    const provenance = recordProvenance({
+      repo: top,
+      policy,
+      at,
+      paths: result.records.map((r) => r.path),
+      attestors: policy.active ? await activeAttestors() : [],
+    });
     return {
       $schema: RECORDS_OUTPUT_SCHEMA_ID,
       contract: RECORDS_CONTRACT_VERSION,
@@ -70,7 +107,8 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
       },
       at,
       current: !!query.current,
-      records: result.records,
+      trust: { base: base.commit, baseFrom: base.from, active: policy.active, signersPath: policy.signersPath, problems: policy.problems },
+      records: result.records.map((r) => ({ ...r, provenance: provenance.get(r.path)! })),
       summary: result.summary,
     };
   } catch (err) {
@@ -85,7 +123,11 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     console.error(formatError({ message: "--kind <kind file> is required", hint: USAGE }));
     return 1;
   }
-  const doc = await queryRecords({ kind: args.kind, current: args.current, at: args.at, cwd: process.cwd() });
+  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;
+  }
+  const doc = await queryRecords({ kind: args.kind, current: args.current, at: args.at, base: args.base, cwd: process.cwd() });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
@@ -93,10 +135,39 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
   } else {
     console.log(formatRecords(doc.records, doc.summary, doc.at));
   }
-  return "error" in doc ? 1 : 0;
+  if ("error" in doc) return 1;
+  if (args.require) {
+    const below = belowRequired(doc.records, args.require);
+    if (below.length > 0) {
+      console.error(
+        formatError({
+          message: `${below.length} of ${doc.records.length} records are not ${args.require}: ${below
+            .slice(0, 5)
+            .map((r) => `${r.path} (${r.provenance.level})`)
+            .join(", ")}${below.length > 5 ? ", ..." : ""}`,
+          hint: doc.trust.active ? "run with --json to see each record's reason" : `there is no signers file (${doc.trust.signersPath}) at base`,
+        }),
+      );
+      return EXIT_BELOW_REQUIRED;
+    }
+  }
+  return 0;
+}
+
+function realpathOr(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+/** Records whose provenance falls below `required`. Only `attested` can be required. */
+export function belowRequired(records: RecordView[], required: ProvenanceLevel): RecordView[] {
+  return records.filter((r) => r.provenance.level !== required);
 }
 
-function formatRecords(records: RecordEntry[], summary: { total: number; valid: number; invalid: number; superseded: number }, at: string | null): string {
+function formatRecords(records: RecordView[], summary: { total: number; valid: number; invalid: number; superseded: number }, at: string | null): string {
   const lines: string[] = [];
   const idWidth = Math.max(2, ...records.map((r) => (r.id ?? "-").length));
   const stateWidth = Math.max(5, ...records.map((r) => (r.state ?? "-").length));
@@ -104,7 +175,8 @@ function formatRecords(records: RecordEntry[], summary: { total: number; valid:
     const title = typeof r.data?.title === "string" ? r.data.title : r.path;
     const flag = r.valid ? "" : "  INVALID";
     const superseded = r.supersededBy ? `  superseded by ${r.supersededBy}` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${flag}`);
+    const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${attested}${flag}`);
     for (const reason of r.reasons) lines.push(`${" ".repeat(idWidth + 2)}${reason.code}: ${reason.message} (${r.path})`);
   }
   lines.push(
@@ -113,13 +185,13 @@ function formatRecords(records: RecordEntry[], summary: { total: number; valid:
   return lines.join("\n");
 }
 
-/** `chant workspace <anything else>`: only `records` exists so far. */
+/** `chant workspace <anything else>`. */
 export async function runWorkspaceUnknown(ctx: CommandContext): Promise<number> {
   const sub = ctx.args.path && ctx.args.path !== "." ? ctx.args.path : "";
   console.error(
     formatError({
       message: sub ? `Unknown workspace subcommand: ${sub}` : "chant workspace needs a subcommand",
-      hint: `Only records exists so far: ${USAGE}`,
+      hint: `Workspace subcommands: audit, build, check, graph, init, lineage, lint, ls, records, status, upgrade, verify. Run "chant --help" for their options.`,
     }),
   );
   return 1;