@intentius/chant 0.124.27 → 0.124.29

package/src/components/release-promote.ts

@@ -0,0 +1,232 @@
+/**
+ * A promote under a release (#4026, ws-104 question 5): the deploy reads the
+ * templates the release recorded for the target environment, not the ones in
+ * the promoting checkout.
+ *
+ * Each template a promoted component's deploy names ({@link templateRefs}) has
+ * to be one the release's target records for that component. Its bytes are
+ * read from `_releases/templates/` on `chant/lifecycle` and checked against
+ * the target's digest, the way a promote checks the publish digest, and a
+ * mismatch refuses the promote before anything runs. The bytes are written
+ * under `.chant/release-templates/<digest>/` in the member's directory and the
+ * step reads them from there. The path is relative and fixed by the digest,
+ * so a gate approval bound to the promote's plan still matches on a re-run.
+ */
+
+import { mkdirSync, readdirSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { contentDigest } from "../content-digest";
+import type { DriverComponent, DriverGate, DriverPhase, DriverStep } from "./driver";
+import { TEMPLATE_FIELDS, templateRefs } from "./release-compile";
+import type { Release, ReleaseTarget } from "../lifecycle/release-store";
+import type { ReleaseRecord } from "../lifecycle/release-ledger";
+import type { BuildArchiveManifest } from "./verbs/build-archive";
+
+/** Where a promote under a release writes the recorded templates, relative to the member's directory. */
+export const RELEASE_TEMPLATES_DIR = ".chant/release-templates";
+
+/** A template ready to write: where, and its bytes. */
+export interface PinnedTemplate {
+  /** Relative to the member's directory. */
+  path: string;
+  content: string;
+}
+
+/** The release's target for `env`, or an error naming the environments it has. */
+export function targetFor(release: Release, env: string): { target: ReleaseTarget } | { error: string } {
+  const target = release.targets.find((t) => t.env === env);
+  if (target) return { target };
+  return {
+    error: `release ${release.releaseDigest} has no target for "${env}"; it was compiled for ${release.targets.map((t) => t.env).join(", ") || "no environment"}`,
+  };
+}
+
+/** Whether a release is of a project with no components (#4046): no artifact, and every template it records has `component: null`. */
+export function isImplicitRelease(release: Release): boolean {
+  const templates = release.targets.flatMap((t) => t.templates);
+  return release.artifactDigests.length === 0 && templates.length > 0 && templates.every((t) => t.component === null);
+}
+
+function isGate(step: DriverStep | DriverGate | DriverPhase): step is DriverGate {
+  return (step as { kind?: unknown }).kind === "gate";
+}
+
+function isPhase(step: DriverStep | DriverGate | DriverPhase): step is DriverPhase {
+  return typeof (step as { phase?: unknown }).phase === "string" && Array.isArray((step as DriverPhase).steps);
+}
+
+/**
+ * Point every template `components` read at the target's recorded bytes.
+ * Returns the rewritten compositions and the files to write, or the reasons
+ * the promote is refused: a template the target does not record, one whose
+ * bytes are missing, or one whose bytes do not hash to the target's digest.
+ */
+export async function pinReleaseTemplates(
+  components: readonly DriverComponent[],
+  release: Release,
+  target: ReleaseTarget,
+  readTemplate: (digest: string) => Promise<string | null>,
+): Promise<{ components: DriverComponent[]; files: PinnedTemplate[] } | { errors: string[] }> {
+  const errors: string[] = [];
+  const files: PinnedTemplate[] = [];
+  const out: DriverComponent[] = [];
+  for (const component of components) {
+    const replace = new Map<string, string>();
+    for (const ref of templateRefs(component)) {
+      if (replace.has(ref.value)) continue;
+      const recorded = target.templates.find((t) => t.component === component.name && t.path === ref.path);
+      if (!recorded) {
+        errors.push(
+          `component "${component.name}" reads ${ref.field} "${ref.value}", which release ${release.releaseDigest} does not record for "${target.env}"; ` +
+            `this checkout's deploy is not the one the release was compiled from (commit ${release.commit.slice(0, 12)})`,
+        );
+        continue;
+      }
+      const content = await readTemplate(recorded.digest);
+      if (content === null) {
+        errors.push(`component "${component.name}": the bytes of template "${ref.path}" (${recorded.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
+        continue;
+      }
+      const got = contentDigest(content);
+      if (got !== recorded.digest) {
+        errors.push(
+          `component "${component.name}": template "${ref.path}" hashes to ${got}, but the release's target for "${target.env}" records ${recorded.digest}; refusing to deploy it`,
+        );
+        continue;
+      }
+      const path = join(RELEASE_TEMPLATES_DIR, recorded.digest.replace(/:/g, "_"), basename(ref.path));
+      files.push({ path, content });
+      replace.set(ref.value, path);
+    }
+    const rewrite = (phase: DriverPhase): DriverPhase => ({
+      ...phase,
+      steps: phase.steps.map((step) => {
+        if (isPhase(step)) return rewrite(step);
+        if (isGate(step)) return step;
+        const next: DriverStep = { ...step };
+        for (const field of TEMPLATE_FIELDS) {
+          const v = next[field];
+          if (typeof v === "string" && replace.has(v)) next[field] = replace.get(v);
+          else if (Array.isArray(v)) next[field] = v.map((x) => (typeof x === "string" && replace.has(x) ? replace.get(x) : x));
+        }
+        return next;
+      }),
+    });
+    out.push({ ...component, deploy: component.deploy.map(rewrite) });
+  }
+  return errors.length > 0 ? { errors } : { components: out, files };
+}
+
+/**
+ * The files a release's target records, read back by digest and checked, for
+ * `chant release export` (#4046). A project with no components has no deploy
+ * step for a promote to point at the recorded bytes, so its deploy (an Op such
+ * as `chant run deploy`, or a CI job) reads the files this writes instead of
+ * building them again. Each path is the one the build wrote, relative to the
+ * member's directory; a template whose bytes are missing or don't hash to the
+ * target's digest is refused, as {@link pinReleaseTemplates} refuses one.
+ */
+export async function targetFiles(
+  release: Release,
+  target: ReleaseTarget,
+  readTemplate: (digest: string) => Promise<string | null>,
+): Promise<{ files: PinnedTemplate[] } | { errors: string[] }> {
+  const errors: string[] = [];
+  const files: PinnedTemplate[] = [];
+  for (const t of target.templates) {
+    const who = t.component === null ? "" : `component "${t.component}": `;
+    if (t.path.startsWith("/") || t.path.split("/").includes("..")) {
+      errors.push(`${who}template "${t.path}" is not a path inside the member's directory; refusing to write it`);
+      continue;
+    }
+    const content = await readTemplate(t.digest);
+    if (content === null) {
+      errors.push(`${who}the bytes of template "${t.path}" (${t.digest}) are not on the chant/lifecycle branch; fetch it and try again`);
+      continue;
+    }
+    const got = contentDigest(content);
+    if (got !== t.digest) {
+      errors.push(`${who}template "${t.path}" hashes to ${got}, but release ${release.releaseDigest} records ${t.digest} for "${target.env}"; refusing to write it`);
+      continue;
+    }
+    const same = files.find((f) => f.path === t.path);
+    if (same) {
+      if (same.content !== content) errors.push(`two components record different bytes at "${t.path}" for "${target.env}", so they can't both be written there`);
+      continue;
+    }
+    files.push({ path: t.path, content });
+  }
+  return errors.length > 0 ? { errors } : { files };
+}
+
+/** Write the pinned templates under `dir`, the member's directory. */
+export function writePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void {
+  for (const f of files) {
+    const full = join(dir, f.path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, f.content);
+  }
+}
+
+/**
+ * Remove the templates {@link writePinnedTemplates} wrote once the promote is
+ * done, and {@link RELEASE_TEMPLATES_DIR} with them when nothing else is in
+ * it, so a promote leaves the checkout as it found it. A re-run writes them
+ * again from the release.
+ */
+export function removePinnedTemplates(dir: string, files: readonly PinnedTemplate[]): void {
+  for (const f of files) rmSync(dirname(join(dir, f.path)), { recursive: true, force: true });
+  const root = join(dir, RELEASE_TEMPLATES_DIR);
+  try {
+    if (readdirSync(root).length === 0) rmdirSync(root);
+  } catch {
+    // Already gone, or not ours to remove.
+  }
+}
+
+/**
+ * Whether the artifact a promote deploys under a release is one the release
+ * built (#4045, the rule #4026 left open). The release records build digests
+ * (`artifactDigests`, the digest the archive step returned), and a deploy
+ * record carries the publish digest, which is another value for an image, so
+ * the two are compared through the build manifest the source deploy record
+ * names (`manifestDigest`), whose entries carry build digests at the same
+ * archive paths:
+ *
+ * - a source record that names this release in `releaseDigest` matches;
+ * - else, each of the release's artifacts for the component must be in that
+ *   manifest at its path with the release's digest, and one that differs is
+ *   a mismatch;
+ * - a record with no `manifestDigest`, a manifest that isn't stored, or an
+ *   artifact path the manifest doesn't hold can't be compared.
+ *
+ * A mismatch is a warning, not a refusal. The environment promoted from was
+ * deployed by its own `run --components`, which builds again, and an image
+ * build is not reproducible, so its digest differs from the cut's for the
+ * same commit. Refusing would refuse every image promote until a deploy can
+ * run the release's own artifacts (#4043).
+ */
+export async function releaseArtifactMismatches(
+  release: Release,
+  sources: ReadonlyArray<{ component: string; source: ReleaseRecord }>,
+  readManifest: (manifestDigest: string) => Promise<BuildArchiveManifest | null>,
+): Promise<string[]> {
+  const out: string[] = [];
+  for (const { component, source } of sources) {
+    if (source.releaseDigest === release.releaseDigest) continue;
+    const artifacts = release.artifactDigests.filter((a) => a.component === component);
+    if (artifacts.length === 0 || source.manifestDigest === undefined) continue;
+    const manifest = await readManifest(source.manifestDigest);
+    if (!manifest) continue;
+    for (const a of artifacts) {
+      const entry = manifest.contents.find((e) => e.path === a.path && e.kind === a.kind);
+      if (entry && entry.digest !== a.digest) {
+        out.push(
+          `${component}: the ${source.env} deploy being promoted was built with ${a.path} at ${entry.digest}, ` +
+            `but release ${release.releaseDigest} built it at ${a.digest}, so the artifact deployed is not the release's own`,
+        );
+      }
+    }
+  }
+  return out;
+}

package/src/components/run-progress.ts

@@ -90,6 +90,13 @@ export interface RunDoneEvent {
   status: RunProgressStatus;
 }
 
+/**
+ * @deprecated Read `RunEvent` (`../run-event.ts`, exported from
+ * `@intentius/chant`) instead: one contract for Op, component and pipeline
+ * runs, with the run id, commit and runtime on every event (#4019).
+ * `runEventOfProgress` maps each of these onto it. `--progress-json` keeps
+ * printing this shape until #4041 moves it to the run-event stream.
+ */
 export type RunProgressEvent =
   | RunStartEvent
   | WaveStartEvent

package/src/components/wave-plan.ts

@@ -19,7 +19,7 @@
  * `@<component>.publish.*`) resolves.
  */
 
