@intentius/chant 0.124.45 → 0.124.48

package/src/graph-ir.ts

@@ -5,9 +5,12 @@ import { type Declarable, isDeclarable } from "./declarable";
 import { isLexiconOutput, type LexiconOutput } from "./lexicon-output";
 import { getProvenance } from "./provenance";
 import { INTRINSIC_MARKER } from "./intrinsic";
+import { subTemplateRefs } from "./graph-sub-template";
 import type { ResourceMetadata } from "./lexicon";
 import type { UnobservedEntity } from "./observation";
 
+export { subTemplateRefs };
+
 /**
  * Graph IR — the engine-neutral, lint-gated representation of a project's
  * resolved infrastructure graph. Painters (mermaid, graphviz, custom SVG) and
@@ -35,6 +38,21 @@ export interface AttrRefEnvelope {
   $ref: string;
 }
 
+/**
+ * A CloudFormation `Fn::Sub` in an attribute projection (#4373), in place of
+ * `{ $intrinsic: true }`. `$sub` is the template exactly as it serializes, so
+ * `${assets.Arn}/*` names the producer and attribute a reader would otherwise
+ * have to guess. `$vars` is the two-argument form's variable map, each value
+ * projected like any other attr. Every `${Name}` or `${Name.Attr}` in the
+ * template that names a node, and every reference in `$vars`, is also an edge.
+ * `${!Literal}` (CloudFormation's escape), pseudo-parameters (`${AWS::Region}`)
+ * and names `$vars` binds are not.
+ */
+export interface SubEnvelope {
+  $sub: string;
+  $vars?: Record<string, unknown>;
+}
+
 /** One resource in the graph. */
 export interface IRNode {
   /** Logical name (the export name, or composite-expanded name). */
@@ -192,6 +210,33 @@ export interface LexiconWorkspaceOutputs {
   gaps?: string[];
 }
 
+/**
+ * One link a lexicon reads from its own declarations (#4397): an output of
+ * another member that a declaration depends on, such as a table an otel
+ * `clickhouse` exporter writes.
+ */
+export interface LexiconWorkspaceLink {
+  /** The producer's output the declaration reads or writes: `default.otel_logs`, `default.otel_logs.Body`. */
+  output: string;
+  /**
+   * The output that picks the producer when `member` is unset; unset, the
+   * output itself. A column is anchored on its table, so a dropped column is
+   * missing from the member that still has the table.
+   */
+  anchor?: string;
+  /** The producer, when the declaration names it. Unset, the one member exposing `anchor`. */
+  member?: string;
+  /** The entity key that states the link, for the finding's file and line. */
+  entity: string;
+}
+
+/** What a lexicon's `workspaceLinks` hook returns (#4397). */
+export interface LexiconWorkspaceLinks {
+  links: LexiconWorkspaceLink[];
+  /** Places the hook could not read without the environment, one line each. Their links are left out. */
+  gaps?: string[];
+}
+
 /** What a lexicon's `graphEdges` hook returns (#3910). */
 export interface LexiconGraphEdges {
   references: LexiconGraphReference[];
@@ -465,6 +510,13 @@ export interface GraphIR {
    * the passes produced, not a list maintained by hand.
    */
   derivedAttrs?: Record<string, string[]>;
+  /**
+   * With `chant graph --format ir --capability-view` (#4378): the
+   * lexicon-neutral view capability rules read, built by this chant through
+   * the project's own lexicon mappings and adapters. A `ViewDocument`
+   * (`capabilities/view.ts`). Absent unless asked for.
+   */
+  capabilityView?: unknown;
 }
 
 /** A node is anything that serializes to a resource — not a property or output. */
@@ -499,6 +551,80 @@ function refIntrinsicTarget(value: unknown): string | undefined {
   return undefined;
 }
 
+/** A CloudFormation `Fn::Sub`: its template, and the variable map of the two-argument form. */
+interface SubForm {
+  template: string;
+  vars?: Record<string, unknown>;
+}
+
+/** Read `{ "Fn::Sub": "..." }` or `{ "Fn::Sub": ["...", { ... }] }`, or undefined. */
+function subForm(json: unknown): SubForm | undefined {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) return undefined;
+  const keys = Object.keys(json);
+  if (keys.length !== 1 || keys[0] !== "Fn::Sub") return undefined;
+  const arg = (json as Record<string, unknown>)["Fn::Sub"];
+  if (typeof arg === "string") return { template: arg };
+  if (Array.isArray(arg) && typeof arg[0] === "string") {
+    const vars = arg[1];
+    return vars !== null && typeof vars === "object" && !Array.isArray(vars)
+      ? { template: arg[0], vars: vars as Record<string, unknown> }
+      : { template: arg[0] };
+  }
+  return undefined;
+}
+
+/** The `Fn::Sub` an intrinsic serializes to (the aws `Sub` tag), or undefined. */
+function subIntrinsicForm(value: unknown): SubForm | undefined {
+  try {
+    return subForm((value as { toJSON?: () => unknown }).toJSON?.());
+  } catch {
+    // An AttrRef inside whose logical name is not set yet: no template to read.
+    return undefined;
+  }
+}
+
+/** False when an intrinsic's `toJSON()` throws (an AttrRef inside it has no logical name yet). */
+function serializes(value: unknown): boolean {
+  try {
+    (value as { toJSON?: () => unknown }).toJSON?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The logical names serialized CloudFormation JSON references: `{ Ref }`,
+ * `{ "Fn::GetAtt" }` in either encoding, and a nested `Fn::Sub`. Reads a
+ * two-argument `Sub`'s variable map after `toJSON()` has turned its live
+ * references into JSON.
+ */
+function cfnJsonRefNames(json: unknown, out: string[]): void {
+  if (json === null || typeof json !== "object") return;
+  if (Array.isArray(json)) {
+    for (const item of json) cfnJsonRefNames(item, out);
+    return;
+  }
+  const obj = json as Record<string, unknown>;
+  if (typeof obj.Ref === "string") {
+    out.push(obj.Ref);
+    return;
+  }
+  const getAtt = obj["Fn::GetAtt"];
+  if (getAtt !== undefined) {
+    const id = Array.isArray(getAtt) ? getAtt[0] : typeof getAtt === "string" ? getAtt.split(".")[0] : undefined;
+    if (typeof id === "string") out.push(id);
+    return;
+  }
+  const sub = subForm(obj);
+  if (sub) {
+    for (const r of subTemplateRefs(sub.template, new Set(Object.keys(sub.vars ?? {})))) out.push(r.name);
+    if (sub.vars) cfnJsonRefNames(Object.values(sub.vars), out);
+    return;
+  }
+  for (const v of Object.values(obj)) cfnJsonRefNames(v, out);
+}
+
 /** Resolve the producer (logical name) an AttrRef points at. */
 function refTarget(ref: AttrRef, reverse: Map<object, string>): string | undefined {
   // Nested refs (under `props`) aren't assigned a logical name by resolveAttrRefs,
@@ -545,6 +671,9 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
     // Ref to a non-node) stay opaque.
     const to = refIntrinsicTarget(value);
     if (to && nodeIds.has(to)) return { $ref: to } satisfies AttrRefEnvelope;
+    // A Sub keeps its template, so a reader sees which node and attribute it names (#4373).
+    const sub = subIntrinsicForm(value);
+    if (sub) return subEnvelope(sub, seen, reverse, nodeIds);
     return { $intrinsic: true };
   }
 
@@ -568,6 +697,14 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
     return out;
   }
 
+  // A Sub written as plain CloudFormation JSON reads the same as the `Sub` tag's.
+  const plainSub = subForm(value);
+  if (plainSub) {
+    const out = subEnvelope(plainSub, seen, reverse, nodeIds);
+    seen.delete(value);
+    return out;
+  }
+
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
     const p = project(v, seen, reverse, nodeIds);
@@ -577,6 +714,17 @@ function project(value: unknown, seen: Set<unknown>, reverse: Map<object, string
   return out;
 }
 
+/** Project a {@link SubForm} into its {@link SubEnvelope}. */
+function subEnvelope(sub: SubForm, seen: Set<unknown>, reverse: Map<object, string>, nodeIds: Set<string>): SubEnvelope {
+  if (!sub.vars) return { $sub: sub.template };
+  const vars: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(sub.vars)) {
+    const p = project(v, seen, reverse, nodeIds);
+    if (p !== undefined) vars[k] = p;
+  }
+  return { $sub: sub.template, $vars: vars };
+}
+
 // `references` and `stack` are the two duck-typed channels above
 // ({@link entityReferences}, {@link entityStack}). They are metadata about the
 // entity's place in the graph, not declared configuration, and both are read
@@ -645,6 +793,9 @@ function collectEdges(
     });
   }
   const seen = new Set<unknown>();
