@intentius/chant 0.102.0 → 0.104.0

package/src/gated-waves-bundle.test.ts

@@ -0,0 +1,62 @@
+/**
+ * The gated-wave primitives bundle small (#3049, ruling #3421).
+ *
+ * terragucci runs a wave per CI job from one bundled file with no TypeScript
+ * toolchain. It calls wave planning, the set digest and the gate names from
+ * `@intentius/chant/gated-waves`, and decides a wave's gate with
+ * `evaluateGate` from `@intentius/chant/op/gate` against the
+ * `chant/lifecycle` ledger. This bundles both the way terragucci would and
+ * reads esbuild's own list of what went in.
+ */
+
+import { join } from "node:path";
+import { build } from "esbuild";
+import { describe, expect, test } from "vitest";
+import { REPO } from "./workspace/__fixtures__/contract-repo";
+
+const HEAVY = [/node_modules\/typescript\//, /node_modules\/esbuild\//, /\/src\/fold\//, /\/src\/lint\//, /\/src\/codegen\//];
+
+async function inputsOf(entry: string): Promise<{ inputs: string[]; bytes: number }> {
+  const result = await build({
+    entryPoints: [join(REPO, "packages", "core", "src", entry)],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    write: false,
+    metafile: true,
+    outdir: "out",
+    logLevel: "silent",
+  });
+  return {
+    inputs: Object.keys(result.metafile.inputs),
+    bytes: result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0),
+  };
+}
+
+describe("the gated-wave bundle", () => {
+  test("wave planning, the set digest and the records hold the change-set digest code and nothing heavier", async () => {
+    const { inputs, bytes } = await inputsOf("gated-waves.ts");
+    for (const pattern of [...HEAVY, /node_modules\/zod\//]) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?packages\//, "packages/")).sort()).toEqual([
+      "packages/core/src/change-set.ts",
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/gated-waves.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+    ]);
+    expect(bytes).toBeLessThan(24 * 1024);
+  });
+
+  test("the gate decision reaches no TypeScript, esbuild, fold, lint or codegen module", async () => {
+    // It does reach zod, through the workspace identity rules a gate reads
+    // (#3163). That is weight, not a toolchain, and #3421 forbids the toolchain.
+    const { inputs } = await inputsOf("op/gate.ts");
+    for (const pattern of HEAVY) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+  });
+});

