@intentius/chant 0.124.45 → 0.124.48

package/src/lifecycle/ledger-read.test.ts

@@ -0,0 +1,107 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, it } from "vitest";
+import type { LedgerReadPort } from "./ledger-port";
+import { ledgerFields, readLedgerTable, resolveLedgerRevision, revisionLedgerReadPort, LedgerRevisionError } from "./ledger-read";
+
+const validate = new Ajv2020({ strict: false, allErrors: true }).compile(JSON.parse(readFileSync(join(__dirname, "..", "workspace", "ledger.schema.json"), "utf-8")) as object);
+const valid = (doc: unknown) => {
+  const ok = validate(doc);
+  if (!ok) throw new Error(JSON.stringify(validate.errors));
+  return ok;
+};
+
+/** A port over files held in memory: `{ "<dir>/<file>": text }`. */
+function memoryPort(files: Record<string, string>): LedgerReadPort {
+  return {
+    read: async (dir, file) => files[`${dir}/${file}`] ?? null,
+    list: async (dir) => Object.keys(files).filter((k) => k.startsWith(`${dir}/`)).map((k) => k.slice(dir.length + 1)),
+    trees: async () => [...new Set(Object.keys(files).map((k) => k.split("/")[0]))],
+  };
+}
+
+const pending = { version: 1, kind: "pending", op: "tf-apply", gate: "wave-1", timestamp: "2026-10-09T05:00:00.000Z", expiresAt: "2026-10-10T05:00:00.000Z", planDigest: "sha256:aa" };
+const approval = { version: 1, op: "tf-apply", gate: "wave-1", timestamp: "2026-10-09T05:10:00.000Z", resolvedBy: "approver-one", planDigest: "sha256:aa" };
+const other = { version: 1, kind: "pending", op: "deploy", gate: "prod", timestamp: "2026-10-20T05:00:00.000Z", expiresAt: "2026-10-21T05:00:00.000Z", planDigest: "sha256:bb" };
+const gates = { "_gates/tf-apply.jsonl": `${JSON.stringify(pending)}\n${JSON.stringify(approval)}\nnot json\n`, "_gates/deploy.jsonl": `${JSON.stringify(other)}\n` };
+const now = new Date("2026-10-23T00:00:00.000Z");
+
+describe("chant ledger (#4363)", () => {
+  it("prints a table's rows as chant query loads them, filtered by --where", async () => {
+    const doc = await readLedgerTable("gates", [{ member: null, port: memoryPort(gates) }], { where: ["op=tf-apply", "kind=resolution"], now });
+    expect(valid(doc)).toBe(true);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.total).toBe(3);
+    expect(doc.malformed).toBe(1);
+    expect(doc.filter).toEqual({ where: ["op=tf-apply", "kind=resolution"], since: null });
+    expect(doc.rows).toHaveLength(1);
+    expect(doc.rows[0]).toMatchObject({ member: null, op: "tf-apply", gate: "wave-1", resolved_by: "approver-one", plan_digest: "sha256:aa", signed: false, empty: false });
+    expect(Object.keys(doc.rows[0])).toEqual(doc.columns);
+  });
+
+  it("keeps the rows at or after --since on the table's time column", async () => {
+    const doc = await readLedgerTable("gates", [{ member: null, port: memoryPort(gates) }], { since: "7d", now });
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.filter.since).toBe("2026-10-16T00:00:00.000Z");
+    expect(doc.rows.map((r) => r.op)).toEqual(["deploy"]);
+  });
+
+  it("prints a JSON column parsed, and filters on a key under it", async () => {
+    const run = { version: 1, id: "r1", op: "tf-apply", env: "prod", started: "2026-10-22T00:00:00.000Z", ended: "2026-10-22T00:01:00.000Z", status: "succeeded", phases: [], labels: { team: "core" }, outcomes: {} };
+    const port = memoryPort({ "prod/runs__tf-apply.jsonl": `${JSON.stringify(run)}\n` });
+    const doc = await readLedgerTable("runs", [{ member: "app", port }], { where: ["labels.team=core"], now });
+    expect(valid(doc)).toBe(true);
+    if ("error" in doc) throw new Error(doc.error.message);
+    expect(doc.rows).toHaveLength(1);
+    expect(doc.rows[0]).toMatchObject({ member: "app", id: "r1", labels: { team: "core" } });
+  });
+
+  it("refuses an unknown table, a bad filter, and --since on a table with no time, without reading", async () => {
+    const never = async (): Promise<never> => {
+      throw new Error("read");
+    };
+    for (const [table, opts, code] of [
+      ["states", {}, "table-unknown"],
+      ["gates", { where: ["approver=x"] }, "filter-invalid"],
+      ["snapshots", { where: ["resources>many"] }, "filter-invalid"],
+      ["releases", { since: "7d" }, "filter-invalid"],
+    ] as const) {
+      const doc = await readLedgerTable(table, never, opts);
+      expect(valid(doc)).toBe(true);
+      expect(doc).toMatchObject({ error: { code } });
+    }
+  });
+
+  it("types each table's columns from chant query's schema", () => {
+    expect(ledgerFields("snapshots")).toMatchObject({ resources: "number", observed_at: "time", lexicon: "text" });
+    expect(ledgerFields("cuts")).toMatchObject({ signed: "boolean", timestamp: "time" });
+    expect(ledgerFields("resources").attributes).toBe("json");
+  });
+
+  describe("--at", () => {
+    const repo = mkdtempSync(join(tmpdir(), "chant-ledger-at-"));
+    afterAll(() => rmSync(repo, { recursive: true, force: true }));
+    const git = (...a: string[]): string => execFileSync("git", ["-C", repo, "-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", ...a], { encoding: "utf-8" });
+
+    it("reads the ledger as a commit of chant/lifecycle held it", async () => {
+      git("init", "-q", "-b", "chant/lifecycle");
+      mkdirSync(join(repo, "_gates"));
+      writeFileSync(join(repo, "_gates", "tf-apply.jsonl"), `${JSON.stringify(pending)}\n`);
+      git("add", "-A");
+      git("commit", "-q", "-m", "one");
+      writeFileSync(join(repo, "_gates", "tf-apply.jsonl"), `${JSON.stringify(pending)}\n${JSON.stringify(approval)}\n`);
+      git("commit", "-q", "-am", "two");
+      const at = (rev: string) => readLedgerTable("gates", [{ member: null, port: revisionLedgerReadPort(repo, resolveLedgerRevision(repo, rev), "") }], { at: rev });
+      const then = await at("chant/lifecycle~1");
+      const tip = await at("chant/lifecycle");
+      if ("error" in then || "error" in tip) throw new Error("read failed");
+      expect(then.at).toBe("chant/lifecycle~1");
+      expect(then.rows.map((r) => r.kind)).toEqual(["pending"]);
+      expect(tip.rows.map((r) => r.kind)).toEqual(["pending", "resolution"]);
+      expect(() => resolveLedgerRevision(repo, "no-such-rev")).toThrow(LedgerRevisionError);
+    });
+  });
+});

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/observe.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { observeResources, collectAmbient } from "./observe";
+import { observeResources, collectAmbient, carryAnnotations } from "./observe";
 import { observation } from "../observation";
 import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
 import type { BuildResult } from "../build";
