@intentius/chant 0.59.0 → 0.60.0

package/src/cli/commands/lint.test.ts

@@ -5,6 +5,7 @@ import { mkdir, rm, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
+import { params, setBuildParams } from "../../params";
 
 describe("lintCommand", () => {
   let testDir: string;
@@ -118,6 +119,69 @@ export default {
     ).toBe(true);
   });
 
+  // #2251 — `chant lint` imports every `*.op.ts` file to read the Op it
+  // declares, and an Op that takes a step argument from `params.<name>`
+  // (`@intentius/chant/params`) evaluates that read at module load. Before
+  // this, nothing populated the shared parameters object first, so every such
+  // argument was `undefined` and OPS012 reported the activity contract
+  // violated on source that builds and runs. The fixture imports the real
+  // params module by absolute path — `@intentius/chant/params` maps to the
+  // same file (packages/core/package.json's `exports`), so it is the one
+  // module record `lintCommand` mutates.
+  describe("build parameters reach an Op's step arguments (#2251)", () => {
+    const paramsModule = resolve(import.meta.dirname, "../../params.ts");
+
+    async function writeParamReadingOp(): Promise<void> {
+      await writeFile(
+        join(testDir, "mini.op.ts"),
+        `
+import { params } from ${JSON.stringify(paramsModule)};
+
+export default {
+  [Symbol.for("chant.declarable")]: true,
+  entityType: "Chant::Op",
+  lexicon: "chant",
+  kind: "resource",
+  props: {
+    name: "mini",
+    overview: "test",
+    phases: [
+      { name: "Greet", steps: [
+        { kind: "activity", fn: "shellCmd", args: { cmd: params.greeting } },
+      ] },
+    ],
+  },
+};
+        `,
+      );
+    }
+
+    test("OPS012 does not fire when the invocation's parameters are supplied", async () => {
+      await writeParamReadingOp();
+
+      const result = await lintCommand({
+        path: testDir,
+        format: "stylish",
+        buildParams: [{ name: "greeting", value: "echo hi", source: "default" }],
+      });
+
+      expect(result.diagnostics.filter((d) => d.ruleId === "OPS012")).toEqual([]);
+      expect(result.success).toBe(true);
+    });
+
+    test("OPS012 fires on the same source when no parameters are supplied", async () => {
+      await writeParamReadingOp();
+
+      const result = await lintCommand({ path: testDir, format: "stylish" });
+
+      expect(
+        result.diagnostics.some(
+          (d) => d.ruleId === "OPS012" && d.message.includes("args.cmd"),
+        ),
+      ).toBe(true);
+    });
+  });
+
   test("formats output as JSON", async () => {
     await writeFile(
       join(testDir, "nested.ts"),
@@ -686,3 +750,90 @@ describe("lintCommand — a declared lexicon that cannot be resolved (#2222)", (
     expect(result.diagnostics.some((d) => d.ruleId === LEXICON_RESOLUTION_RULE_ID)).toBe(false);
   });
 });
+
+/**
+ * chant #2249 — `lintCommand` resolves the project's own declared
+ * `buildParams` when its caller supplied none, so an in-process lint agrees
+ * with `chant lint` on the command line.
+ *
+ * #2251 taught the CLI handler (../handlers/lint.ts) to resolve
+ * `--param`/`--params-file`/declared defaults and pass them down, because
+ * the OPS* checks import every `*.op.ts` file and an Op reading
+ * `params.<name>` evaluates that read at module load. Every other caller of
+ * `lintCommand` has no flags to read and passed nothing, so `params` stayed
+ * empty and OPS012 reported the activity contract violated for source that
+ * lints clean from a shell. That is how the root-examples gate
+ * (examples/root-examples-gate.test.ts) went red on github-pr-preview while
+ * `chant lint .` in the same directory exited 0, and it applied equally to
+ * `handleLint` over MCP and to test-utils' example harness.
+ *
+ * These drive the real `lintCommand` against a temp project holding one
+ * `*.op.ts` file (enough for the OPS* pass to run its parameter binding) and
+ * read the shared `params` object the binding populates.
+ */
+describe("lintCommand build-time parameters (#2249)", () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `chant-lint-params-${Date.now()}-${Math.random()}`);
+    await mkdir(testDir, { recursive: true });
+    // The OPS* pass binds parameters only when there is an Op file to import.
+    // A plain default export is enough: it is skipped as not-an-Op after the
+    // binding has already happened.
+    await writeFile(join(testDir, "noop.op.ts"), `export default { props: {} };\n`);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+    delete process.env.CHANT_TEST_ENV_2249;
+    setBuildParams({});
+  });
+
+  test("a declared default reaches params with no caller-supplied provenance", async () => {
+    await writeFile(
+      join(testDir, "chant.config.json"),
+      JSON.stringify({ buildParams: { env: { type: "string", default: "local" } } }),
+    );
+
+    await lintCommand({ path: testDir, format: "stylish" });
+
+    expect(params.env).toBe("local");
+  });
+
+  test("a declared env mapping reaches params the same way chant lint resolves it", async () => {
+    await writeFile(
+      join(testDir, "chant.config.json"),
+      JSON.stringify({
+        buildParams: { env: { type: "string", default: "local", env: "CHANT_TEST_ENV_2249" } },
+      }),
+    );
+    process.env.CHANT_TEST_ENV_2249 = "pr-42";
+
+    await lintCommand({ path: testDir, format: "stylish" });
+
+    expect(params.env).toBe("pr-42");
+  });
+
+  test("caller-supplied parameters win over the declared defaults", async () => {
+    await writeFile(
+      join(testDir, "chant.config.json"),
+      JSON.stringify({ buildParams: { env: { type: "string", default: "local" } } }),
+    );
+
+    await lintCommand({
+      path: testDir,
+      format: "stylish",
+      buildParams: [{ name: "env", value: "pr-42", source: "cli" }],
+    });
+
+    expect(params.env).toBe("pr-42");
+  });
+
+  test("a project declaring none binds an empty parameter set", async () => {
+    await writeFile(join(testDir, "chant.config.json"), JSON.stringify({}));
+
+    await lintCommand({ path: testDir, format: "stylish" });
+
+    expect(params).toEqual({});
+  });
+});

