@intentius/chant 0.124.46 → 0.124.49

package/src/cli/handlers/graph-reader.test.ts

@@ -0,0 +1,31 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import { readGraphWithModule } from "./graph-reader";
+
+const scratch = mkdtempSync(join(tmpdir(), "chant-graph-reader-"));
+afterAll(() => rmSync(scratch, { recursive: true, force: true }));
+
+function mod(name: string, text: string): string {
+  const file = join(scratch, name);
+  writeFileSync(file, text);
+  return file;
+}
+
+describe("readGraphWithModule (#4413)", () => {
+  test("calls the default export with dir and config, and fills in groups", async () => {
+    const file = mod("ok.mjs", "export default async ({ dir, config }) => ({ nodes: [{ id: 'a', kind: 'K', lexicon: 'x', attrs: { dir, n: config.n } }], edges: [] });\n");
+    const read = await readGraphWithModule(file, { dir: "/m", n: 2 }, "/p");
+    expect(read).toEqual({ ir: { nodes: [{ id: "a", kind: "K", lexicon: "x", attrs: { dir: "/m", n: 2 } }], edges: [], groups: {} } });
+  });
+
+  test("says why when the module is missing, has no function, throws or returns no graph", async () => {
+    const msg = async (p: string) => ("error" in (await readGraphWithModule(p, {}, "/p")) ? ((await readGraphWithModule(p, {}, "/p")) as { error: string }).error : "");
+    expect(await msg(join(scratch, "nope.mjs"))).toMatch(/could not be loaded/);
+    expect(await msg(mod("nofn.mjs", "export default 3;\n"))).toMatch(/no default export function/);
+    expect(await msg(mod("throws.mjs", "export default () => { throw new Error('boom'); };\n"))).toMatch(/failed: boom/);
+    expect(await msg(mod("bad.mjs", "export default () => ({});\n"))).toMatch(/no nodes and edges/);
+    expect(await msg("rel.mjs")).toMatch(/absolute/);
+  });
+});

package/src/cli/handlers/graph-reader.ts