@@ -59,6 +59,32 @@ describe("observeResources", () => {
     expect(Object.keys(observations[0].resources)).toEqual(["web-vpc"]);
   });
 
+  it("returns what a lexicon learned about an absent entity as annotations, outside the observations (#4372)", async () => {
+    const plugins = [
+      {
+        name: "aws",
+        serializer: {} as ObservationLexicon["serializer"],
+        describeResources: async () =>
+          observation({}, undefined, undefined, undefined, undefined, undefined, { "web-vpc": { planAction: "create" } }),
+      } as unknown as ObservationLexicon,
+    ];
+    const { observations, annotations } = await observeResources("prod", plugins, mockBuild());
+    // Absent: no observation row anywhere, so nothing that classifies sees it.
+    expect(observations.flatMap((o) => Object.keys(o.resources))).toEqual([]);
+    expect(annotations).toEqual({ "web-vpc": { planAction: "create" } });
+  });
+
+  it("carryAnnotations sets attributes by id and touches nothing else (#4372)", () => {
+    const nodes = [
+      { id: "a", kind: "K", lexicon: "x", attrs: { _status: "accent", name: "a" } },
+      { id: "b", kind: "K", lexicon: "x", attrs: { _status: "good" } },
+    ];
+    const out = carryAnnotations(nodes, { a: { planAction: "create" } });
+    expect(out[0]).toEqual({ id: "a", kind: "K", lexicon: "x", attrs: { _status: "accent", name: "a", planAction: "create" } });
+    expect(out[1]).toBe(nodes[1]);
+    expect(carryAnnotations(nodes, undefined)).toBe(nodes);
+  });
+
   it("passes the declared entity names for scoping", async () => {
     let names: string[] = [];
     const plugins = [awsPlugin(({ entityNames }) => { names = entityNames; return {}; })];

package/src/lifecycle/observe.ts

@@ -22,6 +22,7 @@ import {
   unobservedAll,
   formatUnobserved,
   type NormalizedObservation,
+  type RootRead,
 } from "../observation";
 import { zeroResourcesWarning } from "../live-endpoint";
 import { unqualifiedKey } from "./identity";
@@ -39,6 +40,40 @@ export interface ObserveResult {
    * answer, not ahead of it.
    */
   notes: string[];
+  /**
+   * Facts about declared entities beside their verdict (#4372), keyed like
+   * the observations' resources (stack-qualified where those are). A planned
+   * create is the case: absent, with the plan's attributes. Never part of
+   * `observations`, so nothing that classifies or paints presence sees it;
+   * {@link carryAnnotations} puts it on the declared nodes of an overlay.
+   */
+  annotations?: Record<string, Record<string, unknown>>;
+  /**
+   * Which read answered each declared entity (#2267), keyed like the
+   * observations' resources: `"state"`, `"live"`, `"plan"` or `"live+plan"`
+   * from the terraform lexicon. Present only for lexicons that report it.
+   */
+  sources?: Record<string, string>;
+  /** Which read answered each root, and why it fell back (structured, from the lexicon). */
+  rootReads?: Record<string, RootRead>;
+}
+
+/**
+ * Put each entity's annotations (#4372) on its node, by id. Only attributes
+ * are touched: `_status`, `physicalId` and `ownership` stay what the overlay
+ * decided, so a planned create is still painted pending and still absent to
+ * every consumer that asks. An annotation wins a collision with a declared
+ * attribute, the same precedence an observed attribute has in the overlay.
+ */
+export function carryAnnotations<N extends { id: string; attrs: Record<string, unknown> }>(
+  nodes: N[],
+  annotations: Record<string, Record<string, unknown>> | undefined,
+): N[] {
+  if (!annotations || Object.keys(annotations).length === 0) return nodes;
+  return nodes.map((n) => {
+    const a = annotations[n.id];
+    return a && Object.keys(a).length > 0 ? { ...n, attrs: { ...n.attrs, ...a } } : n;
+  });
 }
 
 /**
@@ -57,6 +92,7 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
     queried: q(obs.queried),
     // Which read answered (#2267) is per entity, so it re-keys with them.
     sources: q(obs.sources),
+    ...(obs.annotations ? { annotations: q(obs.annotations) } : {}),
     notes: obs.notes,
     // Exports are already keyed by stack (#1279); nothing to qualify.
     ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
@@ -131,6 +167,9 @@ export async function observeResources(
   const warnings: string[] = [];
   const errors: string[] = [];
   const notes: string[] = [];
+  const annotations: Record<string, Record<string, unknown>> = {};
+  const sources: Record<string, string> = {};
+  const rootReads: Record<string, RootRead> = {};
 
   for (const plugin of plugins) {
     if (!plugin.describeResources) continue;
@@ -230,6 +269,9 @@ export async function observeResources(
         const line = `[${plugin.name}] ${note}`;
         if (!notes.includes(line)) notes.push(line);
       }
+      Object.assign(annotations, observed.annotations ?? {});
+      Object.assign(sources, observed.sources);
+      Object.assign(rootReads, observed.rootReads ?? {});
       // What the estate depends on but does not declare (#1273). Read after the
       // managed resources, because the declared observation is the closure's
       // roots — there is nothing to reference out from until it exists.
@@ -299,7 +341,7 @@ export async function observeResources(
     }
   }
 
-  return { observations, warnings, errors, notes };
+  return { observations, warnings, errors, notes, annotations, ...(Object.keys(sources).length > 0 ? { sources } : {}), ...(Object.keys(rootReads).length > 0 ? { rootReads } : {}) };
 }
 
 /**

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"
   );
 }