@intentius/chant 0.59.0 → 0.61.0

package/dist/op/activities/reconcile.d.ts

@@ -6,6 +6,13 @@
  * re-run (chant #2231). It therefore needs a pull-request trigger, and
  * {@link resolvePullRequestContext} fails the step by name when the run has
  * none.
+ *
+ * On GitLab the same mode writes a merge-request note (chant #2256): the same
+ * marker, the same edit-in-place, a different API. Which forge a run is on is
+ * read off the run's own CI variables rather than configured — a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, a GitHub
+ * `pull_request` event sets `GITHUB_REPOSITORY`, and no run sets both. See
+ * {@link mergeRequestContextFrom}.
  */
 export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 /** A change-set entry that triggered reconciliation. */
@@ -69,10 +76,12 @@ export interface ReconcileResult {
     prUrl?: string;
     /** Opened issue URL (issue mode). */
     issueUrl?: string;
-    /** The posted or updated PR comment's URL (comment mode). */
+    /** The posted or updated PR comment / MR note URL (comment mode). */
     commentUrl?: string;
-    /** The pull request the comment landed on, `owner/repo#number` (comment mode). */
+    /** The pull request the comment landed on, `owner/repo#number` (comment mode, GitHub). */
     pullRequest?: string;
+    /** The merge request the note landed on, `group/project!iid` (comment mode, GitLab — #2256). */
+    mergeRequest?: string;
     /** The markdown summary used as the PR/issue body. */
     summary: string;
     /** The entries that triggered the reconcile. */
@@ -101,7 +110,7 @@ export interface PullRequestContext {
  * environments own two comments and each updates in place.
  */
 export declare function commentMarker(env: string): string;
-/** What a `comment`-mode step says when the run it is in has no pull request. */
+/** What a `comment`-mode step says when the run it is in has no pull request and no merge request. */
 export declare function noPullRequestContextMessage(): string;
 /**
  * Derive the triggering pull request from CI environment variables plus the
@@ -119,6 +128,66 @@ export declare function pullRequestContextFrom(env: Record<string, string | unde
  * for it.
  */
 export declare function resolvePullRequestContext(env?: Record<string, string | undefined>): Promise<PullRequestContext>;
+/**
+ * The merge request a `comment`-mode run posts its note onto (#2256), as a
+ * GitLab CI job knows it. The GitLab counterpart of {@link
+ * PullRequestContext}.
+ */
+export interface MergeRequestContext {
+    /** REST v4 base, from `CI_API_V4_URL` or derived from `CI_SERVER_URL`. */
+    api: string;
+    /** The project holding the merge request — its numeric id, or a `group/project` path. */
+    project: string;
+    /** The merge request's `iid` (its per-project number, which is what the API path takes). */
+    iid: number;
+    /** `group/project`, for the human-readable `group/project!iid` on the result. */
+    path?: string;
+    /** The project's web URL, used to build the note's own URL. */
+    webUrl?: string;
+}
+/**
+ * Derive the triggering merge request from a GitLab job's CI variables. Pure
+ * — exported for testing, and the whole forge detection: nothing but a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, so a run that
+ * has it is on GitLab and has a merge request, and a run that does not is
+ * neither.
+ *
+ * The project is the merge request's own (`CI_MERGE_REQUEST_PROJECT_ID`) in
+ * preference to the pipeline's (`CI_PROJECT_ID`): a merge request opened from
+ * a fork runs its pipeline in the fork, and the note belongs on the target
+ * project's merge request rather than on an iid that means something else in
+ * the fork.
+ *
+ * Returns undefined rather than throwing, so the caller owns the message.
+ */
+export declare function mergeRequestContextFrom(env: Record<string, string | undefined>): MergeRequestContext | undefined;
+/** The credential a merge-request note is written with, and the header GitLab reads it from. */
+export interface GitlabNoteToken {
+    /** `PRIVATE-TOKEN` for a personal/project/group access token, `JOB-TOKEN` for `CI_JOB_TOKEN`. */
+    header: "PRIVATE-TOKEN" | "JOB-TOKEN";
+    value: string;
+    /** The variable it came from, so a refusal or a log line can name it. */
+    source: string;
+}
+/**
+ * Resolve the token a merge-request note is written with, most specific
+ * first. Pure — exported for testing.
+ *
+ * Two headers, not one, because GitLab reads two different credentials from
+ * two different headers: an access token goes in `PRIVATE-TOKEN`, and the
+ * pipeline's own ephemeral `CI_JOB_TOKEN` goes in `JOB-TOKEN`. Sending one in
+ * the other's header is a 401, not a fallback.
+ *
+ * The access token is preferred because it is the one that reliably works:
+ * `CI_JOB_TOKEN` reaches only the endpoints GitLab's job-token allowlist
+ * names, and the notes API is not among them on current GitLab, so a project
+ * that has not widened that allowlist needs a token with `api` scope. It is
+ * still accepted last rather than refused, so a project on an instance whose
+ * allowlist does cover notes needs no long-lived credential at all.
+ */
+export declare function gitlabNoteTokenFrom(env: Record<string, string | undefined>): GitlabNoteToken | undefined;
+/** What a `comment`-mode step says on a merge request it has no credential for. */
+export declare function noGitlabNoteTokenMessage(iid: number): string;
 /**
  * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
  * `noop` entries (nothing to reconcile). Pure — exported for testing.
@@ -131,10 +200,13 @@ export declare function entriesFromPlan(planJson: string): ReconcileEntry[];
  * - `issue` — open a GitHub issue describing the drift (no code change).
  * - `comment` — post the body as one comment on the pull request that
  *   triggered the run, editing that same comment on every re-run rather than
- *   stacking a new one (#2231). Needs a pull-request-triggered run; fails by
- *   name when there is none. No code change, and the `pull-requests: write`
- *   the generated workflow already grants on that trigger is the whole scope
- *   it spends.
+ *   stacking a new one (#2231), or, on a GitLab `merge_request_event`
+ *   pipeline, as one note on that merge request by the same recipe (#2256).
+ *   Needs a pull-request- or merge-request-triggered run; fails by name when
+ *   there is none. No code change, and the `pull-requests: write` the
+ *   generated workflow already grants on that trigger is the whole scope it
+ *   spends on GitHub; on GitLab the scope is whatever the token it is given
+ *   carries.
  * - `pull-request` — create a branch, regenerate source via
  *   `chant import --from <env>`, commit, push, and open a PR whose diff is the
  *   regenerated TypeScript. Never commits to the main branch.

package/dist/op/activities/reconcile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/op/activities/reconcile.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5E,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,8CAA8C;IAC9C,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,aAAa,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,CAkB/E;AAMD,wDAAwD;AACxD,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,2BAA2B,IAAI,MAAM,CAQpD;AAeD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACvC,YAAY,CAAC,EAAE,OAAO,GACrB,kBAAkB,GAAG,SAAS,CAOhC;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAAC,kBAAkB,CAAC,CAe7B;AA2CD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAOlE;AAgBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC,CAmDvG"}
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../../src/op/activities/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/op/gate-summary.d.ts

@@ -8,9 +8,14 @@
  * markdown scratchpad through `GITHUB_STEP_SUMMARY`, rendered at the top of
  * the run page; anything else that sets the variable gets the same block.
  *
- * That is the whole forge coupling: one environment variable, appended to
- * when it is set, and nothing at all when it is not. No API call, no token,
- * no flag to turn it on.
+ * GitLab CI sets no such variable and has no step summary at all: a job's
+ * surfaces are its log and its artifacts (#2256). So `CHANT_GATE_SUMMARY`
+ * names a second path, which the generated GitLab job sets to a file it also
+ * declares under `artifacts:`. Same block, same rule, one more variable.
+ *
+ * That is the whole forge coupling: two environment variables, appended to
+ * whichever is set, and nothing at all when neither is. No API call, no
+ * token, no flag to turn it on.
  */
 /** What a gated run knows about the gate it stopped on. */
 export interface GatedRunSummary {
@@ -33,7 +38,14 @@ export interface GatedRunSummary {
 export declare function gatedRunSummaryMarkdown(summary: GatedRunSummary): string;
 /**
  * Append {@link gatedRunSummaryMarkdown} to the file `GITHUB_STEP_SUMMARY`
- * names, when the variable is set and the file can be written.
+ * names, or, where the forge sets no such variable, the one
+ * `CHANT_GATE_SUMMARY` names (#2256) — when it is set and the file can be
+ * written.
+ *
+ * The forge's own variable wins where both are set: a step summary is
+ * rendered on the run page, an artifact has to be downloaded, and writing
+ * both would put the same block in two places on a forge that already shows
+ * one of them.
  *
  * Returns the path written, or `undefined` when there was nothing to write to.
  * A write that fails is swallowed: a run that already decided its outcome must

package/dist/op/gate-summary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate-summary.d.ts","sourceRoot":"","sources":["../../src/op/gate-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAuBxE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CASpB"}
+{"version":3,"file":"gate-summary.d.ts","sourceRoot":"","sources":["../../src/op/gate-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAuBxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CASpB"}

package/dist/params.d.ts

@@ -6,7 +6,7 @@
  * is a deploy-time CloudFormation parameter: it emits a `Parameters:` block and
  * resolves when the STACK deploys. A build-time parameter resolves before the
  * template is even synthesized — its value can change WHICH resources are
- * produced at all (loomster's `LOOM_TIER` selecting `light` vs `production` vs
+ * produced at all (a `tier` parameter selecting `light` vs `production` vs
  * `production-ha`), which a deploy-time `Parameter` structurally cannot do.
  *
  * Project source never reads `process.env` directly to vary a build — that

package/dist/project-root.d.ts

@@ -9,8 +9,8 @@
  * `src/<stack>` layout — `chant build src/<stack>` two or more levels below
  * the project root — silently never found the root config: `buildParams`'
  * declared `env:` mappings went inert, `ownership`/`lint.policies`/etc quietly
- * fell back to defaults, and nothing warned (loomster#162: `LOOM_TIER`/
- * `LOOM_ENV` inert under every `npm run synth:*` for two releases).
+ * fell back to defaults, and nothing warned. That failure ran under every
+ * `npm run synth:*` of one project for two releases before anyone noticed it.
  *
  * `findProjectConfig` is the one walk every config-discovery call site now
  * shares. It stops at the first of:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.59.0",
+  "version": "0.61.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/build-params.ts

@@ -33,8 +33,8 @@ export interface BuildParamDef {
   /**
    * Allowed values — a resolved value outside this list is a build error
    * naming the parameter (never a thrown error from user source). Replaces
-   * the hand-written `if (!VALID.includes(raw)) throw ...` pattern loomster's
-   * `params.ts` files used before migrating to this mechanism.
+   * the hand-written `if (!VALID.includes(raw)) throw ...` pattern a project's
+   * own `params.ts` writes before migrating to this mechanism.
    */
   enum?: readonly BuildParamValue[];
   /**

package/src/cli/commands/build.ts

@@ -174,8 +174,8 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // Resolve opt-in ownership marking from project config. chant #1117 — walks
   // up from the infra dir to the project root (`loadChantConfigUpward`), not
   // just the infra dir's immediate parent: a project whose stacks live two or
-  // more levels below `chant.config.ts` (loomster's `src/<stack>` layout)
-  // otherwise never finds the root config at all, and every declared
+  // more levels below `chant.config.ts` (a `src/<stack>` layout) otherwise
+  // never finds the root config at all, and every declared
   // `buildParams`/`ownership`/`lint.policies` setting silently falls back to
   // its default.
   const loaded = await loadChantConfigUpward(infraPath);
@@ -233,10 +233,10 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // BEFORE calling build() — a resolution failure (an unknown name, a
   // missing required value, a type/enum mismatch) is reported as a chant
   // build error naming the parameter, never a thrown error from inside user
-  // source (which is what loomster's hand-rolled `tierFromEnv()`-style
-  // validators did before migrating to this mechanism). Also logs a one-line
-  // count on success, or every resolved value (`[param] name = value
-  // (source)`) under --verbose (#1424).
+  // source (which is what a hand-rolled `tierFromEnv()`-style validator in a
+  // project's own `params.ts` does before migrating to this mechanism). Also
+  // logs a one-line count on success, or every resolved value (`[param] name =
+  // value (source)`) under --verbose (#1424).
   const paramsResolution = resolveCliBuildParams(config.buildParams, {
     cli: options.params,
     paramsFile: options.paramsFile,
@@ -248,8 +248,8 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   }
 
   // chant #1117 — a project that declares buildParams but resolves NONE of
-  // them for this build is the exact shape that let loomster#162 live for two
-  // releases: the discovered config wasn't the one the project author
+  // them for this build is the exact shape that let a silent misresolution run
+  // for two releases: the discovered config wasn't the one the project author
   // expected (a stale --path, a workspace boundary that stopped the walk
   // short), or every declared parameter's `env:` var went unset, and either
   // way every `params.<name>` read silently falls back to `undefined` — with

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

@@ -591,7 +591,7 @@ export async function runComponentsStatus(ctx: CommandContext): Promise<number>
             // rather than "stale" (recorded, and nothing live).
             const message = err instanceof Error ? err.message : String(err);
             console.error(formatWarning({ message: `${plugin.name}: describeResources failed — ${message} (components in this lexicon report unknown, not stale)` }));
-            observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {}, notes: [] };
+            observed = { resources: {}, unobserved: unobservedAll(declared, "read-failed", message, entities), queried: {}, sources: {}, notes: [] };
           }
           const cs = buildChangeSet(environment, {
             declared,

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

@@ -782,6 +782,7 @@ async function observeLexicon(
       resources: {},
       unobserved: unobservedAll(entityNames, "read-failed", message, opts.entities),
       queried: {},
+      sources: {},
       notes: [],
     };
   }