@intentius/chant 0.124.46 → 0.124.49

package/src/cli/handlers/release.ts

@@ -174,9 +174,12 @@ export async function runReleaseCut(ctx: CommandContext): Promise<number> {
       const { scopeSource } = await import("../../workspace/write-scope");
       const { releaseRuleFrom } = await import("../../workspace/identity");
       const source = scopeSource(cwd);
-      trunk = ws.resolveTrunk(top, source.declaration?.ci?.green?.branch ?? null);
+      const greenDecl = source.declaration?.ci?.green ?? null;
+      const primary = ws.resolveTrunk(top, greenDecl?.branch ?? null);
+      trunk = primary;
       try {
-        ws.checkOnTrunk(top, commit, trunk);
+        // #4325: a commit of a branch ci.green also judges (one ci.branches routes members to) is cut like trunk's.
+        trunk = ws.checkOnGreenBranches(top, commit, primary, (greenDecl?.branches ?? []).slice(1));
       } catch (err) {
         // #4168 4.3: a commit of a pushed compose branch is cut too, and the cut records what it carries.
         if (!(err instanceof ws.WorkstationCheckError) || err.code !== "release-commit-not-on-trunk") throw err;
@@ -552,7 +555,7 @@ export async function runReleaseVerify(ctx: CommandContext): Promise<number> {
  */
 export async function runReleaseCandidates(ctx: CommandContext): Promise<number> {
   const { releaseCandidatesDocument } = await import("../../workspace/release-candidates");
-  const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}) });
+  const doc = await releaseCandidatesDocument({ cwd: resolve("."), ...(ctx.args.env ? { env: ctx.args.env } : {}), ...(ctx.args.branch ? { branch: ctx.args.branch } : {}) });
   if (ctx.args.json) {
     console.log(JSON.stringify(doc, null, 2));
     return "error" in doc ? 1 : 0;

package/src/cli/handlers/search.ts

@@ -22,6 +22,7 @@ import { collectBuildRootContributors, loadPlugins, resolveProjectLexicons } fro
 import { declaredBuildRootContributors, mergeDeclaredBuildRoots, withLexiconEdges } from "./declared-graph";
 import { parseCountBy, countGroups, countsJson, formatCounts, groupMembers, hasManyTerraformRoots, type CountBy } from "./search-count";
 import { formatError, formatWarning } from "../format";
+import { adjacencyOf, walkBreadthFirst } from "../../graph-walk";
 import type { CommandContext } from "../registry";
 import { SEARCH_CONTRACT_VERSION, SEARCH_OUTPUT_SCHEMA_ID, type SearchErrorCode, type SearchFailure, type SearchHead } from "../../workspace/search-contract";
 
@@ -1870,13 +1871,7 @@ const adjacency = new WeakMap<GraphIR, { out: Map<string, IREdge[]>; in: Map<str
 function edgeIndex(ir: GraphIR): { out: Map<string, IREdge[]>; in: Map<string, IREdge[]> } {
   let idx = adjacency.get(ir);
   if (!idx) {
-    idx = { out: new Map(), in: new Map() };
-    for (const e of ir.edges ?? []) {
-      if (!idx.out.has(e.from)) idx.out.set(e.from, []);
-      idx.out.get(e.from)!.push(e);
-      if (!idx.in.has(e.to)) idx.in.set(e.to, []);
-      idx.in.get(e.to)!.push(e);
-    }
+    idx = adjacencyOf(ir.edges ?? []);
     adjacency.set(ir, idx);
   }
   return idx;
@@ -1894,17 +1889,14 @@ function sameName(a: string | undefined, b: string): boolean {
  * the target leaf (any node when the term has none) at a depth inside the
  * term's range. A plain `->`/`<-` is the range 1..1.
  *
- * Termination on a cycle: a state is (node, depth capped at the range's
- * minimum). Past the minimum, arriving at a node again by a longer walk can
- * reach nothing the first arrival could not, so it is not queued twice. The
- * state space is finite and the walk always ends.
+ * The walk is `walkBreadthFirst` (graph-walk.ts), shared with carve's
+ * reachability (#2325); it is what terminates on a cycle.
  */
 function findPath(n: IRNode, t: Term, ir: GraphIR, byId: Map<string, IRNode>): PathHop[] | null {
   if (t.kind !== "edge") return null;
   const { min, max } = t.depth ?? { min: 1, max: 1 };
   const idx = edgeIndex(ir);
   const out = t.dir === "out";
-  type State = { id: string; depth: number; hops: PathHop[] };
   // A capability edge (#4375) stands for the hops that proved it.
   const steps = (id: string): { far: string; hops: PathHop[] }[] => {
     if (t.capability !== undefined) return capabilitySteps(id, t.capability, out, ir);
@@ -1915,28 +1907,15 @@ function findPath(n: IRNode, t: Term, ir: GraphIR, byId: Map<string, IRNode>): P
         hops: [{ from: e.from, ...(e.viaAttr ? { fromAttr: e.viaAttr } : {}), to: e.to, ...(e.toAttr ? { toAttr: e.toAttr } : {}) }],
       })));
   };
-  const seen = new Set<string>([`${n.id}|0`]);
-  let frontier: State[] = [{ id: n.id, depth: 0, hops: [] }];
-  while (frontier.length > 0) {
-    const next: State[] = [];
-    for (const s of frontier) {
-      if (s.depth >= max) continue;
-      for (const step of steps(s.id)) {
-        const farId = step.far;
-        const far = byId.get(farId);
-        if (!far) continue;
-        const depth = s.depth + 1;
-        const hops = [...s.hops, ...step.hops];
-        if (depth >= min && (!t.sub || matchTerm(far, t.sub, ir, byId))) return hops;
-        const key = `${farId}|${Math.min(depth, min)}`;
-        if (seen.has(key)) continue;
-        seen.add(key);
-        next.push({ id: farId, depth, hops });
-      }
-    }
-    frontier = next;
-  }
-  return null;
+  // A node the graph does not hold is no step at all, and the match is the
+  // first arrival in range that satisfies the target leaf (#4359).
+  const found = walkBreadthFirst<PathHop>(n.id, {
+    min,
+    max,
+    steps: (id) => steps(id).filter((step) => byId.has(step.far)),
+    arrive: ({ id }) => !t.sub || matchTerm(byId.get(id)!, t.sub, ir, byId),
+  });
+  return found ? found.hops : null;
 }
 
 function bareId(id: string): string {

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,11 +869,14 @@ describe("workspace init and ls (#2534)", () => {
       "workspace patch",
       "workspace pin",
       "workspace points",
+      "workspace promote",
       "workspace records",
+      "workspace run",
       "workspace runs",
       "workspace search",
       "workspace signers",
       "workspace status",
+      "workspace train",
       "workspace trust",
       "workspace upgrade",
       "workspace verify",
@@ -882,6 +886,19 @@ describe("workspace init and ls (#2534)", () => {
     ]);
   });
 
+  test("run and train take their targets and flags (#2554)", () => {
+    const run = parseArgs(["workspace", "run", "api/deploy", "web/deploy", "--gate", "release", "--env", "prod"]);
+    expect(run).toMatchObject({ command: "workspace", path: "run", positionals: ["run", "api/deploy", "web/deploy"], gate: "release", env: "prod" });
+    expect(resolveCommand(run, commandRegistry)?.def.name).toBe("workspace run");
+    expect(parseArgs(["workspace", "run", "--dependents-of", "network", "--op", "deploy"])).toMatchObject({ dependentsOf: "network", op: "deploy" });
+    expect(() => parseArgs(["workspace", "run", "--dependents-of"])).toThrow(/--dependents-of needs a member/);
+    const train = parseArgs(["workspace", "train", "prod", "--pin", "api=v2", "--pin", "web=v1"]);
+    expect(train).toMatchObject({ positionals: ["train", "prod"], pins: ["api=v2", "web=v1"] });
+    expect(resolveCommand(train, commandRegistry)?.def.name).toBe("workspace train");
+    expect(() => parseArgs(["workspace", "train", "prod", "--pin", "api"])).toThrow(/--pin needs a member and a release/);
+    expect(parseArgs(["workspace", "lint", "--cross-root", "--format", "json"])).toMatchObject({ path: "lint", crossRoot: true, format: "json" });
+  });
+
   test("adopt-lineage, hash-index, versions and upgrade --source take their flags (#2551)", () => {
     const adopt = parseArgs(["workspace", "adopt-lineage", "app", "--from", "acme/starter#svc", "--tags", "v*", "--index", "i.json", "--param", "name=x", "--dry-run"]);
     expect(adopt).toMatchObject({ command: "workspace", path: "adopt-lineage", extraPositional: "app", migrateFrom: "acme/starter#svc", tags: "v*", index: "i.json", param: ["name=x"], dryRun: true });

package/src/cli/main.ts

@@ -183,7 +183,14 @@ Commands:
                         the resources and snapshots each lexicon observed, Op
                         runs, gates, deploys, releases and cuts, loaded into
                         node:sqlite (schema v1, listed in chant_schema).
-                        --member <name> keeps members; --json prints rows
+                        --member <name> keeps members; --json prints rows.
+                        For a read contract, use chant ledger
+  ledger <table> [dir]  One ledger's rows from chant/lifecycle as a read
+                        contract (resources, snapshots, runs, gates, deploys,
+                        releases, cuts; the columns chant query loads).
+                        --where <field><op><value> (= != < <= > >= ~,
+                        repeatable), --since <time|7d>, --at <rev> of
+                        chant/lifecycle, --member <name>, --json
   generate             Generate typed code from sources chant.config declares
                         (k8s.crds, helm.charts) into src/generated/<lexicon>/
                         (codegen.outDir); --check exits 1 when the committed
@@ -607,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
@@ -626,7 +643,7 @@ Workspace (level 1, #2524):
                         restore, from the deploy records, releases and ci
                         revoked tags. Eight weeks back by default. Read only;
                         never fetches. --json prints the read-contract document
-  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--json]
+  workspace records [--kind <kind file>] [--current] [--uncommitted | --at <rev>] [--base <rev>] [--require attested] [--where <field><op><value>]... [--json]
                         Without --kind, every record kind the declaration
                         names. Read the records a record kind locates, validated
                         against its schema, with reason codes for invalid
@@ -639,7 +656,9 @@ Workspace (level 1, #2524):
                         asset-drift or asset-missing. In the working tree,
                         each record says whether it is committed, modified
                         or new against HEAD, with the branch and base;
-                        --uncommitted lists only the modified and new ones
+                        --uncommitted lists only the modified and new ones;
+                        --where keeps the records a typed filter matches
+                        (id, path, state, valid, data.<key>, ...)
   workspace records [--kind <kind file>] --since <rev|session id> [--at <rev>] [--json]
                         What changed in the records between <rev> and --at
                         (default: the working tree): new and removed records,
@@ -709,14 +728,16 @@ Workspace (level 1, #2524):
                         a url or a path pinned by hash) is appended to the
                         item's pins through records amend. Prints the
                         work-evidence document and never commits
-  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--follow-squash] [--json]
+  workspace runs [--unit <id>] [--decision <id>] [--by <principal>] [--since <rev>] [--where <field><op><value>]... [--follow-squash] [--json]
                         The agent runs in the run ledger on chant/lifecycle, each
                         with its model, tokens, cost and the commits it made,
                         and totals per work item, decision and principal; a run
                         that reports no cost is listed as unpriced, never zero.
                         Read-only, never fetches; --follow-squash joins each
                         squash merge to its pull request's runs, fetching a
-                        missing refs/pull/<n>/head from origin
+                        missing refs/pull/<n>/head from origin; --where keeps
+                        the runs a typed filter matches (state, model,
+                        startedAt, cost.amount, ...) before the totals
   workspace runs start --from <file|->
                         Record that an agent run started: who it worked for,
                         its harness, model, work item and lease. Prints the run
@@ -850,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,
@@ -888,7 +918,7 @@ Workspace (level 1, #2524):
   workspace admit <return id> [--note <text>] [--dry-run] [--json]
                         Admit the signers of a return in .chant/trust.json, so
                         its signed work reads as attested once merged
-  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>]
+  workspace check [--at <rev>] [--json] [--format stylish|json|sarif] [--generated] [--kind <kind file>] [--live --env <env>] [--forge-repos <file>]
                         Fail on an unreadable lineage lock or an open manual
                         step, and, in a declared workspace, on a WSP check of
                         the declaration, member ledgers, pipelines or
@@ -900,7 +930,10 @@ Workspace (level 1, #2524):
                         resolves each declared member link against the live
                         graph of <env> (each chant member runs chant graph
                         --live, which reaches the account) and reports
-                        WSP141 and WSP142
+                        WSP141 and WSP142. --forge-repos reads a forge's
+                        repository list from a file and reports repos an
+                        org workspace lacks (WSP014) or names that the
+                        forge no longer has (WSP015)
   workspace check --changes <base>..<head> [--work <id>] [--severity off|warn|fail] [--kind <kind file>...] [--json]
                         Map each path the diff changes to the current records
                         whose constrains cover it: change-uncovered when none
@@ -928,9 +961,12 @@ Workspace (level 1, #2524):
                         its own chant, one process per toolchain. -o <dir>
                         writes <dir>/<member>.json; --member narrows the run;
                         --dry-run prints which chant runs which project
-  workspace lint [dir] [--format stylish|json|sarif] [--member <name>]
+  workspace lint [dir] [--format stylish|json|sarif] [--member <name>] [--cross-root]
                         Lint every chant member and example project with its
-                        own chant; sarif writes one run per member
+                        own chant; sarif writes one run per member.
+                        --cross-root adds the disagreement lint (LNK001 and
+                        the lexicons' cross-root checks) over every member's
+                        graph, where declared links and the graphs disagree
   workspace audit [dir] [--json] [--member <name>]
                         Audit each chant member with its own .chant-audit.json;
                         every finding carries a member field
@@ -967,6 +1003,29 @@ Workspace (level 1, #2524):
                         One decision's intent walk over every path: and member:
                         entry it constrains: the commits in its window, each
                         own, worked, within-other or unexplained, with counts
+  workspace run <member>/<op>... [--env <env>] [--gate <name>] [--on <lexicon>] [--dry-run] [--json]
+                        Run Ops that span members (#2554): each target's chant
+                        run <op> in the member's directory, under its own
+                        chant, producers before the members that link to them.
+                        OPS019 checks every target against the composed graph
+                        first. Member run records cite the workspace run,
+                        whose record goes under _members/_workspace/<env>/.
+                        Exits 3 when a step stops at a gate
+  workspace run --dependents-of <member> --op <op> [--env <env>] [--gate <name>] [--dry-run] [--json]
+                        Run <op> in every member that links to <member>,
+                        directly or not, nearest first; members without the
+                        Op are listed as skipped
+  workspace run approve <gate> [--plan <digest>] [--approver <principal>]
+                        Approve a workspace gate's pending fact. It stands in
+                        for a member gate only when it covers that member's
+                        plan and the member sets acceptWorkspaceGates at base
+  workspace train <env> [--pin <member>=<label|digest>]... [--dry-run] [--json]
+                        Record a release train: one cut release of every
+                        chant member (the newest, unless --pin picks one),
+                        under _members/_workspace/<env>/trains.jsonl. Refuses
+                        when a member has no release
+  workspace train list <env> [--json]
+                        The release trains recorded for <env>, oldest first
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
@@ -1040,7 +1099,9 @@ Component release ledger + status:
                             from the report pr-plan --no-status wrote
                             (--pr <n> --head <sha> --env <env> --forge
                             <kind>), in a job that runs none of the
-                            change's code (#4295)
+                            change's code (#4295); --open posts every
+                            open merge request's from a GitLab pipeline
+                            of the target branch (#4328)
   components pr-record     On merge (#4168): plan the same members again,
                             store the change set and write the merge record
                             _merges/<commit>.json; applies and refuses
@@ -1198,12 +1259,16 @@ Options:
                         JSON (lifecycle plan)
                         OR '--report markdown': emit a reviewer-facing markdown
                         render, holes and disruption included (lifecycle plan)
-  --from <name>         Source lexicon for migrate (default: github)
-  --to <name>           Target lexicon for migrate (default: gitlab)
-  --emit <fmt>          Migration output format: yaml (default) or ts
+  --from <name>         Source for migrate: a lexicon, or lexicon/dialect such
+                        as sql/postgres (default: github)
+  --to <name>           Target for migrate, same form, such as sql/clickhouse
+                        (default: gitlab)
+  --emit <fmt>          Migration output format: yaml (default), ts, or sql;
+                        sql/clickhouse defaults to ts
   --strict              Escalate needs-review/validation to errors (migrate);
                         exit nonzero on an unresolved identity (lifecycle whoami)
-  --validate            Run external validator (glci/glab) after migrate
+  --validate            Run external validator after migrate: glci/glab, or the
+                        ClickHouse emulator for sql/clickhouse
   --use-composites      Rewrite to composite calls when patterns match (migrate)
   --components          Target discovered Component declarations instead of
                         lexicon resources (list, describe, graph, build, run)
@@ -1498,6 +1563,7 @@ export const commandRegistry: CommandDef[] = [
   { name: "search", handler: runSearch },
   // #4297 — SQL over the snapshots, runs, gates, deploys and releases on chant/lifecycle. Imported on first use.
   { name: "query", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/query")).runQueryCommand(ctx) },
+  { name: "ledger", runsNoConfig: true, handler: async (ctx) => (await import("./handlers/ledger")).runLedgerCommand(ctx) },
   // chant#2591 — `import --agents` and `audit` read chant.config statically
   // and never evaluate it (chant#2589 for audit, which audits code it must not run).
   { name: "import", handler: runImport, runsNoConfig: (args) => args.agents === true },
@@ -1608,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) },
@@ -1629,6 +1698,10 @@ export const commandRegistry: CommandDef[] = [
   { name: "workspace audit", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "audit") },
   { name: "workspace graph", handler: async (ctx) => (await import("../workspace/member-commands")).runWorkspaceMembers(ctx, "graph") },
   // #4374 — chant search in every member, under its own chant, composed with workspace graph's ids: the search document.
+  // #2554 — Ops that span members, as <member>/<op> targets, each run under its member's own chant.
+  { name: "workspace run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/workspace-run")).runWorkspaceRun(ctx) },
+  // #2554 — a release train: one release of every chant member, pinned in the workspace ledger.
+  { name: "workspace train", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/release-train")).runWorkspaceTrain(ctx) },
   { name: "workspace search", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/search-cli")).runWorkspaceSearch(ctx) },
   // Each unit decides for itself whether its config is loaded (runCommandInProcess).
   { name: "workspace member-run", runsNoConfig: true, handler: async (ctx) => (await import("../workspace/member-run")).runWorkspaceMemberRun(ctx, runCommandInProcess) },

package/src/cli/parse-args.ts

@@ -47,6 +47,7 @@ const BOOLEAN_FLAGS = new Set([
   "--up",
   "--down",
   "--include-dependents",
+  "--cross-root",
   "--local",
   "--json",
   "--progress-json",
@@ -283,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") {
@@ -380,6 +384,19 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.head = args[++i];
     } else if (arg === "--include-dependents") {
       result.includeDependents = true;
+    } else if (arg === "--cross-root") {
+      // `chant workspace lint --cross-root` (#2549): the disagreement lint over every member's graph.
+      result.crossRoot = true;
+    } else if (arg === "--dependents-of") {
+      // `chant workspace run --dependents-of <member> --op <op>` (#2554).
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--dependents-of needs a member name: --dependents-of <member>");
+      result.dependentsOf = value;
+    } else if (arg === "--pin") {
+      // `chant workspace train <env> --pin <member>=<label|digest>` (#2554), repeatable.
+      const value = args[++i];
+      if (!value || value.startsWith("-") || !value.includes("=")) throw new Error("--pin needs a member and a release: --pin <member>=<label|digest>");
+      (result.pins ??= []).push(value);
     } else if (arg === "--from-affected") {
       result.fromAffected = args[++i];
     } else if (arg === "--gate") {
@@ -908,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];
@@ -932,8 +954,8 @@ export function parseArgs(args: string[]): ParsedArgs {
     } else if (arg === "--expire") {
       result.expire = true;
     } else if (arg === "--role") {
-      // #2508 — a role the approver claims, which a gate's policy sees. A
-      // quorum reads roles from .chant/trust.json at base instead (#4290).
+      // #2508 — a role the approver claims, recorded on the approval. A quorum
+      // (#4290) and a gate policy (#4324) read roles from .chant/trust.json at base.
       // Repeatable, and a comma list works too.
       const value = args[++i] ?? "";
       result.roles = [...(result.roles ?? []), ...value.split(",").map((r) => r.trim()).filter(Boolean)];
@@ -971,6 +993,12 @@ export function parseArgs(args: string[]): ParsedArgs {
       // #2537 — `chant build` and `chant lint` at a declared workspace root
       // run on the root project alone instead of refusing with WSP000.
       result.rootOnly = true;
+    } else if (arg === "--forge-repos") {
+      // #3168 — `chant workspace check --forge-repos <file>`: the forge's
+      // repository list, as a warden reads it, for an org workspace's checks.
+      const value = args[++i];
+      if (!value || value.startsWith("-")) throw new Error("--forge-repos needs a file: --forge-repos <repos.json>");
+      result.forgeRepos = value;
     } else if (arg === "--generated") {
       // #2641 — `chant workspace check --generated` runs each declared
       // generator and compares its output with the file in the tree.
@@ -991,6 +1019,11 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.url = args[++i];
     } else if (arg === "--op") {
       result.op = args[++i];
+    } else if (arg === "--where") {
+      // #4363 — a typed filter on a contract read; repeatable, every clause has to hold.
+      const value = args[++i];
+      if (value === undefined || value.startsWith("--")) throw new Error("--where needs a clause: --where <field><op><value>");
+      result.where = [...(result.where ?? []), value];
     } else if (arg === "--since") {
       result.since = args[++i];
     } else if (arg === "--limit") {

package/src/cli/registry.ts

@@ -83,7 +83,7 @@ export interface ParsedArgs {
   /** `chant run events <run> --follow` (#4042) — stream the run's events as they happen, until `run-settle`. */
   follow?: boolean;
   live: boolean;
-  /** `chant migrate --from <name>` (default "github") */
+  /** `chant migrate --from <name>` (default "github"); `lexicon/dialect` for the sql lexicon */
   migrateFrom?: string;
   /** `chant import --kustomize <dir>` — render the kustomization, then import (#1548) */
   kustomize?: string;
@@ -103,9 +103,9 @@ export interface ParsedArgs {
   write?: boolean;
   /** `chant carve apply --write-source` — stamp the ownership marker into the emitted source */
   writeSource?: boolean;
-  /** `chant migrate --to <name>` (default "gitlab") */
+  /** `chant migrate --to <name>` (default "gitlab"); `lexicon/dialect` for the sql lexicon */
   migrateTo?: string;
-  /** `chant migrate --emit yaml|ts` */
+  /** `chant migrate --emit yaml|ts|sql` */
   emit?: string;
   /** Escalate needs-review diagnostics to errors (migrate command) */
   strict?: boolean;
@@ -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;
@@ -263,6 +265,12 @@ export interface ParsedArgs {
   head?: string;
   /** `chant lifecycle affected --include-dependents` — add downstream consumers */
   includeDependents?: boolean;
+  /** `chant workspace run --dependents-of <member> --op <op>` (#2554): run the Op in every member that links to this one, directly or not. */
+  dependentsOf?: string;
+  /** `chant workspace lint --cross-root` (#2549): also run the disagreement lint and the lexicons' cross-root checks over every member's graph. */
+  crossRoot?: boolean;
+  /** `chant workspace train <env> --pin <member>=<label|digest>` (#2554), repeatable: the release a train pins for that member instead of its newest. */
+  pins?: string[];
   /**
    * `chant components fan-out --from-affected <file>` (#2420) — read the
    * stack-level change signal from the JSON `chant lifecycle affected --json`
@@ -622,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). */
@@ -640,6 +654,8 @@ export interface ParsedArgs {
    * generators run member code.
    */
   generated?: boolean;
+  /** `chant workspace check --forge-repos <file>` (#3168): the forge's repository list, checked against an org workspace's repo members (WSP014, WSP015). */
+  forgeRepos?: string;
   /**
    * `chant workspace build|lint|audit|graph --member <name>` (#2537): run only
    * the named members or example groups. Repeatable, and a comma list works too.
@@ -788,7 +804,7 @@ export interface ParsedArgs {
    * on a model-authored channel.
    */
   allowSameOrigin?: boolean;
-  /** `chant approve --role <name>` (#2508) — roles the approver claims, which a gate's policy sees. A quorum never counts them (#4290): its roles come from `.chant/trust.json` at base. Repeatable; a comma list also works. */
+  /** `chant approve --role <name>` (#2508) — roles the approver claims, recorded on the approval. Nothing trusts them: a quorum (#4290) and a gate policy (#4324) read roles from `.chant/trust.json` at base, for a sealed approval. Repeatable; a comma list also works. */
   roles?: string[];
   /** `chant approve --agent` (#2508) — record the approval as an agent's. An agent never counts toward a quorum; it passes a gate only through a policy permit in `enforce` mode. */
   agent?: boolean;
@@ -798,6 +814,8 @@ export interface ParsedArgs {
   op?: string;
   /** `chant operator log --since <iso>` (#2029) — only entries at or after this ISO-8601 instant. `chant workspace records --since <rev>` (#2673) — the revision to compare the records with. `chant workspace metrics --since <date>` (#4039) — the start of the window the metrics count. */
   since?: string;
+  /** `chant ledger`, `chant workspace records` and `chant workspace runs --where <field><op><value>` (#4363): typed filters, repeatable, all of which have to hold. */
+  where?: string[];
   /** `chant operator log --limit <n>` (#2029) — keep only the newest n entries (still printed oldest-first). */
   limit?: number;
   /** `chant approve <op> <gate> --url <url>` (#2028) — the address this resolution happened at (the PR/MR that carried the change), recorded typed on the gate-resolution fact so a reader is not sniffing `--note` for something link-shaped. Defaults to the PR/MR the surrounding CI job is for, when there is one. Must be an absolute http/https URL. */

package/src/components/builders.ts

@@ -19,6 +19,8 @@ import type {
   ZipPackageInput,
   JvmBuildInput,
   GenerateSbomInput,
+  PublishImageInput,
+  PublishArtifactInput,
   SignInput,
   AttestProvenanceInput,
   VerifyInput,
@@ -64,6 +66,12 @@ export const vulnGate = step<VulnGateInput>("vuln-gate");
 // The cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`)
 // ship as builders from the aws lexicon, alongside their capabilities.
 export const waitClusterHealthy = step<WaitClusterHealthyInput>("wait-cluster-healthy");
+// ── publish (core owns the verb; each cloud lexicon contributes a registry login backend) ──
+export const publishImage = step<PublishImageInput>("publish-image");
+export const publishArtifact = step<PublishArtifactInput>("publish-artifact");
+/** Alias for {@link publishArtifact}. */
+export const publishAsset = publishArtifact;
+
 export const waitEndpoint = step<WaitEndpointInput>("wait-endpoint");
 export const healthGate = step<HealthGateInput>("health-gate");
 

package/src/components/capability-plugin-loader.ts

@@ -26,6 +26,8 @@ import { lexiconModulePath, importLexiconPackage } from "../lexicon-module";
 import type { CapabilityPlugin } from "./capability-plugin";
 import { isCapabilityPlugin } from "./capability-plugin";
 import { starterCapabilityPlugin } from "./starter-plugin";
+import { isRegistryBackendConsumer, type RegistryLoginBackend } from "./verbs/publish-image";
+import { isStorageBackendConsumer, type ArtifactStorageBackend } from "./verbs/publish-artifact";
 
 /** Thrown when a dynamically-imported capability package does not satisfy `CapabilityPlugin` — the "malformed capability package" case #559 asks doctor/validation to detect. */
 export class MalformedCapabilityPluginError extends Error {
@@ -165,9 +167,19 @@ export function registerCapabilityPlugins(
     }
   }
 
+  const backends: RegistryLoginBackend[] = [];
+  for (const plugin of plugins) backends.push(...(plugin.registryBackends?.() ?? []));
+  const storage: ArtifactStorageBackend[] = [];
+  for (const plugin of plugins) storage.push(...(plugin.storageBackends?.() ?? []));
+
   for (const plugin of plugins) {
     for (const capability of plugin.capabilities()) {
-      registry.register(capability);
+      // A capability that consumes registry login backends (`publish-image`)
+      // is re-bound to the backends of the plugins loaded for this registry.
+      let bound = capability;
+      if (isRegistryBackendConsumer(bound)) bound = bound.withRegistryBackends(backends) as typeof bound;
+      if (isStorageBackendConsumer(bound)) bound = bound.withStorageBackends(storage) as typeof bound;
+      registry.register(bound);
     }
   }
   return registry;

package/src/components/capability-plugin.ts

@@ -32,6 +32,8 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { Capability } from "./capability";
+import type { RegistryLoginBackend } from "./verbs/publish-image";
+import type { ArtifactStorageBackend } from "./verbs/publish-artifact";
 
 /**
  * Manifest for a packaged capability plugin — the capability-side analogue
@@ -88,6 +90,20 @@ export interface CapabilityPlugin {
   /** Capability kinds grouped by family, informational — mirrors `STARTER_VERB_FAMILIES` (./registry.ts) shape for third-party plugins that want to publish the same grouping. */
   families?(): Record<string, readonly string[]>;
 
+  /**
+   * Registry login backends this plugin contributes to core's `publish-image`
+   * verb (aws: ECR, azure: ACR, gcp: Artifact Registry). Not capabilities, so
+   * several plugins may contribute without a duplicate-kind clash.
+   */
+  registryBackends?(): RegistryLoginBackend[];
+
+  /**
+   * Object-storage backends this plugin contributes to core's
+   * `publish-artifact` verb (aws: S3, azure: Blob, gcp: GCS). Like
+   * `registryBackends`, not capabilities, so several plugins may contribute.
+   */
+  storageBackends?(): ArtifactStorageBackend[];
+
   /** Optional initialization hook, called once after load (mirrors `LexiconPlugin.init`). */
   init?(): void | Promise<void>;
 }

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