+  const edgeTo = (to: string, viaAttr: string): void => {
+    if (to !== from && nodeIds.has(to)) edges.push({ from, to, kind: "ref", viaAttr });
+  };
   const visit = (value: unknown, viaAttr: string): void => {
     if (value === null || typeof value !== "object") return;
     if (isAttrRefLike(value)) {
@@ -659,8 +810,31 @@ function collectEdges(
       // — resolve it to an edge instead of dropping it as an opaque intrinsic (#513).
       const to = refIntrinsicTarget(value);
       if (to && to !== from && nodeIds.has(to)) edges.push({ from, to, kind: "ref", viaAttr });
+      // A Sub's interpolations are references too (#4373): each `${Name}` or
+      // `${Name.Attr}` naming a node, and each reference in a variable map.
+      const sub = subIntrinsicForm(value);
+      if (sub) {
+        const names = subTemplateRefs(sub.template, new Set(Object.keys(sub.vars ?? {}))).map((r) => r.name);
+        if (sub.vars) cfnJsonRefNames(Object.values(sub.vars), names);
+        for (const name of names) edgeTo(name, viaAttr);
+      }
+      // The live values the aws `Sub` tag interpolated. Covers an AttrRef whose
+      // logical name was not set, where `toJSON()` throws and leaves no
+      // template to read above. Any other intrinsic stays opaque.
+      const interpolated = (value as { values?: unknown }).values;
+      if (Array.isArray(interpolated) && (sub || !serializes(value))) {
+        for (const v of interpolated) visit(v, viaAttr);
+      }
       return;
     }
+    // A Sub written as plain CloudFormation JSON in props: the template's names
+    // here, then the variable map's live values through the walk below.
+    const plainSub = subForm(value);
+    if (plainSub) {
+      for (const r of subTemplateRefs(plainSub.template, new Set(Object.keys(plainSub.vars ?? {})))) {
+        edgeTo(r.name, viaAttr);
+      }
+    }
     // A whole node held in props or an enumerable field (the sql lexicon's
     // `dependsOn`) is a reference to it: draw the edge, and do not walk its
     // config, whose refs belong to that node's own edges (#3257). Checked

package/src/graph-sub-template.ts

@@ -0,0 +1,22 @@
+// Kept apart from ./graph-ir so ./graph-detail, which runs in the browser
+// bundle, can read a Sub template without pulling in node:path.
+
+/**
+ * The names a `Sub` template interpolates (#4373): `${Name}` and
+ * `${Name.Attr}`, in order. Skips CloudFormation's `${!Literal}` escape,
+ * pseudo-parameters (`${AWS::Region}`, anything with `::`), and names the
+ * two-argument form's variable map binds, which are not resources.
+ */
+export function subTemplateRefs(
+  template: string,
+  bound: ReadonlySet<string> = new Set(),
+): Array<{ name: string; attr?: string }> {
+  const out: Array<{ name: string; attr?: string }> = [];
+  for (const match of template.matchAll(/\$\{([^}]*)\}/g)) {
+    const token = match[1].trim();
+    if (!token || token.startsWith("!") || token.includes("::") || bound.has(token)) continue;
+    const dot = token.indexOf(".");
+    out.push(dot > 0 ? { name: token.slice(0, dot), attr: token.slice(dot + 1) } : { name: token });
+  }
+  return out;
+}

package/src/graph-walk.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "vitest";
+import { adjacencyOf, walkBreadthFirst } from "./graph-walk";
+
+const edges = [
+  { from: "a", to: "b" },
+  { from: "b", to: "c" },
+  { from: "c", to: "a" },
+  { from: "c", to: "d" },
+];
+const idx = adjacencyOf(edges);
+const out = (id: string) => (idx.out.get(id) ?? []).map((e) => ({ far: e.to, hops: [e] }));
+
+describe("walkBreadthFirst", () => {
+  test("offers every node at its shortest depth first, and ends on a cycle", () => {
+    const first = new Map<string, number>();
+    const found = walkBreadthFirst("a", {
+      steps: out,
+      arrive: ({ id, depth }) => {
+        if (!first.has(id)) first.set(id, depth);
+        return false;
+      },
+    });
+    expect(found).toBeNull();
+    expect([...first]).toEqual([["b", 1], ["c", 2], ["a", 3], ["d", 3]]);
+  });
+
+  test("stops on the first accepted arrival and returns its hops", () => {
+    const found = walkBreadthFirst("a", { steps: out, arrive: ({ id }) => id === "d" });
+    expect(found?.depth).toBe(3);
+    expect(found?.hops.map((h) => `${h.from}->${h.to}`)).toEqual(["a->b", "b->c", "c->d"]);
+  });
+
+  test("min and max bound which arrivals are offered and how far it steps", () => {
+    const offered: string[] = [];
+    walkBreadthFirst("a", { steps: out, min: 2, max: 2, arrive: ({ id }) => (offered.push(id), false) });
+    expect(offered).toEqual(["c"]);
+  });
+
+  test("walks from several starts at once", () => {
+    const offered = new Set<string>();
+    walkBreadthFirst(["c", "b"], { steps: out, arrive: ({ id }) => (offered.add(id), false) });
+    expect([...offered].sort()).toEqual(["a", "b", "c", "d"]);
+  });
+});

package/src/graph-walk.ts

@@ -0,0 +1,102 @@
+/**
+ * The one breadth-first edge walk in core.
+ *
+ * `chant search`'s transitive edge terms (#4359) walk the graph IR, and carve's
+ * reachability (#2325) and reference-closed sets (#3909) walk a `TfGraph`. The
+ * two graphs have different node and edge shapes but the same walk: an index of
+ * each node's edges by direction, built once, and a frontier that steps along
+ * it. This module is that walk, generic over what a step carries, so neither
+ * caller keeps a traversal of its own.
+ *
+ * Pure: no IR or Terraform types, no filesystem.
+ */
+
+/** Edges grouped by the node they leave (`out`) and the node they enter (`in`). */
+export interface Adjacency<E> {
+  out: Map<string, E[]>;
+  in: Map<string, E[]>;
+}
+
+/**
+ * Index edges by both ends, once. Looking a node's edges up in here is O(1),
+ * where filtering the edge list for them is O(E) per node and O(V·E) per walk
+ * (#2325 measured 21 s against 52 ms at 6 000 nodes).
+ */
+export function adjacencyOf<E extends { from: string; to: string }>(edges: Iterable<E>): Adjacency<E> {
+  const idx: Adjacency<E> = { out: new Map(), in: new Map() };
+  for (const e of edges) {
+    let out = idx.out.get(e.from);
+    if (!out) idx.out.set(e.from, (out = []));
+    out.push(e);
+    let inn = idx.in.get(e.to);
+    if (!inn) idx.in.set(e.to, (inn = []));
+    inn.push(e);
+  }
+  return idx;
+}
+
+/** One step out of a node: where it lands, and the hops (edges) it took to get there. */
+export interface WalkStep<H> {
+  far: string;
+  hops: readonly H[];
+}
+
+/** A node reached by the walk: its id, how many steps from the start, and the hops on the way. */
+export interface WalkArrival<H> {
+  id: string;
+  depth: number;
+  hops: H[];
+}
+
+export interface WalkOptions<H> {
+  /** The steps out of a node. The walk follows exactly these; filter here. */
+  steps: (id: string) => readonly WalkStep<H>[];
+  /** Arrivals shallower than this are walked through but not offered. Default 1. */
+  min?: number;
+  /** No step is taken from a node this deep. Default unbounded. */
+  max?: number;
+  /**
+   * Called for each arrival at a depth of at least `min`, in breadth-first
+   * order, so a node's first arrival is at its shortest depth. A node can
+   * arrive more than once (by several edges, or again past `min` on a cycle);
+   * return true to stop the walk and return this arrival.
+   */
+  arrive?: (arrival: WalkArrival<H>) => boolean;
+}
+
+/**
+ * Walk breadth-first from one or more start nodes (#4359, #2325).
+ *
+ * Termination on a cycle: a state is (node, depth capped at `min`). 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, which matters for carve: chant never runs
+ * Terraform, so a `depends_on` cycle in a malformed estate reaches it
+ * unvalidated.
+ *
+ * Returns the arrival `arrive` stopped on, or null when the walk ran out.
+ */
+export function walkBreadthFirst<H>(start: string | Iterable<string>, opts: WalkOptions<H>): WalkArrival<H> | null {
+  const min = opts.min ?? 1;
+  const max = opts.max ?? Infinity;
+  const starts = typeof start === "string" ? [start] : [...start];
+  const seen = new Set<string>(starts.map((id) => `${id}|0`));
+  let frontier: WalkArrival<H>[] = starts.map((id) => ({ id, depth: 0, hops: [] }));
+  while (frontier.length > 0) {
+    const next: WalkArrival<H>[] = [];
+    for (const s of frontier) {
+      if (s.depth >= max) continue;
+      for (const step of opts.steps(s.id)) {
+        const depth = s.depth + 1;
+        const arrival: WalkArrival<H> = { id: step.far, depth, hops: step.hops.length ? [...s.hops, ...step.hops] : s.hops };
+        if (depth >= min && opts.arrive?.(arrival)) return arrival;
+        const key = `${step.far}|${Math.min(depth, min)}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        next.push(arrival);
+      }
+    }
+    frontier = next;
+  }
+  return null;
+}

package/src/import/parser.ts

@@ -57,6 +57,24 @@ export interface OutputIR {
   readonly condition?: string;
 }
 
+/**
+ * A finding a parser reports about the translation it made (#4398): a
+ * judgment call the author must confirm, or something it could not carry.
+ * `chant import --report <path>` writes these as SARIF and `--strict` fails
+ * while any `warning` or `error` is open, as `chant migrate` does.
+ */
+export interface ImportDiagnostic {
+  readonly ruleId: string;
+  readonly severity: "error" | "warning" | "info";
+  readonly message: string;
+  /** 1-based line in the template, when the parser knows it. */
+  readonly line?: number;
+  /** 1-based column in the template. */
+  readonly column?: number;
+  /** The object the finding is about, as the source names it. */
+  readonly entity?: string;
+}
+
 /**
  * Intermediate representation of a parsed template
  */
@@ -71,6 +89,8 @@ export interface TemplateIR {
   /** Sections or keys the parser read but import cannot carry, named so the
    * import surfaces them instead of dropping them silently (#2069). */
   readonly warnings?: string[];
+  /** Findings for `--report` and `--strict` (#4398); a parser that has none leaves it out. */
+  readonly diagnostics?: ImportDiagnostic[];
 }
 
 /**

package/src/lexicon.ts

@@ -1,9 +1,10 @@
+import type { CapabilityPack } from "./capabilities/view";
 import type { Serializer } from "./serializer";
 import type { Declarable } from "./declarable";
 import type { LintRule } from "./lint/rule";
 import type { RuleSpec } from "./lint/declarative";
-import type { PostSynthCheck } from "./lint/post-synth";
-import type { TemplateParser, TemplateIR, ParseContext, ParserOptions, ParserOptionSpec } from "./import/parser";
+import type { CrossRootCheck, PostSynthCheck } from "./lint/post-synth";
+import type { TemplateParser, TemplateIR, ParseContext, ParserOptions, ParserOptionSpec, ImportDiagnostic } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
 import type { EmbeddedContentImporter } from "./import/embedded";
 import type { AgentConfigImporter } from "./agents/importer";
@@ -23,7 +24,7 @@ import type { OwnershipChannel, OwnershipMarker } from "./ownership";
 import type { LexiconConfigSchema } from "./lexicon-config";
 import type { RuleMeta } from "./audit/catalog";
 import type { ReferenceCatalog } from "./graph-refs";
-import type { IREdge, LexiconGraphEdges, LexiconUnreadSource, LexiconWorkspaceOutputs } from "./graph-ir";
+import type { IREdge, LexiconGraphEdges, LexiconUnreadSource, LexiconWorkspaceLinks, LexiconWorkspaceOutputs } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
@@ -381,8 +382,11 @@ export function intrinsicCallFoldsEagerly(def: { isTag?: boolean; foldsEagerly?:
  * Options passed to a MigrationSource by `chant migrate`.
  */
 export interface MigrateOptions {
-  /** Output format. */
-  emit?: "yaml" | "ts";
+  /**
+   * Output format. `yaml` and `ts` are the gitlab pair's; `sql` writes plain
+   * DDL for a pair whose target is a database (#4399).
+   */
+  emit?: "yaml" | "ts" | "sql";
   /** Recognise composite patterns when emitting. */
   useComposites?: boolean;
   /** Source file path (for provenance display only). */
@@ -410,6 +414,20 @@ export interface MigrationResult {
   diagnostics: Array<Record<string, unknown>>;
   /** Markdown "Security posture" section, when security analysis ran (#306). */
   securityPosture?: string;
+  /**
+   * Outputs of the source member that the rendered output reads, by the names
+   * a workspace link takes (#4399). In a workspace, `chant migrate` writes
+   * them as `links` of the member the output lands in, so a source that drops
+   * or renames one fails `chant workspace check`.
+   */
+  links?: string[];
+  /**
+   * The checks that need the target's own server, run for `--validate`
+   * instead of the external linter (#4399). Returns the diagnostics found,
+   * `error` severity for a refusal. Throws when the server cannot start, which
+   * `chant migrate` reports as a validation that did not run.
+   */
+  validate?(): Promise<Array<Record<string, unknown>>>;
 }
 
 /**
@@ -419,6 +437,12 @@ export interface MigrationResult {
 export interface MigrationSource {
   /** Lightweight detector: does this content look like the expected source? */
   detect(content: string): boolean;
+  /**
+   * The source may be a directory, which `transform` reads itself from
+   * `opts.sourceFile` (a workspace member, #4399). `chant migrate` then skips
+   * `detect` and passes empty content.
+   */
+  directory?: boolean;
   /** Run the translation. */
   transform(content: string, opts: MigrateOptions): Promise<MigrationResult>;
 }
@@ -869,6 +893,19 @@ export interface ScheduledOpSpec {
    * per-job environment mapping to put a value in.
    */
   variables?: Record<string, string>;
+  /**
+   * The Op runs a `reviewAgent` step in `handoff` mode (#4326): generate the
+   * review as two jobs. The first runs `chant run <name>` with no forge write
+   * token (the checkout's fetches get the job's token and nothing after
+   * them does) and hands the review on as job outputs. The second checks
+   * nothing out, takes the review as data and posts it as one note with the
+   * write token (`postReviewNote`). GitHub and Forgejo only: a GitLab merge
+   * request pipeline hands every job the project's unprotected variables, so
+   * the gitlab generator refuses this by name. The trigger must be
+   * `pull_request` and the finding-mode `report`, since the first job posts
+   * nothing.
+   */
+  reviewAgent?: boolean;
 }
 
 /**
@@ -1190,6 +1227,14 @@ export interface LexiconPlugin {
   /** Return post-synthesis checks for build validation */
   postSynthChecks?(): PostSynthCheck[];
 
+  /**
+   * Checks that read across build roots (chant #1939). Only a cross-root run
+   * (`runCrossRootChecks`, ./lint/post-synth.ts) calls this; `chant build`
+   * and `chant lint` never do, so a lexicon that adds one costs a
+   * single-build project nothing.
+   */
+  crossRootChecks?(): CrossRootCheck[];
+
   /**
    * Activity contracts (`ActivityContract`, `./op/activity-contract.ts`) for
    * the activities this lexicon implements, so another lexicon's post-synth
@@ -1304,6 +1349,15 @@ export interface LexiconPlugin {
    */
   parserOptions?(): ParserOptionSpec[];
 
+  /**
+   * `chant import --validate` (#4398): check what the import would write
+   * against the lexicon's own emulator, and return one diagnostic per
+   * failure (severity `error`). Called with the parsed IR and the checked
+   * parser options. A lexicon without an emulator leaves this out, and
+   * `--validate` then fails the import with a message saying so.
+   */
+  validateImport?(ir: TemplateIR, options: ParserOptions): Promise<ImportDiagnostic[]>;
+
   /** Return a generator for converting IR to TypeScript */
   templateGenerator?(): TypeScriptGenerator;
 
@@ -1498,6 +1552,17 @@ export interface LexiconPlugin {
    */
   workspaceOutputs?(entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]): LexiconWorkspaceOutputs | undefined;
 
+  /**
+   * The outputs of other workspace members this lexicon's declarations read
+   * or write (#4397), such as the ClickHouse tables an otel `clickhouse`
+   * exporter writes. `chant workspace check` calls it offline on the member's
+   * folded source, as it calls `workspaceOutputs`, and checks each link like
+   * one a kind's reader found (WSP093 to WSP095, WSP099 for `gaps`), naming
+   * the file and line of the declaring entity. Pure: no I/O. Return
+   * `undefined` when the project declares nothing that links.
+   */
+  workspaceLinks?(entities: ReadonlyMap<string, Declarable>, unread?: readonly LexiconUnreadSource[]): LexiconWorkspaceLinks | undefined;
+
   // LSP
   /** Provide completions for LSP */
   completionProvider?(ctx: CompletionContext): CompletionItem[];
@@ -1543,10 +1608,14 @@ export interface LexiconPlugin {
    * Return a migration source for translating from another lexicon's
    * format into this lexicon. Returns undefined if `from` is not supported.
    *
+   * `to` is the target as `--to` names it. A side may add a dialect after the
+   * lexicon, `sql/clickhouse` (#4399); `from` is passed as written, and a
+   * lexicon with one target ignores `to`.
+   *
    * Example: the gitlab lexicon implements `migrationSource("github")` to
    * translate `.github/workflows/*.yml` into `.gitlab-ci.yml`.
    */
-  migrationSource?(from: string): MigrationSource | undefined;
+  migrationSource?(from: string, to?: string): MigrationSource | undefined;
 
   // State
   /**
@@ -2082,6 +2151,15 @@ export interface LexiconPlugin {
    */
   referenceCatalog?: ReferenceCatalog;
 
+  /**
+   * This lexicon's capability pack (#4375): its mapping onto the
+   * lexicon-neutral view the capability rules read (labels, edge names,
+   * attributes, policy documents, inline blocks, link resources), as data,
+   * plus an adapter for what the mapping can't say as data. `chant search`'s
+   * `cap:` terms and `--capabilities` read it. Opt-in.
+   */
+  capabilityPack?: CapabilityPack;
+
   /**
    * Enrich live IR node attributes for edge reconstruction (#784). Returns
    * `nodeId → attributes` with cross-resource references resolved to the

package/src/lifecycle/gate-ledger.ts

@@ -181,6 +181,14 @@ export interface GateResolutionRecord {
    * other resolution.
    */
   empty?: true;
+  /**
+   * The workspace gate that stood in for this member gate (#2554, ws-039):
+   * its name and the digest of the member plans it covers. Set only on the
+   * resolution a run builds when a workspace approval passes the gate; it is
+   * never written to the member's ledger, where the approval stays the
+   * workspace's (`_members/_workspace/_gates/`).
+   */
+  workspaceGate?: { gate: string; digest: string };
   /**
    * The channel this resolution was authored on (chant#2384) — set by the
    * writer, never by the caller. `chant approve` records `"cli"`, the

package/src/lifecycle/git.ts

@@ -148,7 +148,7 @@ export async function writeBlobToPath(
   filename: string,
   content: string,
   commitMessage: string,
-  opts?: { cwd?: string; expectPriorPathSha?: string | null },
+  opts?: LedgerLocation & { expectPriorPathSha?: string | null },
 ): Promise<string> {
   const dir = await ledgerDir(environment, opts);
   return writeLedgerFiles(
@@ -447,7 +447,7 @@ export async function readBlobFromPath(
 export async function readPathSha(
   environment: string,
   filename: string,
-  opts?: { cwd?: string },
+  opts?: LedgerLocation,
 ): Promise<string | null> {
   const rt = getRuntime();
   const dir = await ledgerDir(environment, opts);