-import { resolveStepInput, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
+import { resolveStepInput, unresolvedWiringSources, type DriverComponent, type DriverPhase, type DriverStep } from "./driver";
 import { componentPlanDigest } from "./gate-plan";
 import type { CapabilityRegistry, DeployContext } from "./capability";
 import type { WaveMember } from "../gated-waves";
@@ -44,7 +44,7 @@ function emptyPart(member: WaveMember): ChangeSetPart {
 }
 
 /** Every capability step in a composition, nested phases included, gates left out. */
-function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
+export function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
   const out: DriverStep[] = [];
   const walk = (steps: DriverPhase["steps"]): void => {
     for (const step of steps) {
@@ -60,6 +60,19 @@ function capabilitySteps(phases: readonly DriverPhase[]): DriverStep[] {
   return out;
 }
 
+/**
+ * The context a step is planned with: `ctx`, plus the components whose
+ * outputs the step reads and could not read yet (`unresolvedInputs`, #4084).
+ */
+export function planContext(
+  ctx: DeployContext,
+  stepInput: Record<string, unknown>,
+  componentOutputs: Record<string, Record<string, unknown>>,
+): DeployContext {
+  const unresolved = unresolvedWiringSources(stepInput, componentOutputs);
+  return unresolved.length > 0 ? { ...ctx, unresolvedInputs: unresolved } : ctx;
+}
+
 /** Plan one component against the outputs earlier waves produced. Never throws: a failure comes back as `error`. */
 export async function planWaveComponent(
   component: DriverComponent,
@@ -76,7 +89,7 @@ export async function planWaveComponent(
       if (!capability.plan) continue;
       const { kind: _kind, ...rest } = step;
       const input = resolveStepInput(rest, {}, componentOutputs);
-      const planned = await capability.plan(ctx, input as never);
+      const planned = await capability.plan(planContext(ctx, rest, componentOutputs), input as never);
       const member = { member: planned.member, planDigest: planned.planDigest };
       members.push(member);
       parts.push(planned.changeSet ?? emptyPart(member));

package/src/config.ts

@@ -12,6 +12,7 @@ import { findProjectConfig } from "./project-root";
 import { evaluateProjectConfig } from "./config-sandbox";
 import { lexiconNames, pathLexiconRoot, registerLexiconDeclarations, type LexiconDeclaration } from "./lexicon-module";
 import { decideConfigSchema, type DecideConfig } from "./op/decide-config";
+import { PublishDeclarationSchema, type PublishDeclaration } from "./lifecycle/publish-declaration";
 
 /**
  * One project-declared environment (chant #1166). Historically always a bare
@@ -22,8 +23,13 @@ import { decideConfigSchema, type DecideConfig } from "./op/decide-config";
  * silently querying real AWS. See {@link environmentName}, {@link
  * environmentNames}, {@link environmentEndpoint} below, and
  * `./live-endpoint.ts`'s `applyLiveEndpoint`, the CLI-side consumer.
+ *
+ * The array's order is the member's promotion order (#4030, see
+ * `./workspace/promotion-order.ts`), and `canary: true` marks a step as the
+ * canary step of that order. The canary is declared and surfaced; chant does
+ * not yet act on it.
  */
-export type EnvironmentDeclaration = string | { name: string; endpoint?: string };
+export type EnvironmentDeclaration = string | { name: string; endpoint?: string; canary?: boolean };
 
 /**
  * `ownership.env`: a literal environment identity, or a reference to a
@@ -124,6 +130,7 @@ const EnvironmentEntrySchema = z.union([
   z.object({
     name: z.string().min(1),
     endpoint: z.string().min(1).optional(),
+    canary: z.boolean().optional(),
   }),
 ]);
 
@@ -163,6 +170,7 @@ export const ChantConfigSchema = z.object({
   ).optional(),
   release: z.object({
     autoRecord: z.boolean().optional(),
+    publish: z.array(PublishDeclarationSchema).optional(),
   }).optional(),
   // Strict: a misspelt key here would leave Ops on the local runtime with
   // nothing said (#2523).
@@ -376,6 +384,12 @@ export interface ChantConfig {
   release?: {
     /** Set false to disable auto-emitting a release record after a successful component deploy project-wide. The `--no-release-record` CLI flag overrides this per-invocation. */
     autoRecord?: boolean;
+    /**
+     * Where `chant release publish` publishes a cut release (#4047): npm
+     * packages, an image in an OCI registry, release assets on a forge. Run in
+     * the order given. See ./lifecycle/publish-declaration.ts.
+     */
+    publish?: PublishDeclaration[];
   };
 
   /** Defaults for `chant run` and its subcommands (#2523). */

package/src/flag-params.test.ts

@@ -0,0 +1,144 @@
+/**
+ * Build-time parameters from workspace flags (#4024): what a build for an
+ * environment resolves in a member with flags, and the precedence rule that a
+ * flag-backed parameter can't be overridden where the environment has a gate.
+ * On the fixture in `workspace/__fixtures__/flag-workspace.ts`, where member
+ * `shop`'s component declares a gate and member `blog`'s does not.
+ */
+
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test, vi } from "vitest";
+import { buildCommand } from "./cli/commands/build";
+import type { Serializer } from "./serializer";
+import type { BuildParamsConfig } from "./build-params";
+import { loadBuildParamFlags, resolveFlaggedBuildParams } from "./flag-params";
+import { cleanScratch, scratchDir } from "./workspace/__fixtures__/contract-repo";
+import { flagWorkspace } from "./workspace/__fixtures__/flag-workspace";
+
+const SHOP: BuildParamsConfig = { newCheckout: { type: "boolean", default: false }, tier: { type: "string", default: "small" } };
+const BLOG: BuildParamsConfig = { banner: { type: "boolean", default: false } };
+
+let root: string;
+beforeAll(() => {
+  root = flagWorkspace();
+});
+afterAll(cleanScratch);
+
+const quiet = { echo: false } as const;
+
+describe("loadBuildParamFlags", () => {
+  test("outside a workspace, and without an environment, there are no flags", async () => {
+    const plain = scratchDir("chant-flags-plain-");
+    expect(await loadBuildParamFlags(plain, "prod")).toEqual({ flags: undefined, errors: [] });
+    expect(await loadBuildParamFlags(join(root, "shop"), undefined)).toEqual({ flags: undefined, errors: [] });
+  });
+
+  test("in a member, each flag-backed parameter with the flag's value for the environment", async () => {
+    expect(await loadBuildParamFlags(join(root, "shop"), "dev")).toEqual({
+      flags: { env: "dev", byParam: { newCheckout: { flag: "new-checkout", value: true } } },
+      errors: [],
+    });
+  });
+
+  test("a flag kind that can't be read stops the build rather than building without its flags", async () => {
+    const dir = flagWorkspace({ "flags/flag.schema.json": "{ not json" });
+    const loaded = await loadBuildParamFlags(join(dir, "shop"), "prod");
+    expect(loaded.flags).toBeUndefined();
+    expect(loaded.errors[0]).toMatch(/the workspace's flag records can't be read/);
+  });
+});
+
+describe("resolveFlaggedBuildParams", () => {
+  test("records the flag as the parameter's source, per environment", async () => {
+    const prod = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, quiet, "prod");
+    expect(prod).toEqual({
+      success: true,
+      errors: [],
+      provenance: [
+        { name: "newCheckout", value: false, source: "flag:new-checkout" },
+        { name: "tier", value: "small", source: "default" },
+      ],
+    });
+    const dev = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, quiet, "dev");
+    expect(dev.provenance[0]).toEqual({ name: "newCheckout", value: true, source: "flag:new-checkout" });
+    // staging: the record gives no value, so the declared default applies.
+    expect((await resolveFlaggedBuildParams(join(root, "shop"), SHOP, quiet, "staging")).provenance[0]).toEqual({ name: "newCheckout", value: false, source: "default" });
+  });
+
+  test("--param can't override a flag in an environment with a gate: the build refuses", async () => {
+    const refused = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, { ...quiet, cli: { newCheckout: "true" } }, "prod");
+    expect(refused.success).toBe(false);
+    expect(refused.provenance).toEqual([]);
+    expect(refused.errors).toHaveLength(1);
+    expect(refused.errors[0]).toMatch(/build parameter "newCheckout" is backed by the flag "new-checkout", and "prod" has a gate, so --param can't set it/);
+    expect(refused.errors[0]).toMatch(/gates: prod-release/);
+  });
+
+  test("--params-file can't either, and a parameter no flag backs still can", async () => {
+    const file = join(scratchDir("chant-flags-file-"), "params.json");
+    writeFileSync(file, JSON.stringify({ newCheckout: true }));
+    const refused = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, { ...quiet, paramsFile: file }, "prod");
+    expect(refused.success).toBe(false);
+    expect(refused.errors[0]).toMatch(/so --params-file can't set it/);
+    const tier = await resolveFlaggedBuildParams(join(root, "shop"), SHOP, { ...quiet, cli: { tier: "large" } }, "prod");
+    expect(tier.success).toBe(true);
+    expect(tier.provenance).toContainEqual({ name: "tier", value: "large", source: "cli" });
+  });
+
+  test("where no component declares a gate, --param still overrides the flag", async () => {
+    const r = await resolveFlaggedBuildParams(join(root, "blog"), BLOG, { ...quiet, cli: { banner: "false" } }, "prod");
+    expect(r.success).toBe(true);
+    expect(r.provenance).toEqual([{ name: "banner", value: false, source: "cli" }]);
+  });
+
+  test("components that can't be read refuse an override, since the gate can't be ruled out", async () => {
+    const dir = flagWorkspace({ "shop/broken.component.ts": "export const = ;\n" });
+    const r = await resolveFlaggedBuildParams(join(dir, "shop"), SHOP, { ...quiet, cli: { newCheckout: "true" } }, "prod");
+    expect(r.success).toBe(false);
+    expect(r.errors[0]).toMatch(/whether "prod" has a gate can't be told/);
+  });
+});
+
+describe("chant build --env in a member with flags", () => {
+  const runtime = join(import.meta.dirname, "runtime");
+  const paramsModule = join(import.meta.dirname, "params");
+  const serializer: Serializer = {
+    name: "aws",
+    rulePrefix: "TEST",
+    serialize: (entities) => JSON.stringify([...entities.values()].map((e) => (e as unknown as { props: unknown }).props)),
+  };
+  const shopFiles = {
+    "shop/chant.config.ts": `export default { environments: ["dev", "staging", "prod"], buildParams: { newCheckout: { type: "boolean", default: false } } };\n`,
+    "shop/main.ts":
+      `import { createResource } from ${JSON.stringify(runtime)};\n` +
+      `import { params } from ${JSON.stringify(paramsModule)};\n` +
+      `const Bucket = createResource("Test::Bucket", "aws", { arn: "Arn" });\n` +
+      `export const bucket = new Bucket({ checkout: params.newCheckout ? "new" : "old" });\n`,
+  };
+
+  test("records the flag on BuildResult.buildParams and builds with its value", async () => {
+    const dir = flagWorkspace(shopFiles);
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({ path: join(dir, "shop"), format: "json", serializers: [serializer], env: "dev" });
+      expect(result.errors).toEqual([]);
+      expect(result.buildParams).toEqual([{ name: "newCheckout", value: true, source: "flag:new-checkout" }]);
+      expect(spy.mock.calls.map((c) => String(c[0])).some((l) => l.includes("1 build parameter resolved (1 from flags)"))).toBe(true);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("refuses --param for a flag-backed parameter in an environment with a gate", async () => {
+    const dir = flagWorkspace(shopFiles);
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await buildCommand({ path: join(dir, "shop"), format: "json", serializers: [serializer], env: "prod", params: { newCheckout: "true" } });
+      expect(result.success).toBe(false);
+      expect(result.errors.join("\n")).toMatch(/"newCheckout" is backed by the flag "new-checkout", and "prod" has a gate, so --param can't set it/);
+    } finally {
+      spy.mockRestore();
+    }
+  });
+});

package/src/flag-params.ts

@@ -0,0 +1,134 @@
+/**
+ * Build-time parameters from workspace flags (#4024, decided in #4016).
+ *
+ * A member of a workspace may have flag records: records of a kind with a
+ * `flag` block, each naming the member, one of its declared build
+ * parameters and a value per environment (`workspace/flags.ts`). A build
+ * for an environment (`chant build --env <env>`, `chant run --components
+ * --env <env>`, and each environment a release cut compiles) reads them, and
+ * a flag-backed parameter takes the flag's value for that environment,
+ * recorded as `source: "flag:<name>"` on `BuildResult.buildParams` and on the
+ * release target's `params`.
+ *
+ * The precedence rule: where the environment has a gate, `--param`,
+ * `--params-file` and the parameter's env var can't set a flag-backed
+ * parameter, and the build refuses. An environment has a gate when a
+ * component enabled in it declares a gate step, the same test `components
+ * promote --release` uses to bind a release gate. The test runs only when one
+ * of those sources did set a flag-backed parameter, since it imports the
+ * member's components; a project with no components has no gate.
+ *
+ * Level 0 pays one upward `existsSync` walk here and nothing more. Workspace
+ * code is imported only once a declaration is found (#2525 rule 5, pinned by
+ * #2526's goldens).
+ */
+
+import { findWorkspaceRoot } from "./project-root";
+import { flagGateRefusal, type BuildParamFlags, type BuildParamsConfig } from "./build-params";
+import type { BuildParamProvenance } from "./provenance";
+import { echoBuildParams, resolveCliBuildParams, type CliBuildParamsArgs, type CliBuildParamsResolution } from "./cli/build-params-cli";
+import { formatError } from "./cli/format";
+
+/** The flags backing parameters of the member at `projectDir` in `env`, or why they can't be read. `flags` is undefined outside a workspace, without an environment, or when no flag names the member. */
+export async function loadBuildParamFlags(projectDir: string, env: string | undefined): Promise<{ flags: BuildParamFlags | undefined; errors: string[] }> {
+  if (!env) return { flags: undefined, errors: [] };
+  const found = findWorkspaceRoot(projectDir);
+  if (!found) return { flags: undefined, errors: [] };
+  const { memberFlagBindings } = await import("./workspace/flags-read");
+  try {
+    const bindings = await memberFlagBindings(found.dir, projectDir, env);
+    if (!bindings) return { flags: undefined, errors: [] };
+    if (bindings.errors.length > 0) return { flags: undefined, errors: bindings.errors };
+    if (Object.keys(bindings.byParam).length === 0) return { flags: undefined, errors: [] };
+    return { flags: { env, byParam: bindings.byParam }, errors: [] };
+  } catch (err) {
+    const { WorkspaceReadError } = await import("./workspace/declaration");
+    const { RecordReadError } = await import("./workspace/records");
+    if (err instanceof WorkspaceReadError || err instanceof RecordReadError) {
+      return { flags: undefined, errors: [`the workspace's flag records can't be read, so this build can't tell which parameters they set: ${err.message}`] };
+    }
+    throw err;
+  }
+}
+
+/** The parameters a flag backs that `--param`, `--params-file` or an env var set instead. */
+export function overriddenFlagParams(provenance: readonly BuildParamProvenance[], flags: BuildParamFlags | undefined): BuildParamProvenance[] {
+  if (!flags) return [];
+  return provenance.filter((p) => flags.byParam[p.name] !== undefined && (p.source === "cli" || p.source === "params-file" || p.source === "env"));
+}
+
+/**
+ * The gates the member's components declare in the environment the process
+ * builds for (`CHANT_ENV`), with the parameters as resolved, or why the
+ * components can't be read. Only components enabled under those parameters
+ * count.
+ */
+export async function environmentGates(projectDir: string, provenance: BuildParamProvenance[]): Promise<{ gates: string[] } | { error: string }> {
+  const { discoverComponents } = await import("./components/discover");
+  const { withoutDisabled } = await import("./components/cli-support");
+  const { gateNamesOf } = await import("./components/release-gate");
+  try {
+    const discovered = await discoverComponents(projectDir, { buildParams: provenance });
+    if (discovered.errors.length > 0) return { error: discovered.errors.map((e) => e.message).join("; ") };
+    const all = [...discovered.components.values()].map((d) => d.component);
+    const plain = all.map((c) => ({ name: c.name, dependsOn: c.dependsOn, deploy: c.deploy as never }));
+    return { gates: gateNamesOf(withoutDisabled(all, plain)) };
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Resolve the build parameters of the project at `projectDir` for `env`,
+ * with the workspace's flags, as `resolveCliBuildParams` does without them.
+ * Refuses when a flag record can't be read, and when `--param`,
+ * `--params-file` or an env var sets a flag-backed parameter in an
+ * environment with a gate. Prints the summary line only on success.
+ */
+export async function resolveFlaggedBuildParams(
+  projectDir: string,
+  buildParamsConfig: BuildParamsConfig | undefined,
+  args: CliBuildParamsArgs,
+  env: string | undefined,
+): Promise<CliBuildParamsResolution> {
+  const loaded = await loadBuildParamFlags(projectDir, env);
+  if (loaded.errors.length > 0) {
+    return { success: false, provenance: [], errors: loaded.errors.map((message) => formatError({ message })) };
+  }
+  const { flags } = loaded;
+  const resolution = resolveCliBuildParams(buildParamsConfig, { ...args, ...(flags ? { flags } : {}), echo: false });
+  if (!resolution.success || !flags) {
+    if (resolution.success && args.echo !== false) echoBuildParams(resolution.provenance, args.verbose);
+    return resolution;
+  }
+  const overridden = overriddenFlagParams(resolution.provenance, flags);
+  if (overridden.length > 0) {
+    const found = await environmentGates(projectDir, resolution.provenance);
+    if ("error" in found) {
+      return {
+        success: false,
+        provenance: [],
+        errors: [
+          formatError({
+            message:
+              `${overridden.map((p) => `"${p.name}"`).join(", ")} ${overridden.length === 1 ? "is" : "are"} backed by a flag and set by ${[...new Set(overridden.map((p) => p.source))].join(", ")}, ` +
+              `and whether "${flags.env}" has a gate can't be told, because its components can't be read: ${found.error}`,
+          }),
+        ],
+      };
+    }
+    if (found.gates.length > 0) {
+      const around = (p: BuildParamProvenance): string =>
+        p.source === "cli" ? "--param" : p.source === "params-file" ? "--params-file" : `the env var ${buildParamsConfig?.[p.name]?.env ?? "(unknown)"}`;
+      return {
+        success: false,
+        provenance: [],
+        errors: overridden.map((p) =>
+          formatError({ message: `${flagGateRefusal(p.name, flags.byParam[p.name].flag, flags.env, around(p))} (gates: ${found.gates.join(", ")})` }),
+        ),
+      };
+    }
+  }
+  if (args.echo !== false) echoBuildParams(resolution.provenance, args.verbose);
+  return resolution;
+}

package/src/index.ts

@@ -153,6 +153,8 @@ export type { SymbolDeclaration, SymbolResolver } from "./workspace/symbols";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
 export * from "./lifecycle/index";
+// The run-event contract (#4019): the types and the one writer of a run's stream.
+export * from "./run-event";
 // Op builders — use explicit exports to avoid collision with the core `build` function
 export { Op, phase, activity, gate, kubectlApply, helmInstall, waitForStack,
          gitlabPipeline, lifecycleSnapshot, shell, teardown, OpResource } from "./op/index";