package/src/gated-waves.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Gated waves (#3049): the parts with no runner. Wave layering with a canary
+ * list, the set digest, gate names and the attempt record's wave entries.
+ */
+
+import { describe, expect, test } from "vitest";
+import {
+  ProvisionalWaveMemberError,
+  UnknownCanaryError,
+  WaveCycleError,
+  describeChangedWave,
+  layerWaves,
+  readWaveRecords,
+  waveGateName,
+  waveSetDigest,
+  withWaveRecord,
+  type WaveRecord,
+} from "./gated-waves";
+import { changeSetDigest } from "./change-set";
+
+/** net → a, b → app-a (on a), app-b (on b). */
+const ROOTS = [
+  { name: "net" },
+  { name: "a", dependsOn: ["net"] },
+  { name: "b", dependsOn: ["net"] },
+  { name: "app-a", dependsOn: ["a"] },
+  { name: "app-b", dependsOn: ["b"] },
+];
+
+describe("layerWaves", () => {
+  test("dependency order, each wave sorted", () => {
+    expect(layerWaves(ROOTS)).toEqual([["net"], ["a", "b"], ["app-a", "app-b"]]);
+  });
+
+  test("a canary list is wave 1 whatever the graph order, and the rest follow the graph", () => {
+    expect(layerWaves(ROOTS, { canary: ["app-b"] })).toEqual([["app-b"], ["net"], ["a", "b"], ["app-a"]]);
+    expect(layerWaves(ROOTS, { canary: ["b", "net"] })).toEqual([["b", "net"], ["a", "app-b"], ["app-a"]]);
+  });
+
+  test("a dependency outside the set does not hold a node back", () => {
+    expect(layerWaves([{ name: "a", dependsOn: ["net"] }, { name: "app-a", dependsOn: ["a"] }])).toEqual([["a"], ["app-a"]]);
+  });
+
+  test("a canary that is not in the set is refused, unless it is known and just not changing", () => {
+    expect(() => layerWaves(ROOTS, { canary: ["nope"] })).toThrow(UnknownCanaryError);
+    expect(layerWaves(ROOTS.slice(0, 2), { canary: ["app-b"], known: ["app-b"] })).toEqual([["net"], ["a"]]);
+  });
+
+  test("a cycle is refused by name", () => {
+    expect(() => layerWaves([{ name: "x", dependsOn: ["y"] }, { name: "y", dependsOn: ["x"] }])).toThrow(WaveCycleError);
+  });
+});
+
+describe("the set digest", () => {
+  const members = [
+    { member: "net", planDigest: "jcs1-sha256:" + "1".repeat(64) },
+    { member: "a", planDigest: "jcs1-sha256:" + "2".repeat(64) },
+  ];
+
+  test("is the change-set digest of the wave's members", () => {
+    expect(waveSetDigest(members)).toBe(changeSetDigest(members));
+    expect(waveSetDigest(members)).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
+  });
+
+  test("does not depend on order and moves when one root's plan does", () => {
+    expect(waveSetDigest([...members].reverse())).toBe(waveSetDigest(members));
+    expect(waveSetDigest([members[0], { member: "a", planDigest: "jcs1-sha256:" + "3".repeat(64) }])).not.toBe(
+      waveSetDigest(members),
+    );
+  });
+
+  test("refuses a wave that names one root twice", () => {
+    expect(() => waveSetDigest([members[0], members[0]])).toThrow(/twice/);
+  });
+
+  test("refuses a wave holding a provisional plan, by name", () => {
+    expect(() => waveSetDigest([members[0], { ...members[1], provisional: true }])).toThrow(ProvisionalWaveMemberError);
+    expect(() => waveSetDigest([members[0], { ...members[1], provisional: true }])).toThrow(/provisional plan: a planned/);
+  });
+});
+
+describe("wave records", () => {
+  const record: WaveRecord = {
+    wave: 2,
+    op: "fan-out",
+    gate: waveGateName("release", 2),
+    components: ["a", "b"],
+    digest: "jcs1-sha256:" + "4".repeat(64),
+    members: [{ member: "a", planDigest: "jcs1-sha256:" + "5".repeat(64) }],
+    status: "gated",
+    approved: "jcs1-sha256:" + "6".repeat(64),
+  };
+
+  test("each wave has its own gate", () => {
+    expect(waveGateName("release", 1)).toBe("release-wave-1");
+    expect(waveGateName("release", 1)).not.toBe(waveGateName("release", 2));
+  });
+
+  test("round-trip through JSON, dropping malformed entries", () => {
+    const read = readWaveRecords(JSON.parse(JSON.stringify([record, { wave: "x" }, null])));
+    expect(read).toEqual([record]);
+    expect(readWaveRecords(undefined)).toEqual([]);
+  });
+
+  test("a later record for the same wave replaces the earlier one", () => {
+    const applied: WaveRecord = { ...record, status: "applied", approvedBy: "ana" };
+    delete applied.approved;
+    expect(withWaveRecord([record], applied)).toEqual([applied]);
+  });
+
+  test("the changed-set refusal names both digests and says nothing applied", () => {
+    const line = describeChangedWave(record);
+    expect(line).toContain(record.approved);
+    expect(line).toContain(record.digest);
+    expect(line).toContain("nothing in it was applied");
+    expect(line).toContain("chant approve fan-out release-wave-2 --plan");
+  });
+});

package/src/gated-waves.ts

@@ -0,0 +1,240 @@
+/**
+ * Gated waves (#3049): one change rolled out across many roots, a wave at a
+ * time, each wave behind its own gate bound to that wave's set digest.
+ *
+ * `chant components fan-out --wave-gate` is the runner. This module holds the
+ * parts that need no runner: how a set of roots is cut into waves, what a
+ * wave's digest is, what its gate is called, and what the attempt record says
+ * about each wave. They are kept apart from the runner because terragucci
+ * calls them from its CI stages as one bundled file with no TypeScript
+ * toolchain (#3421). Everything here imports `./change-set` and nothing else,
+ * and `gated-waves-bundle.test.ts` holds that.
+ *
+ * ## The set digest
+ *
+ * A wave's digest is {@link changeSetDigest} over its members' `{ member,
+ * planDigest }` pairs, the function #3181's change-set document uses. A
+ * terraform-family member is named after its root, so this is the issue's
+ * `jcs1-sha256` over sorted `{ root, planDigest }`, and a wave's digest equals
+ * the change-set digest of the wave's members. Each member's plan digest is
+ * the one a gate on that root alone binds (`terraformPlanDigest`, #2300), so a
+ * one-root wave and a one-root `TerraformApplyOp` approve the same value.
+ *
+ * ## Why a wave is planned when it is reached
+ *
+ * A later wave planned up front reads outputs that do not exist yet. Planned
+ * after the wave before it applied, its digest describes the real upstream
+ * values, which is what an approver of that wave is shown.
+ */
+
+import { changeSetDigest } from "./change-set";
+
+/** A root, or a component, as wave planning sees it: a name and what it reads. */
+export interface WaveNode {
+  name: string;
+  /** Names this node reads from. A name outside the node set is already satisfied. */
+  dependsOn?: readonly string[];
+}
+
+/** Thrown when a canary names something that is not in the set being planned. */
+export class UnknownCanaryError extends Error {
+  constructor(
+    readonly canary: string,
+    known: readonly string[],
+  ) {
+    super(`canary names "${canary}", which is not in this set (known: ${known.join(", ") || "none"})`);
+    this.name = "UnknownCanaryError";
+  }
+}
+
+/** Thrown when the nodes being layered depend on each other in a cycle. */
+export class WaveCycleError extends Error {
+  constructor(readonly members: string[]) {
+    super(`dependency cycle among: ${members.join(", ")}`);
+    this.name = "WaveCycleError";
+  }
+}
+
+export interface LayerWavesOptions {
+  /**
+   * Nodes that form wave 1 whatever the graph says (#3049). Only those in the
+   * set are placed; one outside it has nothing to apply. The rest follow in
+   * dependency order, and a dependency on a canary counts as satisfied by
+   * wave 1.
+   */
+  canary?: readonly string[];
+  /**
+   * Names known to exist outside `nodes`. A canary naming one of them is
+   * left out quietly, since it is real but not part of this change; any
+   * other unknown canary is refused. Defaults to `nodes` alone.
+   */
+  known?: readonly string[];
+}
+
+/**
+ * Cut `nodes` into ordered waves: each node lands after every node it reads
+ * from, and each wave is sorted by name so the same graph always produces the
+ * same waves. With a canary list, those nodes are wave 1.
+ *
+ * A dependency on a name outside `nodes` does not hold a node back. That is
+ * the subset case: the dependency already applied, or is not changing.
+ */
+export function layerWaves(nodes: readonly WaveNode[], options: LayerWavesOptions = {}): string[][] {
+  const names = new Set(nodes.map((n) => n.name));
+  const known = new Set([...names, ...(options.known ?? [])]);
+  for (const canary of options.canary ?? []) {
+    if (!known.has(canary)) throw new UnknownCanaryError(canary, [...known].sort());
+  }
+  const canaries = [...new Set((options.canary ?? []).filter((c) => names.has(c)))].sort();
+
+  const waves: string[][] = canaries.length > 0 ? [canaries] : [];
+  const remaining = new Set([...names].filter((n) => !canaries.includes(n)));
+  const deps = new Map(nodes.map((n) => [n.name, (n.dependsOn ?? []).filter((d) => remaining.has(d))]));
+  while (remaining.size > 0) {
+    const wave = [...remaining].filter((n) => deps.get(n)!.every((d) => !remaining.has(d))).sort();
+    if (wave.length === 0) throw new WaveCycleError([...remaining].sort());
+    for (const n of wave) remaining.delete(n);
+    waves.push(wave);
+  }
+  return waves;
+}
+
+/** One member of a wave: a root (or a component with no plannable step) and its plan digest. */
+export interface WaveMember {
+  member: string;
+  planDigest: string;
+  /** A provisional plan (`ChangeSetMember.provisional`, #3416). A wave refuses it. */
+  provisional?: true;
+}
+
+/** Thrown when a wave's members include a provisional plan, which no gate may bind. */
+export class ProvisionalWaveMemberError extends Error {
+  constructor(readonly members: string[]) {
+    super(
+      `a wave cannot be gated on a provisional plan: ${members.join(", ")} planned before what it reads applied. ` +
+        `Plan it again in its own wave, after its upstream applied`,
+    );
+    this.name = "ProvisionalWaveMemberError";
+  }
+}
+
+/**
+ * A wave's set digest: {@link changeSetDigest} over its members. Order does
+ * not matter, and it moves whenever one member's plan digest does. A wave
+ * naming one member twice has no digest and is refused, and so is a wave
+ * holding a provisional plan (#3416): a gate bound to it would approve
+ * values nobody has yet.
+ */
+export function waveSetDigest(members: readonly WaveMember[]): string {
+  const provisional = members.filter((m) => m.provisional === true).map((m) => m.member);
+  if (provisional.length > 0) throw new ProvisionalWaveMemberError([...new Set(provisional)].sort());
+  return changeSetDigest(members);
+}
+
+/**
+ * The gate a wave waits on: `<gate>-wave-<n>`, under the fan-out's op.
+ *
+ * One gate name per wave keeps each wave's approvals apart. With one name
+ * shared by every wave, wave 2 would find wave 1's approval and report it as
+ * an approval of another plan, which is true and useless. Wave numbers come
+ * from the derivation, not from what is left to run, so wave 3 stays wave 3
+ * on a resumed attempt and its approval still applies.
+ */
+export function waveGateName(gate: string, wave: number): string {
+  return `${gate}-wave-${wave}`;
+}
+
+/** Where a wave got to. */
+export type WaveStatus =
+  /** Planned, and its gate is not approved for this digest. Nothing in it ran. */
+  | "gated"
+  /** Every member applied. */
+  | "applied"
+  /** At least one member failed to plan or to apply. Its dependents are blocked. */
+  | "failed";
+
+/**
+ * One wave, as an attempt record and a run result carry it. The plan report
+ * (#3349) reads these and points at the gate record rather than copying it:
+ * `op` and `gate` name the ledger entry (`_gates/<op>.jsonl` on
+ * `chant/lifecycle`).
+ */
+export interface WaveRecord {
+  /** 1-based, from the derivation. */
+  wave: number;
+  op: string;
+  /** The full gate name, {@link waveGateName}. */
+  gate: string;
+  /** What was planned in this wave on this attempt. */
+  components: string[];
+  /** The set digest the gate was decided against. */
+  digest: string;
+  members: WaveMember[];
+  status: WaveStatus;
+  /** Who approved this digest, once the gate passed. */
+  approvedBy?: string;
+  /** When the gate refused because an approval stands for another digest: that digest. */
+  approved?: string;
+  /** Components that failed to plan or to apply, with why. */
+  failed?: Array<{ component: string; error?: string }>;
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+const strings = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((v): v is string => typeof v === "string") : [];
+
+/**
+ * Read the `waves` array of an attempt record, dropping anything malformed.
+ * A record written before #3049 has none, which reads as no waves.
+ */
+export function readWaveRecords(value: unknown): WaveRecord[] {
+  if (!Array.isArray(value)) return [];
+  const out: WaveRecord[] = [];
+  for (const raw of value) {
+    if (!isObject(raw)) continue;
+    const { wave, op, gate, digest, status } = raw;
+    if (typeof wave !== "number" || typeof op !== "string" || typeof gate !== "string" || typeof digest !== "string") continue;
+    if (status !== "gated" && status !== "applied" && status !== "failed") continue;
+    const members = Array.isArray(raw.members)
+      ? raw.members.filter(
+          (m): m is WaveMember => isObject(m) && typeof m.member === "string" && typeof m.planDigest === "string",
+        )
+      : [];
+    const failed = Array.isArray(raw.failed)
+      ? raw.failed
+          .filter((f): f is { component: string; error?: unknown } => isObject(f) && typeof f.component === "string")
+          .map((f) => ({ component: f.component, ...(typeof f.error === "string" ? { error: f.error } : {}) }))
+      : [];
+    out.push({
+      wave,
+      op,
+      gate,
+      components: strings(raw.components),
+      digest,
+      members: members.map((m) => ({ member: m.member, planDigest: m.planDigest })),
+      status,
+      ...(typeof raw.approvedBy === "string" ? { approvedBy: raw.approvedBy } : {}),
+      ...(typeof raw.approved === "string" ? { approved: raw.approved } : {}),
+      ...(failed.length > 0 ? { failed } : {}),
+    });
+  }
+  return out;
+}
+
+/** Put `record` in `records` in place of any earlier record for the same wave, sorted by wave. */
+export function withWaveRecord(records: readonly WaveRecord[], record: WaveRecord): WaveRecord[] {
+  return [...records.filter((r) => r.wave !== record.wave), record].sort((a, b) => a.wave - b.wave);
+}
+
+/**
+ * The refusal for a wave whose set changed after it was approved: the digest
+ * that was approved, the one planned now, and that nothing in the wave ran.
+ */
+export function describeChangedWave(record: Pick<WaveRecord, "wave" | "op" | "gate" | "digest" | "approved">): string {
+  return (
+    `wave ${record.wave} changed after it was approved, so nothing in it was applied. ` +
+    `approved: ${record.approved ?? "(none)"}; planned now: ${record.digest}. ` +
+    `Read the new plan, then approve it: chant approve ${record.op} ${record.gate} --plan ${record.digest}`
+  );
+}

package/src/index.ts

@@ -149,6 +149,7 @@ export * from "./resource-attributes";
 export * from "./stack-output";
 export * from "./child-project";
 export * from "./lsp/types";
+export type { SymbolDeclaration, SymbolResolver } from "./workspace/symbols";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
 export * from "./lifecycle/index";

package/src/lexicon.ts

@@ -8,6 +8,8 @@ import type { TypeScriptGenerator } from "./import/generator";
 import type { EmbeddedContentImporter } from "./import/embedded";
 import type { AgentConfigImporter } from "./agents/importer";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
+import type { GatedWavePipelineOptions } from "./components/gated-wave-pipeline";
+import type { PrLoopPipelineOptions } from "./components/pr-pipeline";
 import type { OkfFile } from "./okf";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
 import type { McpToolContribution, McpResourceContribution } from "./mcp/types";
@@ -26,6 +28,7 @@ import type { DescribeIdentityOptions, DescribeIdentityResult } from "./identity
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
 import type { BehaviourResult, PredictBehaviourOptions } from "./behaviour";
 import type { BehaviourKinds } from "./behaviour-kinds";
+import type { SymbolResolver } from "./workspace/symbols";
 import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
@@ -536,6 +539,20 @@ export interface ComponentPipelineOptions {
    * `["chant", "components", "promote", "--from", <env>, "--to", <promoteTo>]`.
    */
   promoteCommand?: string[];
+  /**
+   * Gated waves (#3049): one job per wave instead of one per component. Job
+   * `wave-<k>` runs `chant components fan-out --wave-gate <gate> --wave <k>`
+   * and hands the attempt record to the next job. See
+   * `components/gated-wave-pipeline.ts`. Unset, the pipeline is unchanged.
+   */
+  gatedWaves?: GatedWavePipelineOptions;
+  /**
+   * The pull-request loop (#3183): a plan job on each pull request and an
+   * apply job on each push to the target branch, bound to the digest a
+   * reviewer approved, instead of one job per component. See
+   * `components/pr-pipeline.ts`. Unset, the pipeline is unchanged.
+   */
+  prLoop?: PrLoopPipelineOptions;
   /**
    * The workspace member this pipeline belongs to (#2542, #2524 D19). Core
    * sets it when the project sits in a member of a `chant.workspace.json`;
@@ -890,6 +907,16 @@ export interface StackStatusObservation {
 /**
  * Context for a lexicon's {@link LexiconPlugin.buildRoots} hook (#1548).
  */
+/** What {@link LexiconPlugin.changedUnits} reads (#3183). */
+export interface ChangedUnitsContext {
+  /** The directory `chant.config.*` lives in. Config paths resolve against it. */
+  projectRoot: string;
+  /** The resolved project configuration, for the lexicon's own namespace. */
+  config: Record<string, unknown>;
+  /** Files the change added, modified or deleted, relative to `projectRoot`, with `/` separators. */
+  changedFiles: string[];
+}
+
 export interface BuildRootContext {
   /**
    * The directory the project configuration was loaded from (where
@@ -1311,6 +1338,18 @@ export interface LexiconPlugin {
    */
   buildRoots?(ctx: BuildRootContext): Promise<BuildRootContribution>;
 
+  /**
+   * The units this lexicon owns that a change touched, judged from the
+   * changed files alone (#3183). A unit is a name a component's deploy step
+   * targets (`deploy-units.ts`): the terraform lexicon answers with the
+   * `terraform.roots` entries whose directory, local modules or var files a
+   * changed file sits in. `chant components fan-out --base` and `chant
+   * components pr-plan` add these to the stacks `lifecycle affected` finds,
+   * since a root that is not chant source never shows in an artifact diff.
+   * Omit for lexicons whose units are chant source.
+   */
+  changedUnits?(ctx: ChangedUnitsContext): Promise<string[]>;
+
   /**
    * Facts about the whole read that this lexicon's entities imply, for the
    * graph IR's `meta` bag (#2559). The otel lexicon answers
@@ -1337,6 +1376,18 @@ export interface LexiconPlugin {
   /** Provide code actions for LSP */
   codeActionProvider?(ctx: CodeActionContext): CodeAction[];
 
+  /**
+   * Symbol resolvers for the languages this lexicon's members are written in
+   * (#3313), so `chant workspace graph --intent <path>#<symbol>` names a
+   * declaration in such a file: a table in a `.sql` file, a resource in a
+   * manifest. Each is `{ language, extensions, declarations(path, text) }`,
+   * returning every declaration's dotted name, kind and 1-based line range.
+   * The intent walk asks the lexicons a file's member configures, after
+   * core's TypeScript and JavaScript resolver, which keeps `.ts` and `.js`.
+   * Pure: no I/O, no network. Omit for a lexicon with no such language.
+   */
+  symbolResolvers?(): SymbolResolver[];
+
   // Docs
   /** Generate documentation pages */
   docs?(options?: { verbose?: boolean }): Promise<void>;

package/src/lifecycle/gate-ledger.ts

@@ -117,6 +117,13 @@ export interface GateResolutionRecord {
   gate: string;
   /** Who resolved it — an actor name, the same convention `components release --actor` and `run approve --approver` use. */
   resolvedBy: string;
+  /**
+   * Who carried this approval to chant for `resolvedBy` (#3402): `chant
+   * approve --relayed-by`, such as a follower program relaying a person's
+   * approval. The approver is still `resolvedBy`; a seal covers this field
+   * too. Absent when the approver recorded it themselves.
+   */
+  relayedBy?: string;
   /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
   timestamp: string;
   /** Optional free-text context. Before #2028 this was also where a PR link went by convention; put the link in {@link GateResolutionRecord.url} instead and leave this for prose. */