@intentius/chant 0.124.48 → 0.124.49

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/pr.ts

@@ -135,6 +135,8 @@ import { prLoopHooksAt, runPrHooks, type PrHoldSettled, type PrHookPlace, type P
 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. */
@@ -525,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) {
@@ -726,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 } : {}),
@@ -757,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

package/src/cli/main.test.ts

@@ -852,6 +852,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace build",
       "workspace check",
       "workspace evidence",
+      "workspace exit",
       "workspace export",
       "workspace graph",
       "workspace hash-index",
@@ -868,6 +869,7 @@ describe("workspace init and ls (#2534)", () => {
       "workspace patch",
       "workspace pin",
       "workspace points",
+      "workspace promote",
       "workspace records",
       "workspace run",
       "workspace runs",

package/src/cli/main.ts

@@ -614,6 +614,16 @@ Workspace (level 1, #2524):
                         write it only on confirmation (--yes writes without
                         asking; --name <name> names the workspace; --verbose
                         lists every file leaving the root project)
+                        --from tfc|spacelift|backstage proposes from a
+                        Terraform Cloud organization (--org, or --input <export>),
+                        a Spacelift account (--endpoint, or --input <export>) or
+                        the catalog-info.yaml files under dir, and shows what
+                        it left out (#3178)
+  workspace promote <member> [--state <tfstate>] [--lexicon <name>] [--dry-run] [--output <patch>] [--json]
+                        Move a member one rung up the kind ladder (terraform to
+                        choudoufu runs live-check and the adoption report;
+                        choudoufu or other to chant runs chant import), staged
+                        in a worktree and gated on the patch digest like upgrade
   workspace ls [dir]    List the declaration's members and example groups.
                         A member that can't be read is listed with a reason
                         code and still exits 0. --at <rev> reads a commit's
@@ -861,6 +871,15 @@ Workspace (level 1, #2524):
                         manual steps. Needs no workspace file
   workspace lineage resolve <path>
                         Close a manual step once the file is merged by hand
+  workspace exit [<member>...] [--dry-run] [--drill] [--output <file>] [--json]
+                        Leave chant: build each chant member once, commit the
+                        native output (CloudFormation, ARM, Kubernetes YAML,
+                        Compose, CI files), point its CI at the platform's own
+                        CLI, drop the chant dependencies and set the member to
+                        other. Staged in a worktree and gated on the patch
+                        digest (chant approve workspace-exit <scope>). op.json
+                        files stay. --drill runs it on a scratch copy and
+                        checks each member, changing nothing.
   workspace upgrade [<scope>] [--to <ref|dir>] [--source <repo>[#<member>]] [--allow-code] [--dry-run] [--output <file>]
                         Bring a lineage scope to a newer template version: fetch
                         it, migrate and merge per file in a worktree, run build,
@@ -1655,6 +1674,9 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace metrics", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/delivery-metrics")).runWorkspaceMetrics(ctx) },
   { name: "workspace status", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/status")).runWorkspaceStatus(ctx) },
   { name: "workspace lineage", handler: async (ctx) => (await import("../workspace/lineage-cli")).runWorkspaceLineage(ctx) },
+  { name: "workspace exit", handler: async (ctx) => (await import("../workspace/exit-cli")).runWorkspaceExit(ctx) },
+  // #3178 — move a member one rung up the kind ladder, staged in a worktree and gated on the patch digest.
+  { name: "workspace promote", handler: async (ctx) => (await import("../workspace/promote")).runWorkspacePromote(ctx) },
   { name: "workspace upgrade", handler: async (ctx) => (await import("../workspace/lineage-upgrade-cli")).runWorkspaceUpgrade(ctx) },
   // #2551 — adopt a lineage, the hash index it matches against, and the versions of a family of workspaces.
   { name: "workspace adopt-lineage", handler: async (ctx) => (await import("../workspace/lineage-adopt-cli")).runWorkspaceAdoptLineage(ctx) },

package/src/cli/parse-args.ts

@@ -284,6 +284,9 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.emit = args[++i];
     } else if (arg === "--dry-run") {
       result.dryRun = true;
+    } else if (arg === "--drill") {
+      // #3177 — `chant workspace exit --drill` runs the exit on a scratch copy.
+      result.drill = true;
     } else if (arg === "--yes") {
       result.yes = true;
     } else if (arg === "--push") {
@@ -922,6 +925,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       const value = args[++i];
       if (!value || value.startsWith("-")) throw new Error(`${arg} needs a value: ${arg} <${arg.slice(2)}>`);
       result[arg.slice(2) as "holder" | "ttl" | "token" | "outcome"] = value;
+    } else if (arg === "--input" || arg === "--org" || arg === "--endpoint") {
+      // `chant workspace init --from tfc|spacelift` (#3178): an exported file instead of the API, the Terraform Cloud organization, the Spacelift GraphQL endpoint.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error(`${arg} needs a value: ${arg} <${arg === "--input" ? "file" : arg.slice(2)}>`);
+      result[arg.slice(2) as "input" | "org" | "endpoint"] = value;
     } else if (arg === "--signer") {
       // `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign.
       const value = args[++i];

package/src/cli/registry.ts

@@ -165,6 +165,8 @@ export interface ParsedArgs {
   remove?: boolean;
   /** `chant lifecycle rollback --dry-run` — compute the rollback delta and print it; open no PR, push nothing, leave no branch. */
   dryRun?: boolean;
+  /** `chant workspace exit --drill` (#3177): run the exit on a scratch copy and check it, changing nothing. */
+  drill?: boolean;
   /** `chant lifecycle teardown <env> --yes` — execute the planned deletion
    * (#1222). Without it the command plans and stops. */
   yes?: boolean;
@@ -628,6 +630,12 @@ export interface ParsedArgs {
   claim?: string;
   /** `chant workspace evidence sign --environment <file>` (#2553): the runner environment, hashed into the evidence. */
   environment?: string;
+  /** `chant workspace init --from tfc|spacelift --input <file>` (#3178): an exported file read instead of the API. */
+  input?: string;
+  /** `chant workspace init --from tfc --org <name>` (#3178): the Terraform Cloud organization. */
+  org?: string;
+  /** `chant workspace init --from spacelift --endpoint <url>` (#3178): the account's GraphQL endpoint. */
+  endpoint?: string;
   /** `chant workspace runs statement <id> --signer <principal>` (#3192): the runner principal that will sign. */
   signer?: string;
   /** `chant workspace evidence verify --envelope <file>` (#2553). */

package/src/components/pr-env-run-bundle.test.ts

@@ -47,6 +47,7 @@ describe("the pr-env-run bundle", () => {
       "packages/core/src/op/emulator-lifecycle.ts",
       "packages/core/src/plan-summary.ts",
       "packages/core/src/pr-loop.ts",
+      "packages/core/src/pr-migrations.ts",
     ]);
     expect(inputs.some((i) => /node_modules\/(ajv|js-yaml)\//.test(i) || i.endsWith("/op/gate.ts") || i.endsWith("/src/config.ts") || i.endsWith("/ts-loader.ts"))).toBe(false);
     expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(40 * 1024);

package/src/components/pr-run.ts

@@ -99,6 +99,7 @@ import type { CapabilityRegistry, PlannedOutputs } from "./capability";
 import type { RunProgressEvent } from "./run-progress";
 import type { RunEventSink } from "../run-event-stream";
 import { capabilitySteps, planWaveComponent, readDeployedOutputs } from "./wave-plan";
+import type { PrMigrationFile } from "../pr-migrations";
 
 export interface PrPlanSetOptions {
   /** Every component in the project, not the selection: a planned member's dependency outside it is read too (#4104). */
@@ -773,6 +774,8 @@ export interface PrReportInput {
   waves?: PrWave[];
   /** The rounds the apply planned after an upstream applied (#3999). */
   rounds?: PrRound[];
+  /** Plan stage (#4407): the new migration files, classified. */
+  migrations?: PrMigrationFile[];
 }
 
 /** The report a stage writes. */
@@ -797,6 +800,7 @@ export function prReport(input: PrReportInput): PrReport {
     ...(input.set.deployedOutputs ? { deployedOutputs: input.set.deployedOutputs } : {}),
     ...(input.set.plannedOutputs ? { plannedOutputs: input.set.plannedOutputs } : {}),
     ...(input.rounds && input.rounds.length > 0 ? { rounds: input.rounds } : {}),
+    ...(input.migrations && input.migrations.length > 0 ? { migrations: input.migrations } : {}),
     approval: input.approval,
     ...(input.waveGate ? { waveGate: input.waveGate } : {}),
     ...(input.waveGate && input.waves?.length ? { waves: [...input.waves].sort((a, b) => a.wave - b.wave) } : {}),

package/src/config.ts

@@ -76,6 +76,10 @@ export const ChantConfigSchema = z.object({
   // Strict like `run`: a misspelt `lint` would leave the gate on with nothing said.
   graph: z.object({
     lint: z.enum(["gate", "report"]).optional(),
+    reader: z.object({
+      module: z.string().min(1),
+      config: z.record(z.string(), z.unknown()).optional(),
+    }).strict().optional(),
   }).strict().optional(),
   buildParams: z.record(
     z.string(),
@@ -234,6 +238,18 @@ export interface ChantConfig {
    */
   graph?: {
     lint?: "gate" | "report";
+    /**
+     * A graph reader module (#4413): when set, `chant graph --format ir` loads
+     * `module` (an absolute path to an ES module whose default export is
+     * `(input: { dir, config }) => GraphIR`) and prints what it returns,
+     * instead of discovering lexicon entities. The reader project
+     * `chant workspace graph` writes for a kind whose `graph.reader` names a
+     * module sets it. A chant older than the key ignores it.
+     */
+    reader?: {
+      module: string;
+      config?: Record<string, unknown>;
+    };
   };
 
   /**

package/src/gate-decision-bundle.test.ts

@@ -45,6 +45,8 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/notify-verify.ts",
       "packages/core/src/notify.ts",
+      "packages/core/src/op/gate-approval-base.ts",
+      "packages/core/src/op/gate-plan-context.ts",
       "packages/core/src/op/gate-point.ts",
       "packages/core/src/op/gate-quorum.ts",
       "packages/core/src/op/op-waves.ts",
@@ -55,8 +57,8 @@ describe("the gate-decision bundle", () => {
       "packages/core/src/workspace/jsonc.ts",
       "packages/core/src/workspace/trust/trust-files.ts",
     ]);
-    // About 49 KB unminified today: 7 KB of it the pinned classes read as data (#3888), 6 KB the approval rules (#4290).
+    // About 49 KB unminified today: 7 KB of it the pinned classes read as data (#3888), 6 KB the approval rules (#4290), and the base approval checks (#4404) bring it to about 55 KB.
     const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
-    expect(bytes).toBeLessThan(54 * 1024);
+    expect(bytes).toBeLessThan(58 * 1024);
   });
 });

package/src/gate-decision-identity.test.ts

@@ -19,6 +19,7 @@ import {
 import { gateAdmission } from "./workspace/identity";
 import { hasSshKeygen, TestRepo, type Key } from "./workspace/trust/test-repo";
 import { evaluateGate, memoryGateLedgerPort } from "./op/gate";
+import { gatePolicyVersion } from "./op/gate-approval";
 
 const D1 = "sha256:" + "a".repeat(64);
 const GATES = { ship: {}, deploy: { class: "human" }, release: { class: "runner" }, ops: { class: "operator" } };
@@ -227,6 +228,16 @@ describe.skipIf(!hasSshKeygen)("identity.gates read at base, as chant reads it",
     expect(here.requirement.quorum).toEqual(gateAdmission(r.dir, "ship", base)!.requirement.quorum);
     expect(identityGateAdmissionAt(r.dir, base, "deploy")!.requirement).toEqual({ gate: "deploy", class: "human" });
   });
+
+  test("a gate's policy, mode and context at base, as chant reads them (#4404)", () => {
+    const text = "permit (principal, action, resource);";
+    const policy = { kind: "gate-policy", lexicon: "cedar", name: "ship", version: gatePolicyVersion(text), text };
+    const { r, base } = setup(() => ({}), { identity: { gates: { ship: { policy, mode: "enforce", context: { risk: "high" } } } } });
+    const here = identityGateAdmissionAt(r.dir, base, "ship")!.requirement;
+    const theirs = gateAdmission(r.dir, "ship", base)!.requirement;
+    expect(here).toMatchObject({ policy, mode: "enforce", context: { risk: "high" } });
+    expect({ policy: here.policy, mode: here.mode, context: here.context }).toEqual({ policy: theirs.policy, mode: theirs.mode, context: theirs.context });
+  });
 });
 
 describe("admitApprover", () => {

package/src/gate-decision.ts

@@ -67,6 +67,8 @@ import { diskFiles, findInstalledPackage, mergePinClasses, parseClassDataByHand,
 import type { GateResolutionRecord, PendingGateRecord } from "./lifecycle/gate-ledger";
 import type { MergedReview } from "./op/gate-review";
 import { quorumProblems as quorumProblemsOf, type GateQuorumSpec as QuorumSpec } from "./op/gate-quorum";
+import { gateBaseApprovalProblems } from "./op/gate-approval-base";
+import type { GateApprovalMode, GatePolicyRef } from "./op/gate-approval";
 import type { GateApprovalSource } from "./op/op-waves";
 
 export { GATE_APPROVAL_SOURCES, type GateApprovalSource } from "./op/op-waves";
@@ -230,6 +232,14 @@ export interface IdentityGate {
    * this name takes in place of its own. Absent when the entry sets none.
    */
   quorum?: QuorumSpec;
+  /**
+   * `identity.gates.<gate>.policy`, `.mode` and `.context` (#4404): what an Op
+   * gate of this name takes in place of its own `approval` fields. Each is
+   * absent when the entry sets none.
+   */
+  policy?: GatePolicyRef;
+  mode?: GateApprovalMode;
+  context?: Record<string, string | number | boolean | string[]>;
 }
 
 /** The declaration at `base`, parsed, or null when there is none. Throws when it cannot be parsed. */
@@ -245,13 +255,23 @@ function declarationAt(repo: string, base: string): { file: string; value: unkno
 }
 
 function identityGatesOf(declaration: unknown): IdentityGate[] {
-  const gates = (declaration as { identity?: { gates?: Record<string, { class?: unknown; quorum?: unknown } | null> } } | null)?.identity?.gates ?? {};
+  const gates = (declaration as { identity?: { gates?: Record<string, { class?: unknown; quorum?: unknown; policy?: unknown; mode?: unknown; context?: unknown } | null> } } | null)?.identity?.gates ?? {};
   return Object.entries(gates).map(([gate, entry]) => {
-    if (entry?.quorum === undefined) return { gate, class: typeof entry?.class === "string" ? entry.class : null };
-    // #4324: a quorum chant would refuse leaves the gate undecidable, as chant's own read does.
-    const [problem] = quorumProblemsOf(entry.quorum, `identity.gates.${gate}.quorum`, { notAuthor: false });
-    if (problem) throw new Error(`chant.workspace.json at base: ${problem.replace(/`/g, "")}, so the gate cannot be decided`);
-    return { gate, class: typeof entry.class === "string" ? entry.class : null, quorum: structuredClone(entry.quorum) as QuorumSpec };
+    const out: IdentityGate = { gate, class: typeof entry?.class === "string" ? entry.class : null };
+    if (!entry) return out;
+    if (entry.quorum !== undefined) {
+      // #4324: a quorum chant would refuse leaves the gate undecidable, as chant's own read does.
+      const [problem] = quorumProblemsOf(entry.quorum, `identity.gates.${gate}.quorum`, { notAuthor: false });
+      if (problem) throw new Error(`chant.workspace.json at base: ${problem.replace(/`/g, "")}, so the gate cannot be decided`);
+      out.quorum = structuredClone(entry.quorum) as QuorumSpec;
+    }
+    // #4404: the same for the policy, mode and context.
+    const [rest] = gateBaseApprovalProblems(entry, `identity.gates.${gate}`);
+    if (rest) throw new Error(`chant.workspace.json at base: ${rest.replace(/`/g, "")}, so the gate cannot be decided`);
+    if (entry.policy !== undefined) out.policy = structuredClone(entry.policy) as GatePolicyRef;
+    if (entry.mode !== undefined) out.mode = entry.mode as GateApprovalMode;
+    if (entry.context !== undefined) out.context = structuredClone(entry.context) as NonNullable<IdentityGate["context"]>;
+    return out;
   });
 }
 

package/src/lexicon.ts

@@ -1742,6 +1742,30 @@ export interface LexiconPlugin {
     changes: DisruptionQuery[];
   }): Record<string, DisruptionVerdict> | Promise<Record<string, DisruptionVerdict>>;
 
+  /**
+   * Classify the migration files a pull request adds (#4407), offline. Core
+   * lists the new files of a migration-directory workspace member (goose,
+   * golang-migrate, clickhouse-migrations, Flyway) and asks the lexicon whose
+   * dialect they are written in; the lexicon reads each file's up statements
+   * and gives each the class its schema-diff classifier gives the same change.
+   * A statement that alone cannot decide a class comes back `undecided`,
+   * naming the candidate rules. The answer is shown in the plan note; nothing
+   * is applied and no server is contacted. Omit for a lexicon with no
+   * migration dialect.
+   */
+  classifyMigrations?(options: {
+    /** The member's kind reader: `goose-dir`, `golang-migrate-dir`, `clickhouse-migrations-dir` or `flyway-dir`. */
+    reader: string;
+    /** The SQL dialect the member's migrations are written in. A lexicon answers only for its own dialects (an empty list otherwise). */
+    dialect: string;
+    /** The tree the files are read from (the pull request's head), rooted at the workspace root. */
+    tree: import("./workspace/tree").WorkspaceTree;
+    /** The member's directory in that tree; "" for the root. */
+    dir: string;
+    /** The new files to classify, relative to the workspace root. */
+    files: string[];
+  }): import("./pr-migrations").MigrationFileClassification[] | Promise<import("./pr-migrations").MigrationFileClassification[]>;
+
   /**
    * Report the undeclared resources this estate *depends on* (#1273), as
    * opposed to the ones it manages.

package/src/op/gate-approval-at-base.test.ts

@@ -0,0 +1,97 @@
+/**
+ * #4404: an Op gate's `policy`, `mode` and `context` are fields of
+ * `identity.gates.<gate>` in the workspace declaration at base, as the quorum
+ * is (#4324), so a change can't switch its own gate to `log-only` or swap in a
+ * permissive policy and be judged by that.
+ */
+
+import { afterEach, describe, expect, test } from "vitest";
+import type { GateStep, OpConfig } from "./types";
+import type { ActivityFn } from "./activity-registry";
+import { resolveGateApproval, runOpLocally } from "./local-executor";
+import { gitGateLedgerPort, memoryGateLedgerPort, type GateLedgerPort } from "./gate";
+import { gatePolicyVersion, type GatePolicyRef } from "./gate-approval";
+import { stepOutput } from "./step-output-ref";
+import { resetGateOrigin } from "../lifecycle/gate-origin";
+import { hasSshKeygen, TestRepo } from "../workspace/trust/test-repo";
+
+const policy = (name: string, text: string): GatePolicyRef => ({ kind: "gate-policy", lexicon: "cedar", name, version: gatePolicyVersion(text), text });
+const STRICT = policy("strict", "forbid unless maintainer");
+const PERMISSIVE = policy("permissive", "permit all");
+
+const step = (approval?: GateStep["approval"]): GateStep => ({ kind: "gate", gate: "ship", ...(approval ? { approval } : {}) }) as GateStep;
+
+describe("resolveGateApproval reads policy, mode and context at base (#4404)", () => {
+  test("the base policy and mode replace the Op's own", () => {
+    const opSide = step({ policy: PERMISSIVE, mode: "log-only" });
+    const got = resolveGateApproval(opSide, new Map(), undefined, null, { policy: STRICT, mode: "enforce" });
+    expect(got).toEqual({ policy: STRICT, mode: "enforce" });
+  });
+
+  test("a gate whose Op dropped its approval block still takes the base policy and mode", () => {
+    expect(resolveGateApproval(step(), new Map(), undefined, null, { policy: STRICT, mode: "enforce" })).toEqual({ policy: STRICT, mode: "enforce" });
+  });
+
+  test("a field the entry leaves out comes from the Op", () => {
+    const opSide = step({ policy: PERMISSIVE, mode: "enforce" });
+    expect(resolveGateApproval(opSide, new Map(), undefined, null, { mode: "log-only" })).toEqual({ policy: PERMISSIVE, mode: "log-only" });
+    expect(resolveGateApproval(opSide, new Map(), undefined, null, { policy: STRICT })).toEqual({ policy: STRICT, mode: "enforce" });
+  });
+
+  test("the base context wins key by key, and a key only the Op sets still reaches the policy", () => {
+    const opSide = step({ policy: STRICT, context: { risk: "low", team: "payments" } });
+    const got = resolveGateApproval(opSide, new Map(), undefined, null, { context: { risk: "high" } });
+    expect(got?.context).toEqual({ risk: "high", team: "payments" });
+  });
+
+  test("a step output reference in the Op's context still resolves beside a base key", () => {
+    const opSide = step({ policy: STRICT, context: { rows: stepOutput("verify", "rows") } });
+    const got = resolveGateApproval(opSide, new Map([["verify", { rows: 12 }]]), undefined, null, { context: { risk: "high" } });
+    expect(got?.context).toEqual({ risk: "high", rows: 12 });
+  });
+
+  test("with nothing at base, the Op's own applies", () => {
+    expect(resolveGateApproval(step({ policy: PERMISSIVE, mode: "enforce" }), new Map(), undefined, null, { policy: null, mode: null, context: null })).toEqual({ policy: PERMISSIVE, mode: "enforce" });
+    expect(resolveGateApproval(step(), new Map(), undefined, null, { policy: null, mode: null, context: null })).toBeUndefined();
+  });
+});
+
+describe.skipIf(!hasSshKeygen)("an Op gate's policy and mode at base (#4404)", () => {
+  const repos: TestRepo[] = [];
+  afterEach(() => {
+    resetGateOrigin();
+    while (repos.length) repos.pop()!.cleanup();
+  });
+
+  const declaration = (gate: Record<string, unknown>): string => JSON.stringify({ name: "acme", schema: 1, members: [], identity: { gates: { ship: gate } } });
+  const config = (approval: NonNullable<GateStep["approval"]>): OpConfig => ({
+    name: "release",
+    overview: "",
+    phases: [
+      { name: "Gate", steps: [{ kind: "gate", gate: "ship", approval }] },
+      { name: "Apply", steps: [{ kind: "activity", fn: "ship", args: {} }] },
+    ],
+  });
+  const activities = new Map<string, ActivityFn>([["ship", async () => ({})]]);
+
+  test("a change that switches its gate to a permissive log-only policy is judged by the base's", async () => {
+    const r = new TestRepo("4404-policy");
+    repos.push(r);
+    r.git(["config", "user.email", "t@example.test"]);
+    r.git(["config", "user.name", "t"]);
+    r.git(["config", "commit.gpgsign", "false"]);
+    r.write("chant.workspace.json", declaration({ policy: STRICT, mode: "enforce", context: { risk: "high" } }));
+    r.commit("base");
+    // The pull request rewrites the declaration's entry too; only base counts.
+    r.git(["checkout", "-q", "-b", "loosen"]);
+    r.write("chant.workspace.json", declaration({ policy: PERMISSIVE, mode: "log-only", context: { risk: "low" } }));
+    r.commit("loosen the gate");
+
+    const git = gitGateLedgerPort({ cwd: r.dir });
+    const gates: GateLedgerPort = { ...memoryGateLedgerPort(), approvalRule: git.approvalRule };
+    // The Op the change builds says permissive, log-only and low risk.
+    const run = await runOpLocally(config({ policy: PERMISSIVE, mode: "log-only", context: { risk: "low" } }), activities, {}, undefined, { gates, now: "2026-10-23T12:00:00.000Z" });
+    expect(run.status).toBe("gated");
+    expect(run.gate?.approval).toMatchObject({ policy: STRICT, mode: "enforce", context: { risk: "high" } });
+  });
+});

package/src/op/gate-approval-base.ts

@@ -0,0 +1,72 @@
+/**
+ * The parts of an Op gate's approval that an `identity.gates.<gate>` entry
+ * also carries (#4404): the modes, the policy check and the entry check. Its
+ * only runtime import is `node:crypto`, so `gate-decision.ts` (which checks an
+ * entry) bundles without the Op runtime or zod (gate-decision-bundle.test.ts).
+ * `gate-approval.ts` re-exports everything here.
+ */
+
+import { createHash } from "node:crypto";
+import { GATE_PLAN_CONTEXT_KEY } from "./gate-plan-context";
+import type { GateApprovalMode, GatePolicyRef } from "./gate-approval";
+
+export const GATE_APPROVAL_MODES: readonly GateApprovalMode[] = ["log-only", "enforce"];
+
+// The brand `stepOutput()` stamps (`step-output-ref.ts`), as a global symbol so
+// this module need not import that file and its zod schemas; the same copy
+// `activity-contract.ts` keeps for the same reason.
+const STEP_OUTPUT_REF_BRAND = Symbol.for("chant.op.stepOutputRef");
+function isStepOutputRef(value: unknown): boolean {
+  return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[STEP_OUTPUT_REF_BRAND] === true;
+}
+
+/** The version of a gate policy: `sha256:` and the hex digest of its text. A lexicon's helper stamps it, and OPS015 checks it still matches. */
+export function gatePolicyVersion(text: string): string {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+
+export function isGatePolicyRef(value: unknown): value is GatePolicyRef {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    v.kind === "gate-policy" &&
+    typeof v.lexicon === "string" && v.lexicon !== "" &&
+    typeof v.name === "string" && v.name !== "" &&
+    typeof v.version === "string" && v.version !== "" &&
+    typeof v.text === "string" && v.text.trim() !== ""
+  );
+}
+
+/**
+ * What is wrong with the `policy`, `mode` and `context` of an
+ * `identity.gates.<gate>` entry (#4404), one line each, named by `at`. Each
+ * field stands alone: base `mode: "enforce"` with no base `policy` is fine, as
+ * the Op's own policy then applies. `chant workspace check` (WSP153) says so.
+ */
+export function gateBaseApprovalProblems(entry: { policy?: unknown; mode?: unknown; context?: unknown }, at: string): string[] {
+  const problems: string[] = [];
+  if (entry.policy !== undefined) {
+    if (!isGatePolicyRef(entry.policy)) problems.push(`\`${at}.policy\` does not resolve to a gate policy set: it needs kind "gate-policy", lexicon, name, version and text`);
+    else if (entry.policy.version !== gatePolicyVersion(entry.policy.text)) problems.push(`\`${at}.policy\` "${entry.policy.name}" has a version that is not the digest of its text`);
+  }
+  if (entry.mode !== undefined && !GATE_APPROVAL_MODES.includes(entry.mode as GateApprovalMode)) {
+    problems.push(`\`${at}.mode\` must be one of ${GATE_APPROVAL_MODES.map((m) => `"${m}"`).join(", ")}`);
+  }
+  if (entry.context !== undefined) {
+    if (typeof entry.context !== "object" || entry.context === null || Array.isArray(entry.context)) problems.push(`\`${at}.context\` must be an object of plan attributes`);
+    else {
+      for (const [key, value] of Object.entries(entry.context)) {
+        if (key === GATE_PLAN_CONTEXT_KEY) problems.push(`\`${at}.context.${key}\` is reserved: the run fills it with the plan's change-set summary (#3182)`);
+        else if (isStepOutputRef(value) || !isContextValue(value)) problems.push(`\`${at}.context.${key}\` must be a string, number, boolean or list of strings`);
+      }
+    }
+  }
+  return problems;
+}
+
+export function isContextValue(value: unknown): boolean {
+  if (typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every((v) => typeof v === "string");
+  return isStepOutputRef(value);
+}