@@ -0,0 +1,51 @@
+/**
+ * `chant graph` over a graph reader module (#4413).
+ *
+ * A kind's `graph.reader` names a module in the package that supplies the
+ * kind; `chant workspace graph` writes a reader project whose
+ * `graph.reader.module` is that module, and the member's own `chant graph`
+ * runs here. Because the member's chant loads it, the reader runs under the
+ * member's toolchain, as a lexicon reader does. The module's default export
+ * is `(input: { dir, config }) => GraphIR`, sync or async. It reads files and
+ * returns data; chant gives it no write handle, and nothing it returns is
+ * run.
+ */
+
+import { pathToFileURL } from "node:url";
+import { isAbsolute } from "node:path";
+import type { GraphIR } from "../../graph-ir";
+
+export interface GraphReaderInput {
+  /** The member's directory, absolute, as the kind's config placed it in `config.dir` (or the reader project when it didn't). */
+  dir: string;
+  /** The kind's `graph.config`, placeholders substituted. */
+  config: Record<string, unknown>;
+}
+
+/** Load the module and call it, or say why not. Never throws. */
+export async function readGraphWithModule(
+  module: string,
+  config: Record<string, unknown>,
+  projectPath: string,
+): Promise<{ ir: GraphIR } | { error: string }> {
+  if (!isAbsolute(module)) return { error: `graph.reader.module must be an absolute path, got ${module}` };
+  let read: unknown;
+  try {
+    read = ((await import(pathToFileURL(module).href)) as { default?: unknown }).default;
+  } catch (err) {
+    return { error: `graph reader ${module} could not be loaded: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  if (typeof read !== "function") return { error: `graph reader ${module} has no default export function` };
+  let out: unknown;
+  try {
+    const dir = typeof config.dir === "string" ? config.dir : projectPath;
+    out = await (read as (input: GraphReaderInput) => unknown)({ dir, config });
+  } catch (err) {
+    return { error: `graph reader ${module} failed: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const ir = out as Partial<GraphIR> | null;
+  if (ir === null || typeof ir !== "object" || !Array.isArray(ir.nodes) || !Array.isArray(ir.edges)) {
+    return { error: `graph reader ${module} returned something with no nodes and edges` };
+  }
+  return { ir: { ...ir, nodes: ir.nodes, edges: ir.edges, groups: ir.groups ?? {} } as GraphIR };
+}

package/src/cli/handlers/graph.ts

@@ -118,6 +118,20 @@ export function runGraph(ctx: CommandContext): Promise<number> {
 async function runGraphCommand(ctx: CommandContext): Promise<number> {
   const viewFormats = ["ir", "mermaid", "dot", "layout"] as const;
   const isViewFormat = (viewFormats as readonly string[]).includes(ctx.args.format);
+  // A project whose config names a graph reader module is read by it (#4413): `chant workspace graph` writes such a project for a kind that supplies one.
+  if (isViewFormat && !ctx.args.live && !ctx.args.at && !ctx.args.components) {
+    const { config } = await loadChantConfigUpward(resolve(ctx.args.path === "." ? "." : ctx.args.path)).catch(() => ({ config: {} as ChantConfig }));
+    const reader = config.graph?.reader;
+    if (reader) {
+      const { readGraphWithModule } = await import("./graph-reader");
+      const read = await readGraphWithModule(reader.module, reader.config ?? {}, resolve(ctx.args.path === "." ? "." : ctx.args.path));
+      if ("error" in read) {
+        console.error(formatError({ message: read.error }));
+        return 1;
+      }
+      return emitIr(read.ir, ctx, ctx.args.format as (typeof viewFormats)[number]);
+    }
+  }
   // `--projection <lexicon>` (#989) only means anything for the component
   // graph's IR — it adds the CI/pipeline shape to `GraphIR.pipeline`, a field
   // the other view formats' emitters (mermaid/dot/layout) don't read, and the

package/src/cli/handlers/ledger.ts

@@ -0,0 +1,54 @@
+/**
+ * `chant ledger <table> [dir] [--member <name>] [--where <field><op><value>]...
+ * [--since <time>] [--at <rev>] [--json]` (#4363): one ledger's rows from the
+ * local `chant/lifecycle` branch, filtered with typed filters. The read and
+ * its contract live in `../../lifecycle/ledger-read.ts`; the ledgers are read
+ * as `chant query` reads them (`./query.ts` {@link queryLedgers}).
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+import { queryLedgers } from "./query";
+
+const USAGE = "chant ledger <resources|snapshots|runs|gates|deploys|releases|cuts> [dir] [--member <name>] [--where <field><op><value>]... [--since <time>] [--at <rev>] [--json]";
+
+const cell = (v: unknown): string => (v === null || v === undefined ? "" : typeof v === "object" ? JSON.stringify(v) : String(v));
+
+export async function runLedgerCommand(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const table = args.positionals?.[0];
+  if (table === undefined || table.trim() === "") {
+    console.error(formatError({ message: "chant ledger needs a table", hint: USAGE }));
+    return 1;
+  }
+  const cwd = resolve(args.positionals?.[1] ?? ".");
+  if (!existsSync(cwd)) {
+    console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+    return 1;
+  }
+  const { readLedgerTable, ledgerReadFailure, LedgerRevisionError } = await import("../../lifecycle/ledger-read");
+  const { QueryError } = await import("../../lifecycle/query");
+  let doc;
+  try {
+    doc = await readLedgerTable(table, () => queryLedgers(cwd, args.members, args.at), { where: args.where, since: args.since, at: args.at ?? null });
+  } catch (err) {
+    if (err instanceof LedgerRevisionError) doc = ledgerReadFailure("revision-unknown", err.message);
+    else if (err instanceof QueryError) doc = ledgerReadFailure("ledger-unreadable", err.message);
+    else throw err;
+  }
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return "error" in doc ? 1 : 0;
+  }
+  if ("error" in doc) {
+    console.error(formatError({ message: `${doc.error.code}: ${doc.error.message}`, hint: USAGE }));
+    return 1;
+  }
+  const widths = doc.columns.map((c) => Math.max(c.length, ...doc.rows.map((r) => cell(r[c]).length)));
+  const line = (vals: string[]): string => vals.map((v, i) => v.padEnd(widths[i])).join("  ").trimEnd();
+  console.log([line(doc.columns), line(widths.map((w) => "-".repeat(w))), ...doc.rows.map((r) => line(doc.columns.map((c) => cell(r[c]))))].join("\n"));
+  console.log(`(${doc.rows.length} of ${doc.total} ${doc.total === 1 ? "row" : "rows"})`);
+  if (doc.malformed > 0) console.error(formatWarning({ message: `left out ${doc.malformed} in ${doc.table} that could not be read` }));
+  return 0;
+}

package/src/cli/handlers/migrate.ts

@@ -1,4 +1,4 @@
-import { migrateCommand, printMigrateResult } from "../commands/migrate";
+import { lexiconOfSide, migrateCommand, printMigrateResult } from "../commands/migrate";
 import { formatError } from "../format";
 import { loadPlugins } from "../plugins";
 import type { CommandContext } from "../registry";
@@ -16,30 +16,39 @@ export async function runMigrate(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  // A side is a lexicon, or a lexicon and a dialect: `sql/clickhouse` (#4399).
+  const toName = args.migrateTo ?? "gitlab";
+  const fromName = args.migrateFrom ?? "github";
+
+  // The sql pair writes declarations, so ts is its default; yaml is the gitlab pair's.
+  const emit = (args.emit as "yaml" | "ts" | "sql" | undefined) ?? (lexiconOfSide(toName) === "sql" ? "ts" : "yaml");
+  if (emit !== "yaml" && emit !== "ts" && emit !== "sql") {
+    console.error(formatError({ message: `Invalid --emit value: ${emit}. Expected 'yaml', 'ts' or 'sql'.` }));
+    return 1;
+  }
+
+  if (emit === "sql" && lexiconOfSide(toName) !== "sql") {
+    console.error(formatError({ message: `--emit sql writes DDL, and ${toName} is not a sql target`, hint: "use --emit yaml or --emit ts" }));
+    return 1;
+  }
+
   // migrate does not require a chant project context. Load the target
   // lexicon directly by name.
-  const toName = args.migrateTo ?? "gitlab";
   let plugins;
   try {
-    plugins = await loadPlugins([toName]);
+    plugins = await loadPlugins([lexiconOfSide(toName)]);
   } catch (err) {
     console.error(formatError({
       message: `Cannot load target lexicon "${toName}": ${err instanceof Error ? err.message : String(err)}`,
-      hint: `Install @intentius/chant-lexicon-${toName} or pass --to <other-lexicon>`,
+      hint: `Install @intentius/chant-lexicon-${lexiconOfSide(toName)} or pass --to <other-lexicon>`,
     }));
     return 1;
   }
 
-  const emit = (args.emit as "yaml" | "ts" | undefined) ?? "yaml";
-  if (emit !== "yaml" && emit !== "ts") {
-    console.error(formatError({ message: `Invalid --emit value: ${emit}. Expected 'yaml' or 'ts'.` }));
-    return 1;
-  }
-
   const result = await migrateCommand({
     sourceFile: args.path,
-    from: args.migrateFrom ?? "github",
-    to: args.migrateTo ?? "gitlab",
+    from: fromName,
+    to: toName,
     emit,
     strict: args.strict ?? false,
     validate: args.validate ?? false,

package/src/cli/handlers/misc.ts

@@ -384,10 +384,19 @@ export async function runImport(ctx: CommandContext): Promise<number> {
     force: ctx.args.force,
     lexicon: ctx.args.lexicon,
     parserOptions: ctx.args.parserOption,
+    validate: ctx.args.validate,
   });
 
   printImportResult(result);
-  return result.success ? 0 : 1;
+  if (!result.success) return 1;
+  // The review report and `--strict` (#4398): the parser's diagnostics, as `chant migrate` reports its own.
+  if (ctx.args.reportFile) {
+    const { writeImportReport } = await import("../commands/import-report");
+    const failed = writeImportReport(ctx.args.reportFile, resolve(ctx.args.path), result.diagnostics ?? [], CHANT_VERSION);
+    if (failed) console.error(formatWarning({ message: failed }));
+  }
+  const { importExitCode } = await import("../commands/import-report");
+  return importExitCode(result.diagnostics, ctx.args.strict === true);
 }
 
 export async function runUpdate(ctx: CommandContext): Promise<number> {

package/src/cli/handlers/pr-env.ts

@@ -241,10 +241,10 @@ function componentsPrEnvAdapter(p: Prepared, run: { planAll: typeof import("./pr
     },
     async apply(target) {
       const planned = set!;
-      const hookStop = run.runStageHook(p, "before-apply", p.plan.order, planned);
+      const hookStop = await run.runStageHook(p, "before-apply", p.plan.order, planned);
       if (hookStop) return { status: "stopped", rows: rows(target, () => "planned"), message: hookStop };
       const applied = await applyPrSet({ components: p.components, plan: p.plan, registry: p.registry, env: target.env, set: planned, gate: PR_ENV_GATE });
-      const afterHook = run.runStageHook(p, "after-apply", p.plan.order, planned, "the environment stands as applied");
+      const afterHook = await run.runStageHook(p, "after-apply", p.plan.order, planned, "the environment stands as applied");
       const status = (component: string) => applied.members.find((m) => m.component === component)?.status ?? "planned";
       return {
         status: applied.status === "applied" ? "applied" : applied.status === "waiting" ? "waiting" : "failed",

package/src/cli/handlers/pr.ts

@@ -65,8 +65,8 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
 import { loadChantConfig, resolveAutoReleaseDisabled, type ChantConfig } from "../../config";
 import { resolveCommit, resolveMergeBase } from "../../components/changed-files";
 import { deriveFanOut, fanOutRegistry } from "../../components/fan-out-support";
@@ -90,7 +90,8 @@ import { blockedMembers, blockedWords, settleEarlierWaves, type WaveMemberOutcom
 import { readFanOutAttempt, writeFanOutAttempt, type FanOutAttempt, type PrApplyRecord } from "../../components/fan-out-record";
 import { componentInputDigests, progressThatCarries } from "../../components/fan-out-inputs";
 import { samePlanDigest } from "../../lifecycle/plan-digest";
-import { gateIsSealed, gitGateLedgerPort, type GateCheck } from "../../op/gate";
+import { evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "../../op/gate";
+import type { OtherGateHold } from "../../op/stage-hooks";
 import { emitGateStep, gateEventsOf, GATE_PHASE, type RunEventSink, type RunEventStream } from "../../run-event-stream";
 import type { RunEventBody, RunEventComponentSettle, RunEventSettleStatus } from "../../run-event";
 import { openCliRunEvents, refusesEventsWithJson } from "../run-events";
@@ -130,10 +131,12 @@ import type { ComponentChangeSignal, FanOutPlan } from "../../components/fan-out
 import { failedRunExitCode, type DriverComponent } from "../../components/driver";
 import type { CapabilityRegistry } from "../../components/capability";
 import type { ComponentEnvironmentDeclaration } from "../../components/component";
-import { prLoopHooksAt, runPrHooks, type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks";
-import { decidePrPolicyOverride, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrLoopPolicy } from "../../components/pr-policy";
+import { prLoopHooksAt, runPrHooks, type PrHoldSettled, type PrHookPlace, type PrLoopHooks } from "../../components/pr-hooks";
+import { decidePrPolicyOverride, policyReviewOf, prLoopPolicyAt, prPolicyReport, runPrPolicy, spendPrPolicyOverride, type PrLoopPolicy } from "../../components/pr-policy";
 import type { OpWaveHookMoment } from "../../op/op-waves";
 import type { PrHookOutcome } from "../../pr-loop";
+import type { PrMigrationFile } from "../../pr-migrations";
+import { lexiconNames } from "../../lexicon-module";
 
 
 /** Where the reports land unless `--output` says. */
@@ -320,9 +323,19 @@ export function placeHooks(ctx: CommandContext, p: Prepared, stage: PrHookPlace[
  * when no hook failed. A hold is logged: the pull request's gate already
  * waits for a person's approval of the digest.
  */
-export function runStageHook(p: Prepared, moment: OpWaveHookMoment, components: readonly string[], planned?: PrPlanSet, what = "nothing was applied"): string | undefined {
+export async function runStageHook(
+  p: Prepared,
+  moment: OpWaveHookMoment,
+  components: readonly string[],
+  planned?: PrPlanSet,
+  what = "nothing was applied",
+  env?: Record<string, string>,
+): Promise<string | undefined> {
   if (!p.hookPlace || components.length === 0) return undefined;
-  const ran = runPrHooks(p.hooks, moment, p.hookPlace, components, planned ? { members: planned.members, plans: planned.plans } : undefined);
+  const ran = await runPrHooks(p.hooks, moment, p.hookPlace, components, planned ? { members: planned.members, plans: planned.plans } : undefined, {
+    ...(env ? { env } : {}),
+    settle: (hold) => settleHeldGate(p, hold),
+  });
   p.hookOutcomes.push(...ran.outcomes);
   for (const hold of ran.holds) console.error(formatInfo(`${hold} held, and the pull request's gate asks for an approval of the digest either way`));
   if (!ran.failed) return undefined;
@@ -330,6 +343,46 @@ export function runStageHook(p: Prepared, moment: OpWaveHookMoment, components:
   return p.hookFailed;
 }
 
+/**
+ * Settle a hook's hold on another gate (#4323), the way an Op waves job does:
+ * an approval of that gate and digest under its `identity.gates` rule read at
+ * base, else a pending fact for it. The plan stage writes nothing, so there
+ * it only reads.
+ */
+async function settleHeldGate(p: Prepared, hold: OtherGateHold): Promise<PrHoldSettled> {
+  const real = gitGateLedgerPort();
+  const ledger = p.hookPlace?.stage === "plan" ? readOnlyLedger(real) : real;
+  const port: GateLedgerPort = ledger.approvalRule ? { ...ledger, approvalRule: (g: string) => ledger.approvalRule!(g, { base: p.base }) } : ledger;
+  const op = hold.request.op ?? p.hookPlace?.op ?? "";
+  const check = await evaluateGate(port, {
+    op,
+    gate: hold.request.gate,
+    planDigest: hold.request.digest,
+    description: hold.request.description ?? `${hold.label} holds the pull request on it`,
+    fields: { ...hold.request.pending, approvalMode: "ledger", heldBy: { hook: hold.name, moment: hold.moment, ...(hold.target ? { target: hold.target } : {}) } },
+  });
+  if (check.satisfied) return { status: "approved", approvedBy: check.resolution.resolvedBy, approvedAt: check.resolution.timestamp };
+  for (const { resolution: r, reason } of check.refused ?? []) console.error(formatInfo(`${op} / ${hold.request.gate}: the approval by ${r.resolvedBy} at ${r.timestamp} does not count: ${reason}`));
+  return { status: "waiting" };
+}
+
+/**
+ * Run the `after-gate` hooks once the pull request's gate decided (#4323),
+ * whatever it decided. `CHANT_GATE_STATUS` is `approved`, or `waiting` when no
+ * approval of the digest stands; `CHANT_GATE_OP`, `CHANT_GATE` and
+ * `CHANT_GATE_DIGEST` name the gate. Returns the failure message, as
+ * {@link runStageHook} does; the caller ignores it when the gate did not let
+ * the apply through, since the stage ends there anyway.
+ */
+export function runGateHook(p: Prepared, at: { op: string; digest: string; satisfied: boolean }, components: readonly string[]): Promise<string | undefined> {
+  return runStageHook(p, "after-gate", components, undefined, "nothing was applied", {
+    CHANT_GATE_STATUS: at.satisfied ? "approved" : "waiting",
+    CHANT_GATE_OP: at.op,
+    CHANT_GATE: p.gate,
+    CHANT_GATE_DIGEST: at.digest,
+  });
+}
+
 const EMPTY_SET = (): PrPlanSet => ({ doc: composeChangeSet([]), members: [], plans: {}, outputs: {}, failed: true });
 
 /**
@@ -338,11 +391,11 @@ const EMPTY_SET = (): PrPlanSet => ({ doc: composeChangeSet([]), members: [], pl
  * set, so the stage reports `plan-failed` and nothing applies.
  */
 async function hookedPlan(p: Prepared, components: readonly string[], plan: () => Promise<PrPlanSet>): Promise<PrPlanSet> {
-  if (runStageHook(p, "before-observe", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
-  if (runStageHook(p, "before-plan", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
+  if (await runStageHook(p, "before-observe", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
+  if (await runStageHook(p, "before-plan", components, undefined, "nothing was planned or applied")) return EMPTY_SET();
   const set = await plan();
   if (set.failed) return set;
-  if (runStageHook(p, "after-plan", components, set)) return { ...set, failed: true };
+  if (await runStageHook(p, "after-plan", components, set)) return { ...set, failed: true };
   return set;
 }
 
@@ -474,7 +527,7 @@ async function publish(forge: PrForge | undefined, report: PrReport, note: strin
   if (report.pr === null) return;
   // A member the change does not reach has nothing to say: one note per
   // member would put a line on every pull request for each member it skips.
-  if (report.member && report.status === "nothing" && !report.overdue?.length) return;
+  if (report.member && report.status === "nothing" && !report.overdue?.length && !report.migrations?.length) return;
   try {
     await forge.upsertNote(report.pr, prNoteMarker(report.env, report.member), note);
   } catch (err) {
@@ -570,7 +623,9 @@ interface PolicyJudged {
  * read only at the plan stage, and recorded for an override at the apply.
  */
 async function judgePolicy(p: Prepared, at: { stage: "plan" | "apply"; op: string; pr: number | null; set: PrPlanSet }): Promise<PolicyJudged> {
-  const verdict = runPrPolicy(p.policy, { version: 1, stage: at.stage, op: at.op, gate: p.gate, env: p.env, pr: at.pr, base: p.base, head: p.head, changeSet: at.set.doc });
+  // The review is read only when a policy will run: a workspace with no policy makes no forge call for it.
+  const review = p.policy.settings ? await policyReviewOf(p.forge, at.pr) : undefined;
+  const verdict = runPrPolicy(p.policy, { version: 1, stage: at.stage, op: at.op, gate: p.gate, env: p.env, pr: at.pr, base: p.base, head: p.head, changeSet: at.set.doc, ...(review ? { review } : {}) });
   if (!verdict) return { held: false };
   const report = prPolicyReport(verdict, p.policy.base);
   p.policyReport = report;
@@ -673,8 +728,10 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
   }
   const status = p.plan.order.length === 0 ? "nothing" : set.failed ? "plan-failed" : "planned";
   const overdue = await overdueOps(p.forge, p.member);
+  const migrations = await newMigrations(p);
   const planned = prReport({
     stage: "plan",
+    ...(migrations.length > 0 ? { migrations } : {}),
     pr: ctx.args.pr,
     env: p.env,
     ...(p.member ? { member: p.member } : {}),
@@ -704,6 +761,39 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
   return status === "plan-failed" || judged.stop ? 1 : 0;
 }
 
+/**
+ * The migration files the pull request adds in a migration-directory member
+ * (#4407), each statement classified offline by the sql lexicon. Nothing is
+ * applied and no server is contacted. A workspace without such a member, or
+ * a classifier that cannot load, leaves the note as it was.
+ */
+async function newMigrations(p: Prepared): Promise<PrMigrationFile[]> {
+  const { newMigrationFilesBetween } = await import("../../workspace/new-migrations");
+  try {
+    return await newMigrationFilesBetween(resolve("."), p.base, p.head, {
+      ...(p.member ? { member: p.member } : {}),
+      plugins: async () => {
+        const { loadPlugin } = await import("../plugins");
+        const names = ["sql", ...lexiconNames(p.config.lexicons ?? []).filter((n) => n !== "sql")];
+        const loaded = [];
+        for (const name of names) {
+          try {
+            const plugin = await loadPlugin(name);
+            if (plugin.classifyMigrations) loaded.push(plugin);
+            if (loaded.length > 0) break;
+          } catch {
+            // not installed: the next name, or the note says no lexicon classifies the dialect
+          }
+        }
+        return loaded;
+      },
+    });
+  } catch (err) {
+    console.error(formatWarning({ message: `could not classify the new migration files: ${err instanceof Error ? err.message : String(err)}` }));
+    return [];
+  }
+}
+
 /**
  * The scheduled watch and reconcile Ops that stopped running (#4289,
  * `op/schedule-overdue.ts`), asked of the forge. Without a forge, or when
@@ -712,27 +802,8 @@ async function prPlan(ctx: CommandContext, stage: StageEvents): Promise<number>
  * `pr-post` asks instead, reading the Ops at the target branch's commit.
  */
 async function overdueOps(forge: PrForge | undefined, member: string | undefined): Promise<PrOverdue[]> {
-  if (!forge?.scheduledRuns) return [];
-  try {
-    const { discoverOps } = await import("../../op/discover");
-    const { scheduledWatches, checkOverdueOps } = await import("../../op/schedule-overdue");
-    const discovered = await discoverOps({ cwd: resolve(".") });
-    const watches = scheduledWatches([...discovered.ops.values()].map((d) => d.config));
-    if (watches.length === 0) return [];
-    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
-    if (top.status !== 0) return [];
-    return await checkOverdueOps({
-      watches,
-      forge,
-      repoRoot: top.stdout.trim(),
-      ...(member ? { member } : {}),
-      now: new Date(),
-      log: (line) => console.error(formatWarning({ message: line })),
-    });
-  } catch (err) {
-    console.error(formatWarning({ message: `could not check the scheduled Ops, so none is reported overdue: ${err instanceof Error ? err.message : String(err)}` }));
-    return [];
-  }
+  const { overdueOpsAt } = await import("../../op/schedule-overdue");
+  return overdueOpsAt({ forge, cwd: resolve("."), ...(member ? { member } : {}), log: (line) => console.error(formatWarning({ message: line })) });
 }
 
 /** chant components pr-apply --base <ref> [--pr <n>] [--env <env>] [--gate <name>] [--forge <kind>] [--require-review] [--output <dir>] [--json] [--events-json] [--report-url <url>] */
@@ -881,6 +952,9 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
     if (judged.stop) return stop(prReport({ ...base, approval: { status: "pending" }, status: "refused", refusal: judged.stop.refusal, message: judged.stop.message }), judged.stop.code);
     const decided = await decideApplyGate(p, { op, pr, set, events, held: judged.held, ...(green ? { green } : {}) });
     approval = decided.approval;
+    // #4323: the after-gate hooks hear the decision, a refusal too; only a failure that would have applied changes the outcome.
+    const afterGate = await runGateHook(p, { op, digest: set.doc.digest, satisfied: decided.satisfied }, p.plan.order);
+    if (afterGate && decided.satisfied) return stop(prReport({ ...base, approval, status: "failed", message: afterGate }), 1);
     if (!decided.satisfied) return stop(prReport({ ...base, approval, status: "refused", refusal: decided.refusal, message: decided.message }), GATED_EXIT_CODE);
     via = decided.via;
   }
@@ -935,7 +1009,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
 
   // #4288: the before-apply hooks, once the gate and the review let the apply through.
   const toApply = (resumed?.plan ?? p.plan).order.filter((name) => !completedSoFar.has(name));
-  const beforeFailed = runStageHook(p, "before-apply", toApply);
+  const beforeFailed = await runStageHook(p, "before-apply", toApply);
   if (beforeFailed) return stop(prReport({ ...base, approval, status: "failed", message: beforeFailed }), 1);
 
   // #3999: a round planned after an upstream applied waits on a gate of its
@@ -994,7 +1068,7 @@ async function prApply(ctx: CommandContext, stage: StageEvents, beforeMerge?: Pr
   });
   recordAttempt();
   // #4288: the after-apply hooks, for the components that applied.
-  const afterFailed = runStageHook(p, "after-apply", toApply.filter((name) => applied.run.completed.includes(name)), undefined, "the apply counts as failed though its components applied");
+  const afterFailed = await runStageHook(p, "after-apply", toApply.filter((name) => applied.run.completed.includes(name)), undefined, "the apply counts as failed though its components applied");
   await recordAutoReleasesForRun(applied.run.results, p.env, release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), release.runOrigin, undefined, undefined, prAppliedDigests(p, applied.members));
   const report = prReport({
     ...base,
@@ -1787,6 +1861,9 @@ async function prApplyWaves(
     if (judged.stop) return stop(report({ status: "refused", refusal: judged.stop.refusal, message: judged.stop.message }), judged.stop.code);
     const decided = await decideApplyGate(p, { op, pr, set, events, held: judged.held, ...(green ? { green } : {}) });
     approval = decided.approval;
+    // #4323: the after-gate hooks hear the decision, a refusal too.
+    const afterGate = await runGateHook(p, { op, digest: set.doc.digest, satisfied: decided.satisfied }, p.plan.order);
+    if (afterGate && decided.satisfied) return stop(report({ status: "failed", message: afterGate }), 1);
     if (!decided.satisfied) return stop(report({ status: "refused", refusal: decided.refusal, message: decided.message }), GATED_EXIT_CODE);
     via = decided.via;
     planned = set;
@@ -1944,7 +2021,7 @@ async function prApplyWaves(
     }
 
     // #4288: the wave's apply-side hooks, around its apply.
-    const waveBefore = runStageHook(p, "before-apply", wavePlan.order, undefined, `nothing in wave ${k} was applied`);
+    const waveBefore = await runStageHook(p, "before-apply", wavePlan.order, undefined, `nothing in wave ${k} was applied`);
     if (waveBefore) {
       setWave({ ...entry, status: "failed" });
       return stop(report({ status: "failed", message: waveBefore }), 1);
@@ -1979,7 +2056,7 @@ async function prApplyWaves(
       const outputs = applied.run.componentOutputs[name];
       if (outputs) outputsSoFar[name] = outputs;
     }
-    const waveAfter = runStageHook(p, "after-apply", wavePlan.order.filter((name) => applied.run.completed.includes(name)), undefined, `wave ${k} counts as failed though its components applied`);
+    const waveAfter = await runStageHook(p, "after-apply", wavePlan.order.filter((name) => applied.run.completed.includes(name)), undefined, `wave ${k} counts as failed though its components applied`);
     setWave({ ...entry, status: applied.status === "applied" && !waveAfter ? "applied" : "failed" });
     await recordAutoReleasesForRun(applied.run.results, p.env, at.release.runId, resolveAutoReleaseDisabled(p.config, args.noReleaseRecord), at.release.runOrigin, undefined, undefined, prAppliedDigests(p, applied.members));
     if (applied.status !== "applied") {
@@ -2023,6 +2100,7 @@ function writeWaveChangeSet(ctx: CommandContext, wave: number, doc: PrPlanSet["d
 
 /**
  * chant components pr-post --pr <n> --head <sha> --env <env> --forge <kind> [--member <name>] [--output <dir>] [--result <result>] (#4295)
+ * chant components pr-post --open --env <env> --forge gitlab [--branch <branch>] [--member <name>] [--output <dir>] (#4328)
  *
  * Post the plan note and the `chant/plan` status from the report a plan job
  * wrote with `pr-plan --no-status`, in a job that runs none of the change's
@@ -2033,6 +2111,7 @@ function writeWaveChangeSet(ctx: CommandContext, wave: number, doc: PrPlanSet["d
  */
 export async function runComponentsPrPost(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
+  if (args.open) return runComponentsPrPostOpen(ctx);
   if (args.pr === undefined) return fail("pr-post needs the pull or merge request: --pr <n>");
   if (!args.head || !/^[0-9a-f]{40}$/.test(args.head)) return fail("pr-post needs the full commit the plan job checked out: --head <sha>");
   if (!args.env) return fail("pr-post needs the environment the plan was for: --env <env>");
@@ -2062,3 +2141,63 @@ export async function runComponentsPrPost(ctx: CommandContext): Promise<number>
   console.error(formatInfo(`pr-post: ${prStatusContext("plan", member)} ${posted.state}: ${posted.description}${posted.noted ? "; note posted" : ""}`));
   return 0;
 }
+
+/**
+ * `pr-post --open` (#4328): in a pipeline of the target branch on GitLab,
+ * post the plan note and status of every open merge request into it whose
+ * plan job settled, reading each report from the plan job's artifacts
+ * (`postOpenPlanReports`, ../../pr-post.ts). The branch is `--branch`, else
+ * the pipeline's own (`CI_COMMIT_BRANCH`). The plan job is `plan`, or
+ * `<member>-plan` with `--member`, as the gitlab lexicon names it, and the
+ * artifact path is `--output` from the repository root. It exits 0 once it
+ * has posted, as `pr-post` does.
+ */
+async function runComponentsPrPostOpen(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.pr !== undefined || args.head) return fail("pr-post --open finds each merge request and its head itself, so it takes no --pr or --head");
+  if (!args.env) return fail("pr-post needs the environment the plan was for: --env <env>");
+  if (args.forge !== "gitlab") return fail("pr-post --open is for a GitLab pipeline of the target branch: --forge gitlab");
+  if (args.members && args.members.length > 1) return fail(`pr-post takes one --member, not ${args.members.join(", ")}`);
+  const branch = args.branch ?? process.env.CI_COMMIT_BRANCH;
+  if (!branch) return fail("pr-post --open posts for the merge requests into a branch: run it in a branch pipeline, or pass --branch <branch>");
+  let forge: PrForge;
+  try {
+    forge = forgeFromEnv("gitlab");
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
+  if (top.status !== 0) return fail("pr-post --open reads the plan report's path from the repository root, and this directory is not in a git repository");
+  const member = args.members?.[0];
+  const artifactDir = relative(realpathSync(top.stdout.trim()), resolve(args.output ?? PR_REPORT_DIR)).split(sep).join("/");
+  const { postOpenPlanReports } = await import("../../pr-post");
+  const { gitlabPlanJobName } = await import("../../components/pr-pipeline");
+  let done: Awaited<ReturnType<typeof postOpenPlanReports>>;
+  try {
+    done = await postOpenPlanReports({
+      forge,
+      branch,
+      job: gitlabPlanJobName(member),
+      artifactDir,
+      env: args.env,
+      ...(member ? { member } : {}),
+      // #4289: the Ops at the commit this pipeline checked out, the target branch's.
+      overdue: () => overdueOps(forge, member),
+    });
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err));
+  }
+  for (const message of done.warnings) console.error(formatWarning({ message }));
+  for (const p of done.posts) {
+    if (p.skipped) {
+      console.error(formatInfo(`pr-post: !${p.pr}: ${p.skipped}`));
+      continue;
+    }
+    const posted = p.posted!;
+    for (const message of posted.warnings) console.error(formatWarning({ message: `!${p.pr}: ${message}` }));
+    if (posted.refused) console.error(formatWarning({ message: `!${p.pr}: the plan report was not used: ${posted.refused}` }));
+    console.error(formatInfo(`pr-post: !${p.pr} ${prStatusContext("plan", member)} ${posted.state}: ${posted.description}${posted.noted ? "; note posted" : ""}`));
+  }
+  if (done.posts.length === 0) console.error(formatInfo(`pr-post: no open merge request into ${branch} has a ${gitlabPlanJobName(member)} job`));
+  return 0;
+}

package/src/cli/handlers/query.ts

@@ -18,11 +18,23 @@ import { findWorkspaceRoot } from "../../project-root";
 
 const USAGE = 'chant query "<sql>" [dir] [--member <name>] [--json]';
 
-/** The ledgers `chant query` reads from `cwd`: every member's in a workspace, else the project's own. */
-export async function queryLedgers(cwd: string, members?: readonly string[]): Promise<QueryLedger[]> {
+/**
+ * The ledgers `chant query` and `chant ledger` read from `cwd`: every
+ * member's in a workspace, else the project's own. With `at`, a commit of
+ * `chant/lifecycle` (`chant ledger --at`, #4363), each is read as that commit
+ * held it rather than at the branch tip.
+ */
+export async function queryLedgers(cwd: string, members?: readonly string[], at?: string): Promise<QueryLedger[]> {
   const { gitLedgerReadPort } = await import("../../lifecycle/git");
   const found = findWorkspaceRoot(cwd);
-  if (!found) return [{ member: null, port: gitLedgerReadPort({ cwd }) }];
+  const atPort = at === undefined ? undefined : await (async () => {
+    const { resolveLedgerRevision, revisionLedgerReadPort } = await import("../../lifecycle/ledger-read");
+    const { memberLedgerPrefix } = await import("../../lifecycle/member-ledger");
+    const repo = found?.dir ?? cwd;
+    const commit = resolveLedgerRevision(repo, at);
+    return (member: string | null) => revisionLedgerReadPort(repo, commit, member === null ? "" : memberLedgerPrefix([member]));
+  })();
+  if (!found) return [{ member: null, port: atPort ? atPort(null) : gitLedgerReadPort({ cwd }) }];
   // Workspace code loads only when there is a workspace, so a level-0 project never pays for it.
   const { readDeclaration, WorkspaceReadError } = await import("../../workspace/declaration");
   const { workingTree } = await import("../../workspace/tree");
@@ -41,7 +53,7 @@ export async function queryLedgers(cwd: string, members?: readonly string[]): Pr
   }
   return declaration.members
     .filter((m) => !wanted || wanted.has(m.name))
-    .map((m) => ({ member: m.name, port: gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
+    .map((m) => ({ member: m.name, port: atPort ? atPort(m.dir === "." ? null : m.name) : gitLedgerReadPort({ cwd: found.dir, member: m.dir === "." ? "." : m.name }) }));
 }
 
 export async function runQueryCommand(ctx: CommandContext): Promise<number> {