@intentius/chant 0.124.46 → 0.124.48

package/src/lifecycle/ledger-read.ts

@@ -0,0 +1,195 @@
+/**
+ * `chant ledger <table>` (#4363): the rows of one ledger on `chant/lifecycle`
+ * as a JSON read contract (`workspace/ledger.schema.json`), filtered with
+ * `--where`, `--since` and `--at` instead of SQL.
+ *
+ * The tables, their columns and the rows are the ones `chant query` loads
+ * (`./query.ts` {@link QUERY_TABLES}, {@link loadQueryData}), so the two
+ * agree on every row. A column `chant query` keeps as JSON text is an object
+ * or array here. No SQL engine loads.
+ *
+ * `--since <time>` keeps the rows whose time column ({@link LEDGER_TIME_COLUMN})
+ * is at or after it. `--at <rev>` reads the ledger as the commit `rev` of
+ * `chant/lifecycle` held it ({@link revisionLedgerReadPort}).
+ *
+ * Everything here but {@link revisionLedgerReadPort} is pure over a
+ * {@link LedgerReadPort}, so a product that reads the branch its own way
+ * (terragucci, behold) supplies its own port.
+ */
+import { execFileSync } from "node:child_process";
+import { FilterError, matchesWhere, parseSince, parseWhere, type FilterFields, type FilterFieldType } from "../read-filter";
+import type { ReasonCode } from "../workspace/reason-codes";
+import type { LedgerReadPort } from "./ledger-port";
+import { loadQueryData, QUERY_TABLES, type QueryLedger, type QueryRow, type QueryTable } from "./query";
+
+/** The version of the `ledger` document this chant writes. */
+export const LEDGER_READ_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for `chant ledger --json`. */
+export const LEDGER_READ_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ledger/v1/ledger.schema.json";
+
+/** The tables, in the order `chant query` lists them. */
+export const LEDGER_TABLES = Object.keys(QUERY_TABLES) as QueryTable[];
+
+/** The column `--since` compares, per table; null for a table with no time of its own. */
+export const LEDGER_TIME_COLUMN: Record<QueryTable, string | null> = {
+  resources: "observed_at",
+  snapshots: "observed_at",
+  runs: "started",
+  gates: "timestamp",
+  deploys: "timestamp",
+  releases: null,
+  cuts: "timestamp",
+};
+
+/** The columns that hold JSON, which this read prints parsed. */
+const JSON_COLUMNS = new Set(["attributes", "labels", "outcomes", "promoted_from", "restores", "redeploys", "artifacts"]);
+/** The columns that hold an ISO instant. */
+const TIME_COLUMNS = new Set(["last_updated", "observed_at", "started", "ended", "timestamp", "expires_at"]);
+/** INTEGER columns that hold 0 or 1, which this read prints as booleans. */
+const BOOLEAN_COLUMNS = new Set(["signed", "empty"]);
+
+/** The fields `--where` takes on a table: its columns, typed. */
+export function ledgerFields(table: QueryTable): FilterFields {
+  const out: Record<string, FilterFieldType> = {};
+  for (const [name, sqlType] of QUERY_TABLES[table]) {
+    out[name] = BOOLEAN_COLUMNS.has(name) ? "boolean" : sqlType === "INTEGER" ? "number" : JSON_COLUMNS.has(name) ? "json" : TIME_COLUMNS.has(name) ? "time" : "text";
+  }
+  return out;
+}
+
+export type LedgerValue = string | number | boolean | null | Record<string, unknown> | unknown[];
+export type LedgerRow = Record<string, LedgerValue>;
+
+/** The row as the contract prints it: JSON columns parsed, 0/1 columns as booleans. */
+function contractRow(table: QueryTable, row: QueryRow): LedgerRow {
+  const out: LedgerRow = {};
+  for (const [name] of QUERY_TABLES[table]) {
+    const v = row[name] ?? null;
+    if (v !== null && JSON_COLUMNS.has(name) && typeof v === "string") {
+      try {
+        out[name] = JSON.parse(v) as LedgerValue;
+      } catch {
+        out[name] = v;
+      }
+    } else if (BOOLEAN_COLUMNS.has(name) && typeof v === "number") out[name] = v === 1;
+    else out[name] = v;
+  }
+  return out;
+}
+
+export interface LedgerReadOptions {
+  where?: readonly string[];
+  /** An ISO date or time, or a span back from now such as `7d`. */
+  since?: string;
+  /** The revision of `chant/lifecycle` the ports read, as given; only echoed here. */
+  at?: string | null;
+  now?: Date;
+}
+
+export type LedgerReadDocument =
+  | {
+      $schema: string;
+      contract: number;
+      table: QueryTable;
+      /** The table's columns, in order. */
+      columns: string[];
+      at: string | null;
+      filter: { where: string[]; since: string | null };
+      /** Rows in the table before the filter. */
+      total: number;
+      rows: LedgerRow[];
+      /** Lines and files of this table that could not be read as their kind, left out. */
+      malformed: number;
+    }
+  | { $schema: string; contract: number; error: { code: LedgerReadErrorCode; message: string } };
+
+/** Why the read printed no rows. Closed. */
+export const LEDGER_READ_ERROR_CODES = ["filter-invalid", "table-unknown", "revision-unknown", "ledger-unreadable"] as const satisfies readonly ReasonCode[];
+export type LedgerReadErrorCode = (typeof LEDGER_READ_ERROR_CODES)[number];
+
+const head = { $schema: LEDGER_READ_SCHEMA_ID, contract: LEDGER_READ_CONTRACT_VERSION };
+
+/** A failure document. */
+export function ledgerReadFailure(code: LedgerReadErrorCode, message: string): LedgerReadDocument {
+  return { ...head, error: { code, message } };
+}
+
+/** Read one table from the ledgers and filter it. A bad table or filter is a failure document, before anything is read. */
+export async function readLedgerTable(table: string, ledgers: readonly QueryLedger[] | (() => Promise<readonly QueryLedger[]>), opts: LedgerReadOptions = {}): Promise<LedgerReadDocument> {
+  if (!(LEDGER_TABLES as string[]).includes(table)) return ledgerReadFailure("table-unknown", `no table ${JSON.stringify(table)}; the tables are ${LEDGER_TABLES.join(", ")}`);
+  const t = table as QueryTable;
+  let clauses;
+  let since: string | null = null;
+  try {
+    clauses = parseWhere(opts.where ?? [], ledgerFields(t), opts.now);
+    if (opts.since !== undefined) {
+      if (LEDGER_TIME_COLUMN[t] === null) throw new FilterError(`--since: ${t} has no time column; filter it with --where`);
+      since = parseSince(opts.since, opts.now);
+    }
+  } catch (err) {
+    if (err instanceof FilterError) return ledgerReadFailure("filter-invalid", err.message);
+    throw err;
+  }
+  const load = await loadQueryData(typeof ledgers === "function" ? await ledgers() : ledgers);
+  const all = load.data[t].map((r) => contractRow(t, r));
+  const timeCol = LEDGER_TIME_COLUMN[t];
+  const sinceMs = since === null ? null : Date.parse(since);
+  const rows = all.filter((r) => {
+    if (sinceMs !== null && timeCol !== null) {
+      const v = r[timeCol];
+      if (typeof v !== "string" || !(Date.parse(v) >= sinceMs)) return false;
+    }
+    return matchesWhere(r, clauses);
+  });
+  return {
+    ...head,
+    table: t,
+    columns: QUERY_TABLES[t].map(([c]) => c),
+    at: opts.at ?? null,
+    filter: { where: [...(opts.where ?? [])], since },
+    total: all.length,
+    rows,
+    malformed: load.malformed[t],
+  };
+}
+
+/** Thrown by {@link resolveLedgerRevision} for a revision git can't resolve. */
+export class LedgerRevisionError extends Error {}
+
+/** The commit `rev` names in the repository at `cwd`. Throws a {@link LedgerRevisionError}. */
+export function resolveLedgerRevision(cwd: string, rev: string): string {
+  try {
+    return execFileSync("git", ["rev-parse", "--verify", "--quiet", `${rev}^{commit}`], { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    throw new LedgerRevisionError(`--at ${rev} names no commit here; give a commit of chant/lifecycle, such as chant/lifecycle~3`);
+  }
+}
+
+/**
+ * A port over the ledger as the commit `commit` holds it, under `prefix`
+ * (`""`, or `_members/<member>/` per level). It never fetches.
+ */
+export function revisionLedgerReadPort(cwd: string, commit: string, prefix: string): LedgerReadPort {
+  const git = (args: string[]): string | null => {
+    try {
+      return execFileSync("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 256 * 1024 * 1024 });
+    } catch {
+      return null;
+    }
+  };
+  const lsTree = (path: string, nameOnly: boolean): string[] => {
+    const spec = path === "" ? commit : `${commit}:${path}`;
+    const out = git(["ls-tree", "--full-tree", ...(nameOnly ? ["--name-only"] : []), spec]);
+    return out === null ? [] : out.split("\n").filter(Boolean);
+  };
+  return {
+    read: async (dir, file) => git(["show", `${commit}:${prefix}${dir}/${file}`]),
+    list: async (dir) => lsTree(`${prefix}${dir}`, true),
+    trees: async () =>
+      lsTree(prefix.replace(/\/$/, ""), false)
+        .map((line) => /^\d+\s+(\w+)\s+[0-9a-f]+\t(.+)$/.exec(line))
+        .filter((m): m is RegExpExecArray => m !== null && m[1] === "tree")
+        .map((m) => m[2]),
+  };
+}

package/src/lifecycle/release-workstation.ts

@@ -70,6 +70,30 @@ export function resolveTrunk(cwd: string, greenBranch: string | null): Trunk {
   return { remote: RELEASE_REMOTE, branch: "main", from: "default" };
 }
 
+/**
+ * {@link checkOnTrunk} across the branches `ci.green` judges (#4325): the
+ * trunk `commit` is on, `trunk` itself or one of `others` (the declaration's
+ * further green branches, which `ci.branches` routes members to). A commit on
+ * none of them is refused with the first trunk's error.
+ */
+export function checkOnGreenBranches(cwd: string, commit: string, trunk: Trunk, others: readonly string[]): Trunk {
+  try {
+    checkOnTrunk(cwd, commit, trunk);
+    return trunk;
+  } catch (err) {
+    for (const branch of others) {
+      const routed: Trunk = { ...trunk, branch };
+      try {
+        checkOnTrunk(cwd, commit, routed);
+        return routed;
+      } catch {
+        // Not on this one either; the next, then the first branch's error.
+      }
+    }
+    throw err;
+  }
+}
+
 /**
  * Refuse `commit` unless it is reachable from `<remote>/<branch>` as this
  * clone knows it. A commit on the local branch only is `release-commit-not-pushed`;

package/src/lifecycle/run-ledger.ts

@@ -39,7 +39,7 @@ import { sortedJsonReplacer } from "../utils";
 import type { OpConfig } from "../op/types";
 import type { StepRecord } from "../op/local-executor";
 import { opRunFailureOf, type OpRunRecord, type OpRunRecordInput, type OpRunPhaseRecord, type OpRunStepRecord } from "../op/runtime";
-import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError, type LedgerLocation } from "./git";
 
 /** Prefix folding the per-op run ledgers into one flat name under `<env>/`. See the module doc. */
 const PREFIX = "runs__";
@@ -95,6 +95,8 @@ export function buildRunRecord(
     runOrigin?: OpRunRecord["runOrigin"];
     /** Each phase's wall-clock time, by name, as the executor measured it. */
     phaseDurations?: Record<string, number>;
+    /** The workspace run that started this one (#2554). */
+    workspaceRun?: OpRunRecord["workspaceRun"];
   },
 ): OpRunRecordInput {
   const phases: OpRunPhaseRecord[] = [];
@@ -145,6 +147,7 @@ export function buildRunRecord(
     ...(times.resumed ? { resumed: times.resumed } : {}),
     ...(times.gitSha ? { gitSha: times.gitSha } : {}),
     ...(times.runOrigin ? { runOrigin: times.runOrigin } : {}),
+    ...(times.workspaceRun ? { workspaceRun: times.workspaceRun } : {}),
   };
 }
 
@@ -193,7 +196,7 @@ export async function appendRunRecord(
 export async function readRunLedger(
   environment: string,
   op: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<{ records: OpRunRecord[]; malformed: number }> {
   const content = await readBlobFromPath(environment, fileFor(op), opts);
   if (!content) return { records: [], malformed: 0 };

package/src/lint/cross-root.test.ts

@@ -0,0 +1,122 @@
+import { describe, test, expect } from "vitest";
+import {
+  runPostSynthChecks,
+  runCrossRootChecks,
+  createCrossRootContext,
+  isPostSynthCheck,
+  isCrossRootCheck,
+  type CrossRootCheck,
+  type CrossRootInput,
+  type PostSynthCheck,
+} from "./post-synth";
+
+function buildResult(outputs: Record<string, string> = {}, entities: Record<string, unknown> = {}) {
+  const out = new Map(Object.entries(outputs));
+  return {
+    outputs: out,
+    entities: new Map(Object.entries(entities)) as Map<string, never>,
+    warnings: [] as string[],
+    errors: [] as Array<{ message: string; name: string }>,
+    sourceFileCount: 0,
+  };
+}
+
+const secretRoot: CrossRootInput = {
+  root: "workloads",
+  buildResult: buildResult({ k8s: "kind: Secret\nmetadata:\n  name: db\n" }, { dbSecret: {} }),
+};
+const fluxRoot: CrossRootInput = {
+  root: "flux",
+  dir: "/repo/flux",
+  buildResult: buildResult({ k8s: "kind: Kustomization\nmetadata:\n  name: apps\n---\nkind: GitRepository\n" }),
+};
+
+const kindsAcross: CrossRootCheck = {
+  id: "XR001",
+  description: "records kinds across roots",
+  scope: "cross-root",
+  check(ctx) {
+    return ctx.docs.map((d) => ({
+      checkId: "XR001",
+      severity: "info" as const,
+      message: String((d.value as { kind?: string }).kind),
+      root: d.root,
+    }));
+  },
+};
+
+describe("cross-root post-synth checks (chant #1939)", () => {
+  test("a per-build run never calls a cross-root check", () => {
+    let called = false;
+    const xr = { ...kindsAcross, check: () => { called = true; return []; } };
+    const diags = runPostSynthChecks([xr as unknown as PostSynthCheck], buildResult());
+    expect(diags).toEqual([]);
+    expect(called).toBe(false);
+  });
+
+  test("guards keep the two kinds apart", () => {
+    const plain: PostSynthCheck = { id: "P", description: "p", check: () => [] };
+    expect(isPostSynthCheck(kindsAcross)).toBe(false);
+    expect(isCrossRootCheck(kindsAcross)).toBe(true);
+    expect(isPostSynthCheck(plain)).toBe(true);
+    expect(isCrossRootCheck(plain)).toBe(false);
+  });
+
+  test("docs are the union across roots, tagged by root", () => {
+    const diags = runCrossRootChecks([kindsAcross], [secretRoot, fluxRoot]);
+    expect(diags.map((d) => `${d.root}:${d.message}`)).toEqual([
+      "workloads:Secret",
+      "flux:Kustomization",
+      "flux:GitRepository",
+    ]);
+  });
+
+  test("a cross-root check can see that the other half lives in another root", () => {
+    const needsDecryption: CrossRootCheck = {
+      id: "XR002",
+      description: "a Secret needs a Kustomization in some root",
+      scope: "cross-root",
+      check(ctx) {
+        const hasKs = ctx.docs.some((d) => (d.value as { kind?: string }).kind === "Kustomization");
+        return ctx.docs
+          .filter((d) => (d.value as { kind?: string }).kind === "Secret" && !hasKs)
+          .map((d) => ({ checkId: "XR002", severity: "warning" as const, message: "no Kustomization in any root", root: d.root }));
+      },
+    };
+    expect(runCrossRootChecks([needsDecryption], [secretRoot, fluxRoot])).toEqual([]);
+    expect(runCrossRootChecks([needsDecryption], [secretRoot])).toEqual([
+      { checkId: "XR002", severity: "warning", message: "no Kustomization in any root", root: "workloads" },
+    ]);
+  });
+
+  test("roots stay apart and each is a PostSynthContext", () => {
+    const ctx = createCrossRootContext([secretRoot, fluxRoot], { env: "prod" });
+    expect(ctx.roots.map((r) => r.root)).toEqual(["workloads", "flux"]);
+    expect(ctx.root("flux")?.dir).toBe("/repo/flux");
+    expect(ctx.root("flux")?.projectDir).toBe("/repo/flux");
+    expect(ctx.root("flux")?.docs).toHaveLength(2);
+    expect(ctx.root("workloads")?.env).toBe("prod");
+    expect(ctx.root("missing")).toBeUndefined();
+    expect(ctx.entities).toEqual([{ root: "workloads", name: "dbSecret", entity: {} }]);
+    expect(ctx.env).toBe("prod");
+  });
+
+  test("the union is parsed lazily, once", () => {
+    const ctx = createCrossRootContext([secretRoot, fluxRoot]);
+    expect(ctx.docs).toBe(ctx.docs);
+    expect(ctx.entities).toBe(ctx.entities);
+  });
+
+  test("plain checks in the list are skipped, and nothing is built when none is cross-root", () => {
+    let called = false;
+    const plain: PostSynthCheck = { id: "P", description: "p", check: () => { called = true; return []; } };
+    // Duplicate root names would throw if a context were built.
+    expect(runCrossRootChecks([plain], [secretRoot, secretRoot])).toEqual([]);
+    expect(called).toBe(false);
+  });
+
+  test("root names must be unique and non-empty", () => {
+    expect(() => createCrossRootContext([secretRoot, secretRoot])).toThrow(/appears twice/);
+    expect(() => createCrossRootContext([{ ...secretRoot, root: "" }])).toThrow(/needs a name/);
+  });
+});

package/src/lint/discover.ts

@@ -143,6 +143,8 @@ function isPostSynthCheck(obj: unknown): obj is PostSynthCheck {
     typeof o.description === "string" &&
     typeof o.check === "function" &&
     // Exclude LintRules (which also have check) by checking for PostSynthCheck-specific fields
-    typeof o.severity !== "string"
+    typeof o.severity !== "string" &&
+    // A cross-root check (chant #1939) is not a per-build check.
+    o.scope !== "cross-root"
   );
 }

package/src/lint/post-synth.ts

@@ -192,6 +192,11 @@ export interface PostSynthDiagnostic {
     /** Where it is missing from (e.g. a root module name). */
     scope: string;
   };
+  /**
+   * The build root the finding is about, set by a {@link CrossRootCheck}
+   * (chant #1939). Absent from a per-build finding.
+   */
+  root?: string;
 }
 
 /**
@@ -214,16 +219,26 @@ export interface PostSynthCheck {
    * new check would otherwise change the audit output of every project.
    */
   auditOptIn?: boolean;
+  /**
+   * `"build"`, the default: the check sees one build. A check that reads
+   * across build roots is a {@link CrossRootCheck} instead (chant #1939).
+   */
+  scope?: "build";
 }
 
-/** Structural type guard — used to collect project-authored policy checks. */
+/**
+ * Structural type guard — used to collect project-authored policy checks.
+ * A {@link CrossRootCheck} is not a `PostSynthCheck`, so a policy module or a
+ * lexicon's check directory that exports one never puts it in a per-build run.
+ */
 export function isPostSynthCheck(value: unknown): value is PostSynthCheck {
   return (
     typeof value === "object" &&
     value !== null &&
     typeof (value as PostSynthCheck).id === "string" &&
     typeof (value as PostSynthCheck).description === "string" &&
-    typeof (value as PostSynthCheck).check === "function"
+    typeof (value as PostSynthCheck).check === "function" &&
+    (value as { scope?: unknown }).scope !== "cross-root"
   );
 }
 
@@ -259,11 +274,206 @@ export function runPostSynthChecks(
 
   const diagnostics: PostSynthDiagnostic[] = [];
   for (const check of checks) {
+    // chant #1939: a cross-root check never runs in a per-build pass, even
+    // when a caller hands one over untyped. runCrossRootChecks runs it.
+    if ((check as { scope?: unknown }).scope === "cross-root") continue;
     diagnostics.push(...check.check(ctx));
   }
   return diagnostics;
 }
 
+// ---------------------------------------------------------------------------
+// Cross-build-root mode (chant #1939)
+// ---------------------------------------------------------------------------
+
+/**
+ * One build root handed to {@link runCrossRootChecks}: a name, and the build
+ * result the caller already has for it. The caller decides what a root is
+ * (a workspace member, a project directory, an environment's build) and
+ * builds it; this module never builds or reads the disk.
+ */
+export interface CrossRootInput {
+  /**
+   * The root's name, unique within one run. A workspace member's name, or a
+   * project-relative path. Findings name it in {@link PostSynthDiagnostic.root}.
+   */
+  root: string;
+  /** The root's directory, when it has one. */
+  dir?: string;
+  /** The environment this root was built for, when known. */
+  env?: string;
+  buildResult: PostSynthContext["buildResult"];
+  projectConfig?: Record<string, unknown>;
+}
+
+/**
+ * One build root as a cross-root check sees it: an ordinary
+ * {@link PostSynthContext} over that root's build, so a per-build helper
+ * (k8s's `allManifests(ctx)`) works on it unchanged, plus its name.
+ */
+export interface BuildRootView extends PostSynthContext {
+  readonly root: string;
+  readonly dir?: string;
+  readonly docs: OutputDoc[];
+}
+
+/** An {@link OutputDoc} tagged with the build root it came from. */
+export interface RootedOutputDoc extends OutputDoc {
+  root: string;
+}
+
+/**
+ * A link between two build roots, as the caller knows it (chant #2549): in a
+ * workspace, a member link from the declaration or one the members' graphs
+ * surface. A cross-root check that compares what the outputs say with what
+ * was written down reads these from {@link CrossRootContext.links}.
+ */
+export interface CrossRootLink {
+  consumer: string;
+  producer: string;
+  output: string;
+  /** How the link was found: `declared`, `kind-reader`, or `inferred:<rule>` for one the roots' graphs surface. */
+  origin: string;
+  /** The consumer's parameter an inferred link feeds; null or absent for a declared one. */
+  input?: string | null;
+  /** Whether the link resolved against the producer's outputs, as the caller judged it. */
+  status?: string;
+}
+
+/** An entity tagged with the build root that declared it. */
+export interface RootedEntity {
+  root: string;
+  name: string;
+  entity: Declarable;
+}
+
+/**
+ * Context provided to a {@link CrossRootCheck}. `roots` keeps every root's
+ * build apart; `docs` and `entities` are the union across roots, each entry
+ * tagged with its root, built lazily on first access.
+ */
+export interface CrossRootContext {
+  /** Every root in the run, in the order the caller gave them. */
+  readonly roots: readonly BuildRootView[];
+  /** Look a root up by name. */
+  root(name: string): BuildRootView | undefined;
+  /** Every root's parsed output documents, tagged by root. Lazy. */
+  readonly docs: readonly RootedOutputDoc[];
+  /** Every root's entities, tagged by root. Lazy. */
+  readonly entities: readonly RootedEntity[];
+  /** The run's environment, when the caller set one for the whole run. */
+  readonly env?: string;
+  readonly activityContracts?: ReadonlyMap<string, ActivityContract>;
+  /** The links between roots the caller passed (#2549), or absent when it passed none. */
+  readonly links?: readonly CrossRootLink[];
+}
+
+/** What a cross-root run takes besides its roots. */
+export interface CrossRootOptions {
+  env?: string;
+  activityContracts?: ReadonlyMap<string, ActivityContract>;
+  /** The links between roots (#2549), handed to every check as {@link CrossRootContext.links}. */
+  links?: readonly CrossRootLink[];
+}
+
+/**
+ * A check that reads across build roots (chant #1939). It declares
+ * `scope: "cross-root"`, and only {@link runCrossRootChecks} runs it:
+ * `chant build`, `chant lint` and every other per-build pass skip it, so a
+ * project that never asks for a cross-root run pays nothing for it.
+ */
+export interface CrossRootCheck {
+  id: string;
+  description: string;
+  scope: "cross-root";
+  check(ctx: CrossRootContext): PostSynthDiagnostic[];
+  /** As {@link PostSynthCheck.auditOptIn}. */
+  auditOptIn?: boolean;
+}
+
+/** Structural type guard for {@link CrossRootCheck}. */
+export function isCrossRootCheck(value: unknown): value is CrossRootCheck {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as CrossRootCheck).id === "string" &&
+    typeof (value as CrossRootCheck).description === "string" &&
+    typeof (value as CrossRootCheck).check === "function" &&
+    (value as CrossRootCheck).scope === "cross-root"
+  );
+}
+
+/**
+ * Build the {@link CrossRootContext} for a set of roots. Exported for tests
+ * and for a caller that runs checks itself; most callers want
+ * {@link runCrossRootChecks}. Throws on an empty or duplicate root name.
+ */
+export function createCrossRootContext(
+  inputs: readonly CrossRootInput[],
+  opts?: CrossRootOptions,
+): CrossRootContext {
+  const seen = new Set<string>();
+  const roots: BuildRootView[] = inputs.map((input) => {
+    if (input.root.length === 0) throw new Error("cross-root run: a build root needs a name");
+    if (seen.has(input.root)) throw new Error(`cross-root run: build root "${input.root}" appears twice`);
+    seen.add(input.root);
+    const getDocs = createDocsAccessor(input.buildResult.outputs);
+    const env = input.env ?? opts?.env;
+    return {
+      root: input.root,
+      ...(input.dir ? { dir: input.dir, projectDir: input.dir } : {}),
+      outputs: input.buildResult.outputs,
+      entities: input.buildResult.entities,
+      env,
+      buildResult: input.buildResult,
+      ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
+      ...(input.projectConfig ? { projectConfig: input.projectConfig } : {}),
+      get docs(): OutputDoc[] {
+        return getDocs();
+      },
+    };
+  });
+  const byName = new Map(roots.map((r) => [r.root, r]));
+  let docs: RootedOutputDoc[] | undefined;
+  let entities: RootedEntity[] | undefined;
+  return {
+    roots,
+    root: (name) => byName.get(name),
+    get docs(): readonly RootedOutputDoc[] {
+      docs ??= roots.flatMap((r) => r.docs.map((d) => ({ ...d, root: r.root })));
+      return docs;
+    },
+    get entities(): readonly RootedEntity[] {
+      entities ??= roots.flatMap((r) =>
+        [...r.entities].map(([name, entity]) => ({ root: r.root, name, entity })),
+      );
+      return entities;
+    },
+    ...(opts?.env ? { env: opts.env } : {}),
+    ...(opts?.activityContracts ? { activityContracts: opts.activityContracts } : {}),
+    ...(opts?.links ? { links: opts.links } : {}),
+  };
+}
+
+/**
+ * Run the cross-root checks in `checks` over `roots` (chant #1939). Anything
+ * in `checks` that is not a {@link CrossRootCheck} is skipped, so a caller can
+ * pass a lexicon's whole check list. With no cross-root check to run it
+ * returns at once, without building a context.
+ */
+export function runCrossRootChecks(
+  checks: ReadonlyArray<CrossRootCheck | PostSynthCheck>,
+  roots: readonly CrossRootInput[],
+  opts?: CrossRootOptions,
+): PostSynthDiagnostic[] {
+  const selected = checks.filter(isCrossRootCheck);
+  if (selected.length === 0) return [];
+  const ctx = createCrossRootContext(roots, opts);
+  const diagnostics: PostSynthDiagnostic[] = [];
+  for (const check of selected) diagnostics.push(...check.check(ctx));
+  return diagnostics;
+}
+
 // chant #1138 — `applyConfiguredSeverity` (the `lint.rules` severity-override
 // pass over a set of `PostSynthDiagnostic`s) lives in `./config.ts`, not here,
 // even though it operates on this module's own type. This file is a leaf:

package/src/lint/rules/op/index.ts

@@ -28,6 +28,8 @@ export { ops016 } from "./ops016-gate-resume";
 export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias";
 export { ops018 } from "./ops018-shell-image-digest";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http";
+// OPS019 (#2554) reads across members, so it is a cross-root check that only `chant workspace run` runs.
+export { ops019Check, parseWorkspaceOpTarget, formatWorkspaceOpTarget, OPS019_ID, type WorkspaceOpTarget } from "./ops019-workspace-op-target";
 
 export interface CoreOpCheckOptions {
   /** `decide.backends` from the project's chant.config, for SYS010 (#2828). */