package/src/cli/commands/lint.ts

@@ -20,6 +20,8 @@ import { rule } from "../../lint/declarative";
 import { watchDirectory, formatTimestamp, formatChangedFiles } from "../watch";
 import { formatError, formatInfo } from "../format";
 import { GENERATED_MARKER } from "../../discovery/files";
+import { buildParamValues, resolveBuildParams } from "../../build-params";
+import { setBuildParams } from "../../params";
 import { isNoLexiconDetected } from "../../detectLexicon";
 
 // Import config loader
@@ -535,11 +537,21 @@ async function runComponentCheckDiagnostics(
 async function runOpCheckDiagnostics(
   infraPath: string,
   files: string[],
+  buildParams?: BuildParamProvenance[],
 ): Promise<{ diagnostics: LintDiagnostic[]; suppressed: Array<LintDiagnostic & { reason?: string }> }> {
   const config = loadConfig(findProjectRoot(infraPath));
   const opFiles = files.filter((f) => f.endsWith(".op.ts"));
   if (opFiles.length === 0) return { diagnostics: [], suppressed: [] };
 
+  // chant #2251 — the same step `discover()` runs before it imports or folds a
+  // project file (../../discovery/index.ts): populate the shared build-time
+  // parameters object BEFORE the imports below, so an Op that takes a step
+  // argument from `params.<name>` reads the value this invocation resolved
+  // rather than `undefined`. Unconditional, so a stale value from a prior
+  // lint in the same process (a test, `--watch`) never leaks into one that
+  // resolved none.
+  setBuildParams(buildParamValues(buildParams ?? []));
+
   const entities = new Map<string, unknown>();
   const fileByOpName = new Map<string, string>();
   for (const filePath of opFiles) {
@@ -640,10 +652,31 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // than a failure — `loadOkfBundle` already treats a missing directory as
   // an empty bundle.
   let knowledgeBundle: OkfBundle | undefined;
+  /**
+   * chant #2249 — this invocation's build-time parameters, falling back to
+   * the project's own declared `buildParams` when the caller passed none.
+   *
+   * `chant lint` resolves them in ./handlers/lint.ts (#2251) because only
+   * the CLI knows about `--param`/`--params-file`, and passes them here. An
+   * in-process caller has no such flags to read, and before this fell
+   * through to the empty parameter object: the OPS* checks import each
+   * `*.op.ts`, an Op taking a step argument from `params.<name>` read
+   * `undefined` at module load, and OPS012 reported the activity contract
+   * violated for source `chant lint` on the command line passes. That made
+   * `lintCommand` disagree with its own CLI (the root-examples gate,
+   * `handleLint` over MCP, test-utils' example harness). Resolving the
+   * declared defaults + `env` mappings here is what the command line
+   * already gets; anything a flag would override still arrives in
+   * `options.buildParams` and wins. Best-effort like `projectConfig`:
+   * `resolveBuildParams` collects failures per parameter without throwing,
+   * and the ones that did resolve are still better than none.
+   */
+  let buildParams = options.buildParams;
   try {
     const chantConfig = (await loadChantConfig(projectRoot)).config;
     projectConfig = chantConfig as LintProjectConfig;
     knowledgeBundle = await loadOkfBundle(resolveKnowledgeDir(chantConfig, projectRoot));
+    buildParams ??= resolveBuildParams(chantConfig.buildParams, { env: process.env }).provenance;
   } catch {
     projectConfig = undefined;
     knowledgeBundle = undefined;
@@ -696,14 +729,14 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
   // structurally distinct check family (whole-project, post-discovery,
   // see ../../lint/component-checks.ts) but the same `chant lint` output and
   // the same error-severity gating as every COR/EVL diagnostic.
-  const componentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, options.buildParams);
+  const componentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, buildParams);
   diagnostics.push(...componentResult.diagnostics);
   suppressed.push(...componentResult.suppressed);
 
   // Run the OPS* Op-model post-synth checks (#2122) over every `*.op.ts`
   // file under the lint target — see runOpCheckDiagnostics's doc for why
   // this needs no lexicon or build to fire.
-  const opResult = await runOpCheckDiagnostics(infraPath, files);
+  const opResult = await runOpCheckDiagnostics(infraPath, files, buildParams);
   diagnostics.push(...opResult.diagnostics);
   suppressed.push(...opResult.suppressed);
 
@@ -751,13 +784,13 @@ export async function lintCommand(options: LintOptions): Promise<LintResult> {
     // `*.component.ts` file on their behalf), but a fix applied to another
     // rule could still be in the same file a component was discovered from —
     // re-run for consistency with the AST re-lint above.
-    const postComponentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, options.buildParams);
+    const postComponentResult = await runComponentCheckDiagnostics(infraPath, options.sandbox, buildParams);
     diagnostics.push(...postComponentResult.diagnostics);
     suppressed.push(...postComponentResult.suppressed);
 
     // OPS* checks have no `.fix` either; re-run for the same consistency
     // reason as the COMP* re-run just above.
-    const postOpResult = await runOpCheckDiagnostics(infraPath, files);
+    const postOpResult = await runOpCheckDiagnostics(infraPath, files, buildParams);
     diagnostics.push(...postOpResult.diagnostics);
     suppressed.push(...postOpResult.suppressed);
   }

package/src/cli/handlers/graph.test.ts

@@ -710,10 +710,10 @@ describe("runGraph", () => {
       });
     });
 
