@intentius/chant 0.58.0 → 0.60.0

package/src/config.ts

@@ -481,10 +481,10 @@ export async function loadChantConfig(dir: string): Promise<ResolvedConfig> {
  * lives at the project root, one or more levels up. Before this, callers
  * either read `startDir` alone or bolted on a single `dirname()` fallback —
  * fine for a one-level-deep stack, silently blind to anything deeper
- * (loomster's `src/<stack>` layout is exactly one level too deep: `buildParams`'
- * declared `env:` mappings never resolved, so `LOOM_TIER`/`LOOM_ENV` were inert
- * under every `npm run synth:*` for two releases — loomster#162). Uses the
- * same walk `chant lint`/`chant graph` already used ({@link findProjectConfig},
+ * (a `src/<stack>` layout is exactly one level too deep: `buildParams`' declared
+ * `env:` mappings never resolved, so the env vars they named were inert under
+ * every `npm run synth:*` for two releases). Uses the same walk `chant
+ * lint`/`chant graph` already used ({@link findProjectConfig},
  * shared with `./lint/config.ts`'s `findProjectRoot`) — one config-discovery
  * contract for the whole CLI.
  *

package/src/detectLexicon.ts

@@ -1,5 +1,22 @@
 import { readFile } from "node:fs/promises";
 
+/**
+ * The message {@link detectLexicons} throws when a scan of the project's
+ * source files turns up no `@intentius/chant-lexicon-*` import at all.
+ *
+ * Named (chant #2222) because one caller has to tell this failure apart from
+ * every other one: `chant lint` reports a lexicon it cannot resolve as an
+ * error diagnostic, but "this directory declares no lexicon and imports none"
+ * is not that. It is a project that lints under the core rules alone, and it
+ * has always been allowed to. See {@link isNoLexiconDetected}.
+ */
+export const NO_LEXICON_DETECTED_MESSAGE = "No lexicon detected in infrastructure files";
+
+/** Whether `error` is the {@link NO_LEXICON_DETECTED_MESSAGE} failure. */
+export function isNoLexiconDetected(error: unknown): boolean {
+  return error instanceof Error && error.message === NO_LEXICON_DETECTED_MESSAGE;
+}
+
 /**
  * Detects which lexicons are being used by analyzing import statements
  * in the provided infrastructure files. Matches any `@intentius/chant-lexicon-*` package.
@@ -32,7 +49,7 @@ export async function detectLexicons(files: string[]): Promise<string[]> {
 
   // Validate results
   if (detectedLexicons.size === 0) {
-    throw new Error("No lexicon detected in infrastructure files");
+    throw new Error(NO_LEXICON_DETECTED_MESSAGE);
   }
 
   return Array.from(detectedLexicons);

package/src/discovery/fold-import.test.ts

@@ -1009,7 +1009,7 @@ describe("tryFoldFile — build-time parameters (chant #1064)", () => {
     expect((entity as unknown as { props: { name: unknown } }).props.name).toBe("staging");
   });
 
-  test("a nullish-coalesced default still folds to a literal (loomster's `params.x ?? \"default\"` pattern)", async () => {
+  test("a nullish-coalesced default still folds to a literal (the `params.x ?? \"default\"` pattern)", async () => {
     const file = join(testDir, "main.ts");
     await writeFile(
       file,
@@ -1276,7 +1276,7 @@ describe("tryFoldFile — registered authoring helpers (#1082)", () => {
               stack: "web",
               inputs: { pVpcId: { stackOutput: { stack: "shared-foundation", name: "oVpcId" } } },
             },
-            { kind: "gate", signalName: "approve", timeout: "24h" },
+            { kind: "gate", gate: "approve", timeout: "24h" },
           ],
         },
       ],

package/src/discovery/fold-import.ts

@@ -1697,9 +1697,9 @@ async function resolveCallArguments(
 //  4. **Its body is a single expression, or a block of `const` declarations
 //     followed by one `return`** — and nothing else. No `if`, no `throw`, no
 //     loop, no `let`/`var`, no nested function declaration, no bare expression
-//     statement. This is the line loomster's `composites/*.ts` fall outside
-//     (module-level `buildXxx()` helpers with `if`/`throw` and `.map()`), and
-//     they are meant to: they keep invoking, exactly as before.
+//     statement. This is the line a project's hand-rolled composite modules
+//     fall outside (module-level `buildXxx()` helpers with `if`/`throw` and
+//     `.map()`), and they are meant to: they keep invoking, exactly as before.
 //  5. **Every expression in it is inside the fold subset, extended with the
 //     two things a factory body exists to do**: `new Type(...)` in ANY value
 //     position (a member, a nested property object, an array element), and a

package/src/fold/foldable-helpers.ts

@@ -123,7 +123,7 @@ export const FOLDABLE_AUTHORING_HELPERS: readonly FoldableHelperDef[] = [
   {
     name: "gate",
     module: "components/component.ts, op/builders.ts",
-    note: "Returns a plain `{ kind: 'gate', signalName, ... }` object literal built from its arguments.",
+    note: "Returns a plain `{ kind: 'gate', gate, ... }` object literal built from its arguments.",
   },
   {
     name: "activity",

package/src/graph-ops.test.ts

@@ -54,7 +54,7 @@ describe("mergeProjectOps (#1675)", () => {
     expect(node?.attrs.name).toBe("deploy");
     expect(node?.attrs.depends).toEqual(["inner"]);
     expect(node?.attrs.phases).toEqual([
-      { name: "Apply", steps: [{ kind: "activity", fn: "build" }, { kind: "gate", signalName: "approve" }] },
+      { name: "Apply", steps: [{ kind: "activity", fn: "build" }, { kind: "gate", gate: "approve" }] },
     ]);
     // The sourceDir op discovery already loaded is untouched, not duplicated.
     expect(ir.nodes.filter((n) => n.kind === "Chant::Op")).toHaveLength(2);

package/src/lexicon.ts

@@ -492,9 +492,15 @@ export interface ComponentPipelineResult {
  * into the Op's own activity args at build time and is never re-passed on the
  * generated CI invocation; here it decides only what token/permission wiring
  * the generated job needs to act on a finding — elevated write access for
- * `issue`/`pull-request`/`merge-request`, none for `report`.
+ * `issue`/`comment`/`pull-request`/`merge-request`, none for `report`.
+ *
+ * `comment` posts the finding on the pull request — or, on GitLab, the merge
+ * request (#2256) — that triggered the run, so unlike every other mode it
+ * constrains the trigger: the github and gitlab generators both refuse it by
+ * name on anything but `pull_request`. The forgejo generator refuses it
+ * outright, having no forge client to post the equivalent comment with.
  */
-export type OpFindingMode = "report" | "issue" | "pull-request" | "merge-request";
+export type OpFindingMode = "report" | "issue" | "comment" | "pull-request" | "merge-request";
 
 /**
  * The CI-native trigger driving a scheduled Op's generated workflow. `cron`
@@ -509,6 +515,77 @@ export type OpTrigger =
   | { kind: "pull_request"; branches?: string[] }
   | { kind: "push"; branches?: string[] };
 
+/**
+ * One step a generated Op job runs between the checkout and the
+ * `beforeScript` lines (#2242). Two shapes, matching what a GitHub Actions
+ * step can be: a marketplace action (`uses`, with its `with:` inputs and
+ * `env:`), or a shell line (`run`). The `uses` shape is the reason this
+ * exists at all: `beforeScript` covers everything a shell line can install,
+ * but an action like `aws-actions/configure-aws-credentials` is not a shell
+ * line, and OIDC has no shell equivalent.
+ *
+ * A CI provider with no action concept degrades by name rather than
+ * silently: the gitlab generator refuses a `uses` entry at build time and
+ * emits a `run` entry as an ordinary script line. The additive `permissions`
+ * map degrades the same way there, with one exception: `id-token: write`
+ * becomes GitLab's own `id_tokens:` declaration (#2256).
+ */
+export type OpSetupStep = OpSetupUsesStep | OpSetupRunStep;
+
+/** A marketplace-action setup step (`uses:` with its inputs). */
+export interface OpSetupUsesStep {
+  /**
+   * `owner/repo[/subpath]@ref`. The ref is required and must not be the
+   * action repository's own default branch — see the github generator's
+   * `assertSetupSteps`, which refuses both at build time.
+   */
+  uses: string;
+  /** The action's inputs, emitted as the step's `with:` mapping. */
+  with?: Record<string, string | number | boolean>;
+  /** Environment for this step alone, emitted as the step's `env:` mapping. */
+  env?: Record<string, string>;
+}
+
+/** A shell setup step, the same shape a `beforeScript` line emits as. */
+export interface OpSetupRunStep {
+  /** The shell line, emitted as the step's `run:`. */
+  run: string;
+  /** Environment for this step alone, emitted as the step's `env:` mapping. */
+  env?: Record<string, string>;
+}
+
+/**
+ * The deployment environment a generated Op job runs in (#2257) — a forge
+ * object rather than a chant one. On GitHub Actions an environment carries
+ * its own protection rules (required reviewers, a wait timer, a branch
+ * restriction) and its own secrets and variables, so naming one on a job is
+ * how a generated apply is put behind a human before the job starts. GitLab
+ * has the same key with the same two fields and its own protected-environment
+ * approvals behind it. Forgejo Actions has no environments at all, so its
+ * dialect drops the key and says so in the generated file's header.
+ *
+ * This is not a chant gate and does not replace one. The environment reviewer
+ * stops the job before any step runs; chant's own gate (#2119) stops the apply
+ * inside a run that already started, on a fact recorded on the
+ * `chant/lifecycle` branch, and is cleared by `chant approve`. A project may
+ * have either, both, or neither per environment.
+ */
+export interface OpEnvironment {
+  /**
+   * The environment's name, exactly as the forge spells it. Nothing creates
+   * it: an environment is repository configuration, and a job naming one that
+   * does not exist yet gets an unprotected environment created on first run
+   * rather than an error, which is precisely why the name is not guessed here.
+   */
+  name: string;
+  /**
+   * The URL shown against the resulting deployment. Absolute, or an
+   * expression the forge resolves (`${{ ... }}`) — a relative path renders as
+   * a dead link on the deployments page rather than failing anywhere.
+   */
+  url?: string;
+}
+
 /** One scheduled Op to generate CI for — the cron-triggered counterpart to a component (generate mode). */
 export interface ScheduledOpSpec {
   /** Op name (`*.op.ts`'s `Op({ name })`) — what `chant run <name>` targets. */
@@ -535,6 +612,32 @@ export interface ScheduledOpSpec {
   opSchedule?: OpSchedule;
   /** This Op's finding-mode, for permission/token wiring only (see {@link OpFindingMode}). Default: "report" — no elevated permissions. */
   findingMode?: OpFindingMode;
+  /**
+   * Steps this Op's generated job runs between the checkout and the
+   * `beforeScript` lines (#2242), in the order given. Per-Op rather than a
+   * `ComponentPipelineOptions` knob because the setup an Op needs is a
+   * property of that Op: a plan job assumes a read-only role, an apply job
+   * assumes the one that can write.
+   */
+  setup?: OpSetupStep[];
+  /**
+   * Scopes added to the ones this Op's finding-mode already grants (#2242).
+   * Strictly additive: the generator refuses a scope the mode's own set
+   * already names, at any value, so this can neither downgrade nor restate
+   * least privilege, and it refuses `write-all`/`read-all` outright. The
+   * motivating value is `{ "id-token": "write" }`, which no finding-mode
+   * grants and OIDC cannot work without.
+   */
+  permissions?: Record<string, "read" | "write">;
+  /**
+   * The forge deployment environment this Op's generated job runs in
+   * (#2257). Per Op, beside `setup` and `permissions`, and for the same
+   * reason: which environment a job deploys to is a property of that job — a
+   * pull-request plan touches none, and only the push apply belongs behind
+   * the reviewer. See {@link OpEnvironment} for how it composes with chant's
+   * own gate.
+   */
+  environment?: OpEnvironment;
 }
 
 /**
@@ -663,6 +766,29 @@ export type BuildRootContributor = (
   ctx: Pick<BuildRootContext, "entities">,
 ) => Promise<BuildRootContribution>;
 
+/**
+ * Where the content handed to `auditEntities` came from (#2217).
+ *
+ * The hook's first argument is the text audit discovery classified for a
+ * lexicon. For most lexicons that is the whole unit of parsing. For terraform
+ * it is not: a root module's `module` blocks name sibling directories, and a
+ * rule about what a CHILD module may contain cannot be answered from one
+ * directory's text. So the discovery facts a lexicon may need to read further
+ * travel with the content.
+ *
+ * `dir` and `baseDir` are set only when discovery walked a local filesystem.
+ * A remote tree fetch leaves both undefined, and a lexicon that finds them
+ * undefined parses the content it was given and nothing else.
+ */
+export interface AuditEntitiesInput {
+  /** The input's path as discovery recorded it, relative to the audited root. `"."` for the root itself. */
+  path: string;
+  /** Absolute path of the directory this input's files were read from. */
+  dir?: string;
+  /** Absolute path of the audited root: the boundary a lexicon may read within. */
+  baseDir?: string;
+}
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -791,8 +917,17 @@ export interface LexiconPlugin {
    * return a `Promise` for a lexicon whose parser is inherently async (e.g.
    * terraform's HCL parser, a lazy-loaded wasm module). `auditLexicon` awaits
    * it before reading `ctx.entities`.
+   *
+   * `input` says where the content came from (#2217). It is optional so a
+   * caller can still parse a bare string, and a lexicon that only needs the
+   * text ignores it. A lexicon whose unit of parsing is a directory rather
+   * than a file (terraform: a root module and the local modules it calls)
+   * reads `dir` to descend, and stays inside `baseDir` while doing it.
    */
-  auditEntities?(content: string): Map<string, Declarable> | Promise<Map<string, Declarable>>;
+  auditEntities?(
+    content: string,
+    input?: AuditEntitiesInput,
+  ): Map<string, Declarable> | Promise<Map<string, Declarable>>;
 
   /**
    * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
@@ -1146,6 +1281,39 @@ export interface LexiconPlugin {
     region?: string;
   }): Promise<Record<string, ResourceMetadata>>;
 
+  /**
+   * Subscribe to this substrate's own change notifications (#1981), so an
+   * operator tick can run when something moved instead of only when the timer
+   * came round. Optional, and consumed by exactly one caller: `chant
+   * operator`'s loop (`./op/operator.ts`). A lexicon that does not implement
+   * it behaves exactly as it did: the loop keeps its timer and never asks.
+   *
+   * Three rules make the seam honest, and the types are shaped to enforce the
+   * first one rather than describe it.
+   *
+   * - **The signal is a trigger, never a fact.** {@link
+   *   SubscribeChangesOptions.onChange} takes no arguments and returns
+   *   nothing, so there is no channel through which a watch event could reach
+   *   a change set, a snapshot row or a diff line. The tick that follows an
+   *   early wake re-observes and re-derives from scratch, exactly as a
+   *   timer-driven tick does; waking early changes *when* a tick runs and
+   *   nothing about what it concludes.
+   * - **A dropped subscription degrades to the timer and says so.** Report it
+   *   through {@link SubscribeChangesOptions.onError} and stop; the operator
+   *   logs one line and re-subscribes on its next round. Losing the stream
+   *   slows detection back to the interval. It must never stop the loop, and
+   *   must never read as a clean estate.
+   * - **The timer stays.** A signal shortens the sleep, it does not replace
+   *   it, so a substrate that silently stops sending still converges on the
+   *   interval.
+   *
+   * Only implement it where the substrate has a change stream that needs
+   * nothing deployed into the account being observed. See the per-lexicon
+   * verdict table in the operator guide for where that holds and where it does
+   * not.
+   */
+  subscribeChanges?(options: SubscribeChangesOptions): Promise<ChangeSubscription>;
+
   /**
    * Read the full live *property tree* for each declared entity (#1014). Opt-in,
    * and strictly deeper than {@link describeResources}, which reports existence
@@ -1568,6 +1736,56 @@ export interface DependencyObservation {
   edges?: IREdge[];
 }
 
+/**
+ * What {@link LexiconPlugin.subscribeChanges} is handed (#1981).
+ *
+ * `onChange` is the whole payload channel, and it has no payload. That is the
+ * point: a substrate's change notification is a reason to look again, never
+ * evidence of what is there. An implementation that wanted to pass the watch
+ * event through would have nowhere to put it.
+ */
+export interface SubscribeChangesOptions {
+  /** chant environment being watched. Resolves the same binding a read does. */
+  environment: string;
+  /** Directory whose `chant.config.ts` carries the binding. Defaults to cwd. */
+  cwd?: string;
+  /**
+   * Declared entities for this lexicon, keyed by chant entity name. The same
+   * map {@link LexiconPlugin.describeResources} receives, and the bound on
+   * what a subscription may watch. An implementation scopes its streams to the
+   * kinds and namespaces these entities name; it must never subscribe to the
+   * whole substrate. Absent, or empty, means there is nothing in scope to
+   * watch and the implementation should say so through {@link onError} rather
+   * than widening.
+   */
+  entities?: Map<string, { entityType: string; props: Record<string, unknown> }>;
+  /**
+   * Something moved. No arguments, deliberately (see {@link
+   * LexiconPlugin.subscribeChanges}). The caller re-observes from scratch and
+   * nothing about the notification reaches what it reports.
+   */
+  onChange(): void;
+  /**
+   * The subscription died, or could not be established for part of its scope.
+   * Reported once per occurrence; the caller logs it and falls back to its
+   * timer. Never a throw once the subscription is live: a stream that ends is
+   * a degradation, not a crash.
+   */
+  onError?(message: string): void;
+  /** Aborts the subscription. Closing on abort is the implementation's job. */
+  signal: AbortSignal;
+}
+
+/**
+ * A live subscription handed back by {@link LexiconPlugin.subscribeChanges}
+ * (#1981). `close()` releases every stream the subscription holds and resolves
+ * once they are gone; it must be safe to call twice, and safe to call after
+ * the subscription has already died on its own.
+ */
+export interface ChangeSubscription {
+  close(): Promise<void>;
+}
+
 export interface ResourceMetadata {
   /** Entity type (e.g. AWS::S3::Bucket, K8s::Apps::Deployment) */
   type: string;

package/src/lifecycle/gate-ledger.ts

@@ -142,7 +142,7 @@ export interface PendingGateRecord {
   kind: "pending";
   /** The op (or, on the component driver, the component) the gate belongs to. */
   op: string;
-  /** The gate's signal name (matches `GateStep.signalName`). */
+  /** The gate's name (matches `GateStep.gate`). */
   gate: string;
   /** The gate's human-readable description, when it declared one — what `chant operator status` shows a reader who wasn't there for the run. */
   description?: string;
@@ -173,6 +173,17 @@ function filename(op: string): string {
   return `${op}.jsonl`;
 }
 
+/**
+ * Where an Op's gate ledger lives, as a path a human can go and read:
+ * `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch. Exported so a
+ * renderer that tells someone a gate is pending can name the file the pending
+ * fact was appended to (#2243) rather than describing it in prose that drifts
+ * from `DIR`.
+ */
+export function gateLedgerPath(op: string): string {
+  return `${DIR}/${filename(op)}`;
+}
+
 /** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
 export async function appendGateResolution(
   input: GateResolutionInput,

package/src/lifecycle/observe.test.ts

@@ -204,8 +204,8 @@ describe("observeResources", () => {
         const stack = (opts as { stack?: string }).stack;
         calls.push(stack);
         // Different resources per stack — the multi-stack, per-component case
-        // (#57 loomster). Bare-string stacks keep BARE ids (no `src` scope), so
-        // the union is `db-a`+`db-b`, not stack-qualified: per-component ids are
+        // (#57). Bare-string stacks keep BARE ids (no `src` scope), so the
+        // union is `db-a`+`db-b`, not stack-qualified: per-component ids are
         // already unique and behold reads them bare. Qualification is a scoped
         // (`src`) feature — see the per-stack src test below.
         const resources: Record<string, ResourceMetadata> =

package/src/lifecycle/observe.ts

@@ -71,10 +71,10 @@ function qualifyObservation(obs: NormalizedObservation, stackName: string): Norm
  * (`read-failed`, #1089) rather than dropped, so a failed read is visibly a
  * hole instead of a silent absence.
  *
- * `stacks` (#57) is for a multi-stack, per-component project (e.g. loomster)
- * where there is no single stack named after the environment — AWS's
- * single-stack convention (`lexicons/aws/src/plugin.ts`'s `describeResources`,
- * absent an explicit `stack`) queries a stack that simply doesn't exist there,
+ * `stacks` (#57) is for a multi-stack, per-component project, where there is no
+ * single stack named after the environment — AWS's single-stack convention
+ * (`lexicons/aws/src/plugin.ts`'s `describeResources`, absent an explicit
+ * `stack`) queries a stack that simply doesn't exist there,
  * so the single-call path always observes zero nodes. When `stacks` is
  * present and non-empty, each observing plugin's `describeResources` is
  * called once per stack and the returned observations are merged. A stack entry
@@ -197,10 +197,10 @@ export async function observeResources(
           // Qualify ids by stack ONLY for a scoped (`src`) stack (#1162): that
           // is the multi-region case where the SAME bare LogicalResourceId
           // (e.g. `vpc`) exists in every stack, so a bare union would collide.
-          // A bare-string stack (#57 loomster) has unique per-component ids and
-          // is asked the whole-project entity set, so it keeps the bare-id
-          // tri-state merge (present > not-observed > absent) that behold and
-          // other consumers read.
+          // A bare-string stack (#57) has unique per-component ids and is asked
+          // the whole-project entity set, so it keeps the bare-id tri-state
+          // merge (present > not-observed > absent) that behold and other
+          // consumers read.
           parts.push(stack.src ? qualifyObservation(norm, stack.name) : norm);
         }
         observed = mergeObservations(parts);

package/src/lifecycle/release-ledger.test.ts

@@ -256,10 +256,10 @@ describe("release-ledger", () => {
     test("a Forgejo instance resolves through the same env contract to its own host", () => {
       const env = {
         GITHUB_RUN_ID: "42",
-        GITHUB_REPOSITORY: "intentius/loomster",
+        GITHUB_REPOSITORY: "acme/widgets",
         GITHUB_SERVER_URL: "https://forge.example.dev",
       };
-      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/intentius/loomster/actions/runs/42");
+      expect(resolveRunId(undefined, env).runOrigin!.url).toBe("https://forge.example.dev/acme/widgets/actions/runs/42");
     });
 
     test("GitLab CI env records the project path and takes CI_PIPELINE_URL verbatim", () => {

package/src/lint/pipeline-change-gate.test.ts

@@ -44,7 +44,7 @@ describe("classifyComponentPipelineChange (#1569)", () => {
 
   test("gate steps are never mistaken for an escape hatch", () => {
     const withGate = component([
-      { phase: "Approve", steps: [{ kind: "gate", signalName: "release-approved" }] },
+      { phase: "Approve", steps: [{ kind: "gate", gate: "release-approved" }] },
     ]);
     expect(classifyComponentPipelineChange(withGate, { knownKinds: KNOWN })).toEqual({
       pipelineChange: false,
@@ -78,7 +78,7 @@ describe("componentVerbSet (#1569)", () => {
     const c = component([
       {
         phase: "Deploy",
-        steps: [{ kind: "cfn-deploy" }, { kind: "gate", signalName: "go" }, { kind: "wait-for-stack" }],
+        steps: [{ kind: "cfn-deploy" }, { kind: "gate", gate: "go" }, { kind: "wait-for-stack" }],
       },
     ]);
     expect(componentVerbSet(c)).toEqual(new Set(["cfn-deploy", "wait-for-stack"]));

package/src/lint/rules/comp/comp.test.ts

@@ -267,6 +267,32 @@ describe("COMP004: gate-needs-durable-runtime", () => {
     const hits = diagnostics.filter((d) => d.checkId === "COMP004" && d.component === "neo4j-cluster");
     expect(hits).toHaveLength(1);
   });
+
+  // #2202: the message names the gate whichever key carries the name, so the
+  // "chant approve <component> <gate>" line it prints stays copy-pasteable.
+  it("names a gate still using the deprecated `signalName` key", () => {
+    const [comp004] = checks.filter((c) => c.id === "COMP004");
+    const ctx = {
+      rollbackPolicies: FIXTURE_ROLLBACK_POLICIES,
+      components: new Map([
+        [
+          "svc",
+          {
+            component: {
+              name: "svc",
+              dependsOn: [],
+              deploy: [{ phase: "Approve", steps: [{ kind: "gate", signalName: "release-approval" }] }],
+            },
+            filePath: "svc.component.ts",
+          },
+        ],
+      ]),
+    };
+    const diagnostics = comp004.check(ctx as never);
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].message).toContain('gate "release-approval"');
+    expect(diagnostics[0].message).toContain("chant approve svc release-approval");
+  });
 });
 
 describe("COMP005: capability-kind-is-noun", () => {

package/src/lint/rules/comp/comp004-gate-needs-durable-runtime.ts

@@ -41,6 +41,7 @@
  */
 
 import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic } from "../../component-checks";
+import { gateName } from "../../../op/gate-name";
 import { walkComponent } from "./support";
 
 export const comp004GateNeedsDurableRuntimeRule: ComponentCheck = {
@@ -54,15 +55,16 @@ export const comp004GateNeedsDurableRuntimeRule: ComponentCheck = {
     for (const [name, { component, filePath }] of ctx.components) {
       const { gates } = walkComponent(component);
       for (const { gate, phaseName } of gates) {
+        const label = gateName(gate);
         diagnostics.push({
           checkId: "COMP004",
           severity: "error",
           component: name,
           file: filePath,
           message:
-            `Component "${name}": gate "${gate.signalName}" (phase "${phaseName}") ends the run pending approval — ` +
+            `Component "${name}": gate "${label}" (phase "${phaseName}") ends the run pending approval — ` +
             `a run that reaches it records the gate as a fact and stops there until someone runs ` +
-            `"chant approve ${name} ${gate.signalName}", and no later phase runs. If that wait is intended, ` +
+            `"chant approve ${name} ${label}", and no later phase runs. If that wait is intended, ` +
             `suppress with a file-level "// chant-disable COMP004 -- <reason>" comment anywhere in this file to ` +
             `document who approves it and why.`,
         });

package/src/lint/rules/op/ops014-converge-rule-refusals.test.ts

@@ -72,7 +72,7 @@ function destructiveOpEntity(name: string, opts?: { gated?: boolean }) {
   ];
   const phases = opts?.gated
     ? [
-        { name: "Approve", steps: [{ kind: "gate", signalName: "approve-x" }] },
+        { name: "Approve", steps: [{ kind: "gate", gate: "approve-x" }] },
         { name: "Apply", steps },
       ]
     : [{ name: "Apply", steps }];

package/src/op/activities/index.ts

@@ -43,8 +43,15 @@ export type { EnvTeardownArgs, EnvTeardownResult, EnvTeardownDeps } from "./env-
 // the registry imports this module statically, so a project that installs
 // nothing but chant still resolves every step below.
 
-export { reconcilePr } from "./reconcile";
-export type { ReconcilePrArgs, ReconcileResult, ReconcileMode, ReconcileEntry } from "./reconcile";
+export {
+  reconcilePr,
+  commentMarker,
+  pullRequestContextFrom,
+  resolvePullRequestContext,
+  mergeRequestContextFrom,
+  gitlabNoteTokenFrom,
+} from "./reconcile";
+export type { ReconcilePrArgs, ReconcileResult, ReconcileMode, ReconcileEntry, PullRequestContext } from "./reconcile";
 
 export { nativeApply, compensateApply, hasNativeRollback } from "./apply";
 export type {