-    // The bug this branch fixes (#57): a multi-stack, per-component project
-    // (loomster/Floci) has no stack literally named after the environment, so
-    // the live graph must resolve each component's own `cfn-deploy` stack(s)
-    // and pass them through to `observeResources` for the per-stack union.
+    // The bug this branch fixes (#57): a multi-stack, per-component project has
+    // no stack literally named after the environment, so the live graph must
+    // resolve each component's own `cfn-deploy` stack(s) and pass them through
+    // to `observeResources` for the per-stack union.
     test("multi-stack component project: resolves each component's cfn-deploy stack(s) and passes them to observeResources", async () => {
       resolveLexMock.mockResolvedValue(["aws"]);
       loadPluginsMock.mockResolvedValue([

package/src/cli/handlers/graph.ts

@@ -253,17 +253,17 @@ async function runGraphLive(
     return 1;
   }
 
-  // Multi-stack, per-component projects (loomster/Floci, #57): AWS's
-  // single-stack convention (`describeResources` defaults to a stack named
-  // after the environment, lexicons/aws/src/plugin.ts) never matches a
-  // per-component layout (e.g. `loom-local-a-<component>`), so the plain
-  // single call always observes zero nodes. Resolve every discovered
-  // component's `cfn-deploy` stack(s) — the same walk `chant components
-  // status --live` uses (`cfnDeployStacks`, ./components.ts) — and hand them
-  // to `observeResources`, which queries `describeResources` once per stack
-  // and unions the results. A project with no components (or whose discovery
-  // errors) yields no stacks, so `observeResources` falls back to its
-  // original single-stack call — unchanged.
+  // Multi-stack, per-component projects (#57): AWS's single-stack convention
+  // (`describeResources` defaults to a stack named after the environment,
+  // lexicons/aws/src/plugin.ts) never matches a per-component layout (e.g.
+  // `loom-local-a-<component>`), so the plain single call always observes zero
+  // nodes. Resolve every discovered component's `cfn-deploy` stack(s) — the
+  // same walk `chant components status --live` uses (`cfnDeployStacks`,
+  // ./components.ts) — and hand them to `observeResources`, which queries
+  // `describeResources` once per stack and unions the results. A project with
+  // no components (or whose discovery errors) yields no stacks, so
+  // `observeResources` falls back to its original single-stack call —
+  // unchanged.
   const componentsDiscovery = await discoverComponents(resolve(args.src ?? config.sourceDir ?? "."), {
     sandbox: args.sandbox,
   });

package/src/cli/handlers/lint.test.ts

@@ -0,0 +1,107 @@
+/**
+ * chant #2251 — `chant lint` resolves this invocation's declared build-time
+ * parameters before it lints.
+ *
+ * The gap this covers: `runLint` built its `LintOptions` without ever
+ * touching `chant.config.ts`'s `buildParams`, so the OPS* checks imported
+ * every `*.op.ts` file with `params` (`@intentius/chant/params`) still empty.
+ * An Op taking a step argument from `params.<name>` therefore read
+ * `undefined` and OPS012 reported the activity contract violated on source
+ * that builds and runs — reproducible on any project with an Op that reads a
+ * build parameter, `--param` and the declared `env` mapping alike (the
+ * resolution never ran at all, so no input could reach it).
+ *
+ * Mocks `lintCommand` and `loadChantConfigUpward` and drives the exported
+ * `runLint` dispatcher, the same shape ./build.test.ts uses for the matching
+ * #1108 gap in generate mode.
+ */
+import { describe, test, expect, vi, beforeEach, afterEach } from "vitest";
+import type { ParsedArgs } from "../registry";
+
+const lintCommandMock = vi.fn();
+const loadChantConfigUpwardMock = vi.fn();
+
+vi.mock("../commands/lint", async () => {
+  const actual = await vi.importActual<typeof import("../commands/lint")>("../commands/lint");
+  return {
+    ...actual,
+    lintCommand: (...args: unknown[]) => lintCommandMock(...args),
+    printLintResult: () => {},
+  };
+});
+vi.mock("../../config", async () => {
+  const actual = await vi.importActual<typeof import("../../config")>("../../config");
+  return { ...actual, loadChantConfigUpward: (...args: unknown[]) => loadChantConfigUpwardMock(...args) };
+});
+
+const { runLint } = await import("./lint");
+
+function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
+  return {
+    command: "lint",
+    path: ".",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    ...overrides,
+  };
+}
+
+describe("runLint build-time parameters (#2251)", () => {
+  beforeEach(() => {
+    lintCommandMock.mockReset().mockResolvedValue({ success: true, errorCount: 0, warningCount: 0, diagnostics: [] });
+    loadChantConfigUpwardMock.mockReset().mockResolvedValue({ config: {} });
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test("a project declaring no buildParams lints with an empty provenance array", async () => {
+    const exit = await runLint({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(lintCommandMock.mock.calls[0][0].buildParams).toEqual([]);
+  });
+
+  test("declared buildParams resolve from their defaults and reach lintCommand", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({
+      config: { buildParams: { env: { type: "string", default: "local" } } },
+    });
+
+    const exit = await runLint({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(lintCommandMock.mock.calls[0][0].buildParams).toEqual([
+      { name: "env", value: "local", source: "default" },
+    ]);
+  });
+
+  test("--param overrides the declared default, the same precedence chant build applies", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({
+      config: { buildParams: { env: { type: "string", default: "local" } } },
+    });
+
+    const exit = await runLint({ args: makeArgs({ param: ["env=pr-42"] }), plugins: [], serializers: [] });
+
+    expect(exit).toBe(0);
+    expect(lintCommandMock.mock.calls[0][0].buildParams).toEqual([
+      { name: "env", value: "pr-42", source: "cli" },
+    ]);
+  });
+
+  test("an unresolvable parameter exits non-zero without linting", async () => {
+    loadChantConfigUpwardMock.mockResolvedValue({
+      config: { buildParams: { env: { type: "string", required: true } } },
+    });
+
+    const exit = await runLint({ args: makeArgs(), plugins: [], serializers: [] });
+
+    expect(exit).toBe(1);
+    expect(lintCommandMock).not.toHaveBeenCalled();
+  });
+});

package/src/cli/handlers/lint.ts

@@ -1,6 +1,31 @@
+import { resolve } from "node:path";
 import { lintCommand, lintCommandWatch, printLintResult } from "../commands/lint";
 import { formatError, formatInfo } from "../format";
 import type { CommandContext } from "../registry";
+import { commandBuildParams } from "../build-params-cli";
+import { loadChantConfigUpward, type ChantConfig } from "../../config";
+
+/**
+ * chant #2251 — `chant lint` resolves this invocation's declared build-time
+ * parameters (`chant.config.ts`'s `buildParams`) before it lints, the same
+ * way `chant build` and the lifecycle family do (`commandBuildParams`,
+ * ../build-params-cli.ts).
+ *
+ * The OPS* checks import every `*.op.ts` file to read the Op it declares
+ * (../commands/lint.ts's `runOpCheckDiagnostics`), and an Op that takes a
+ * step argument from `params.<name>` (`@intentius/chant/params`) evaluates
+ * that read at module load. With no parameters resolved, `params` is the
+ * empty object every such argument reads `undefined` out of, and OPS012
+ * reports the activity contract violated — `args.env: expected string,
+ * received undefined` — for source that builds and runs correctly. The
+ * config is loaded by walking up from the lint path, so linting a
+ * subdirectory still sees the project root's declarations.
+ */
+async function lintBuildParams(args: { path: string; param?: string[]; paramsFile?: string }) {
+  const { config } = await loadChantConfigUpward(resolve(args.path)).catch(() => ({ config: {} as ChantConfig }));
+  if (!config.buildParams) return [];
+  return commandBuildParams(config.buildParams, args);
+}
 
 export async function runLint(ctx: CommandContext): Promise<number> {
   const { args } = ctx;
@@ -11,12 +36,16 @@ export async function runLint(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
+  const buildParams = await lintBuildParams(args);
+  if (buildParams === undefined) return 1;
+
   if (args.watch) {
     const cleanup = lintCommandWatch({
       path: args.path,
       fix: args.fix,
       format: lintFormat,
       sandbox: args.sandbox,
+      buildParams,
     });
     process.on("SIGINT", () => {
       cleanup();
@@ -31,6 +60,7 @@ export async function runLint(ctx: CommandContext): Promise<number> {
     fix: args.fix,
     format: lintFormat,
     sandbox: args.sandbox,
+    buildParams,
   });
 
   printLintResult(result);

package/src/components/SPRAWL-VALIDATION.md

@@ -16,16 +16,16 @@ generic `runInterpretDriver` (#556, [`../driver.ts`](./driver.ts)), unchanged.
 ## Before / after: the ALB/ECS pipeline glue this replaces
 
 The component model's whole reason for existing is visible in one concrete
-diff. [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../examples/gitlab-aws-alb-api/src/pipeline.ts)
-hand-rolls a `deployService` job that shells out to CloudFormation and greps
+diff. [`examples/gitlab-aws-alb-services/src/pipeline.ts`](../../../../examples/gitlab-aws-alb-services/src/pipeline.ts)
+hand-rolls a `deployServices` job that shells out to CloudFormation and greps
 its own infra stack's outputs before it can deploy:
 
 ```ts
-// before — examples/gitlab-aws-alb-api/src/pipeline.ts (deployService job)
+// before — examples/gitlab-aws-alb-services/src/pipeline.ts (deployServices job)
 `OUTPUTS=$(aws cloudformation describe-stacks --stack-name ${INFRA_STACK} --query 'Stacks[0].Outputs' --output json)`,
 `PARAMS=$(echo "$OUTPUTS" | jq -r '[(.[] | select(.OutputKey == "ClusterArn") | "clusterArn=" + .OutputValue), (.[] | select(.OutputKey == "ListenerArn") | "listenerArn=" + .OutputValue), ...] | join(" ")')`,
-`IMAGE_URI=$(echo "$OUTPUTS" | jq -r '.[] | select(.OutputKey == "ApiRepoUri") | .OutputValue'):${CI_COMMIT_REF_SLUG}`,
-`aws cloudformation deploy --template-file templates/template.json --stack-name ${STACK_NAME} ... --parameter-overrides $PARAMS image=$IMAGE_URI`,
+`API_IMAGE_URI=$(echo "$OUTPUTS" | jq -r '.[] | select(.OutputKey == "ApiRepoUri") | .OutputValue'):${CI_COMMIT_REF_SLUG}`,
+`aws cloudformation deploy --template-file templates/template.json --stack-name ${STACK_NAME} ... --parameter-overrides $PARAMS apiImage=$API_IMAGE_URI uiImage=$UI_IMAGE_URI`,
 ```
 
 That `describe-stacks | jq` line is bespoke per pipeline: every component that

package/src/components/pilots/README.md

@@ -13,7 +13,7 @@ The epic ([#551](https://github.com/INTENTIUS/chant/issues/551)) picked these th
 |---|---|---|---|---|---|---|
 | **Neo4j per-instance fan-out** | [`neo4j-fanout.pilot.ts`](./neo4j-fanout.pilot.ts) / [`neo4j-fanout.json`](../__fixtures__/neo4j-fanout.json) | no-build (`infra`, applies pre-built templates) | **fan-out** — one component composes 3 per-instance mini-compositions (`cfn-deploy` + `code-deploy` + `wait-cluster-healthy`), seed-first then rolling, gated at node 1 | simple apply (no `onReplace`/`stageGsi` — no sticky CFN concerns here) | none (self-contained cluster, no shared-stack imports) | **auto** — `code-deploy` (AWS CodeDeploy) rollback is native/automatic on failure, declared once inside the capability, never scripted per node |
 | **DynamoDB table** | [`dynamodb.pilot.ts`](./dynamodb.pilot.ts) / [`dynamodb-infra.json`](../__fixtures__/dynamodb-infra.json) | no-build (`infra`, applies an existing table template) | single (one `cfn-deploy`, no fan-out) | **sticky** — `onReplace: "block"` refuses a replacing changeset (data loss guard); `stageGsi: true` stages the GSI add→backfill→remove instead of an in-place replace | none | no rollback declared — a blocked replacement is not something to compensate, it is a stop |
-| **ALB/ECS target** | [`alb-ecs.pilot.ts`](./alb-ecs.pilot.ts) / [`alb-ecs-service.json`](../__fixtures__/alb-ecs-service.json) | **build** — `docker-build` → `publish-image` (promote by digest at deploy time) | single (one service, one `cfn-deploy` + `ecs-update-service`) | simple apply (no replacement-sensitive resource here) | **cross-stack** — imports `shared-alb`'s `ListenerArn`/`ClusterArn`/`Subnets` via `stackOutput()`, replacing the `describe-stacks \| jq` glue in [`examples/gitlab-aws-alb-api/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-api/src/pipeline.ts) | **no** (component-declared) — `ecs-update-service`/`cfn-deploy` have no native automatic rollback for an already-running service swap, so the component supplies an explicit `rollback` phase (`rollback-previous`) rather than relying on capability compensation |
+| **ALB/ECS target** | [`alb-ecs.pilot.ts`](./alb-ecs.pilot.ts) / [`alb-ecs-service.json`](../__fixtures__/alb-ecs-service.json) | **build** — `docker-build` → `publish-image` (promote by digest at deploy time) | single (one service, one `cfn-deploy` + `ecs-update-service`) | simple apply (no replacement-sensitive resource here) | **cross-stack** — imports `shared-alb`'s `ListenerArn`/`ClusterArn`/`Subnets` via `stackOutput()`, replacing the `describe-stacks \| jq` glue in [`examples/gitlab-aws-alb-services/src/pipeline.ts`](../../../../../examples/gitlab-aws-alb-services/src/pipeline.ts) | **no** (component-declared) — `ecs-update-service`/`cfn-deploy` have no native automatic rollback for an already-running service swap, so the component supplies an explicit `rollback` phase (`rollback-previous`) rather than relying on capability compensation |
 
 Read together, the three cover every cell at least once: build only shows up for ALB/ECS, fan-out only for Neo4j, sticky-apply only for DynamoDB, cross-stack only for ALB/ECS, and both rollback styles (capability-native vs component-declared) appear once each.
 

package/src/components/pilots/alb-ecs.pilot.ts

@@ -9,8 +9,8 @@
  * `ecs-update-service` → `wait-steady-state` + `health-gate`.
  *
  * This is the direct component-native replacement for the hand-rolled GitLab
- * pipeline in `examples/gitlab-aws-alb-api/src/pipeline.ts`: the
- * `describe-stacks`/`jq` glue in that pipeline's `deployService` job is
+ * pipeline in `examples/gitlab-aws-alb-services/src/pipeline.ts`: the
+ * `describe-stacks`/`jq` glue in that pipeline's `deployServices` job is
  * exactly the cross-stack `stackOutput()` wiring below, and its
  * `docker build`/`docker push` steps are the `docker-build` + `publish-image`
  * capabilities. `service` archetype: build → publish → apply → verify, the

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/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,

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

@@ -494,10 +494,11 @@ export interface ComponentPipelineResult {
  * the generated job needs to act on a finding — elevated write access for
  * `issue`/`comment`/`pull-request`/`merge-request`, none for `report`.
  *
- * `comment` posts the finding on the pull request that triggered the run
- * (#2231), so unlike every other mode it constrains the trigger: the github
- * generator refuses it by name on anything but `pull_request`, and the gitlab
- * and forgejo generators refuse it outright.
+ * `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" | "comment" | "pull-request" | "merge-request";
 
@@ -525,7 +526,9 @@ export type OpTrigger =
  *
  * 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.
+ * 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;
 
@@ -551,6 +554,38 @@ export interface OpSetupRunStep {
   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. */
@@ -594,6 +629,15 @@ export interface ScheduledOpSpec {
    * 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;
 }
 
 /**