@intentius/chant 0.124.44 → 0.124.46

package/src/components/pr-environment.ts

@@ -32,14 +32,20 @@
  *
  * terragucci's `ephemeral.ts` gives each copy a suffixed Terraform state key.
  * That part is Terraform's own and stays there; chant keys ownership on the
- * marker its lexicons stamp and read back (`../lifecycle/teardown.ts`).
+ * marker its lexicons stamp and read back (`../lifecycle/teardown.ts`). A
+ * product supplies the rest as adapters (#4330): its plan and apply
+ * (`./pr-env-run.ts`), and a teardown for what no lexicon tears down
+ * ({@link PrEnvTeardownAdapter}), which reads the marker back from the copy
+ * as a lexicon does.
  */
 
-import { environmentEndpoint, environmentName, isEnvironmentPattern, isOwnershipParamRef, matchesDeclaredEnvironment, resolveOwnershipStack, type ChantConfig, type EnvironmentDeclaration } from "../config";
+import type { ChantConfig } from "../config";
+import { environmentEndpoint, environmentName, isEnvironmentPattern, isOwnershipParamRef, matchesDeclaredEnvironment, resolveOwnershipStack, type EnvironmentDeclaration } from "../config-environments";
 import type { OwnershipMarker } from "../ownership";
 import { executeTeardown, planTeardown, type TeardownPlan, type TeardownPlanEntry, type TeardownReport } from "../lifecycle/teardown";
-import type { ObservationLexicon } from "../lexicon";
+import type { ObservationLexicon, TeardownCandidate, TeardownEnumeration, TeardownExecution } from "../lexicon";
 import { applyLiveEndpoint } from "../live-endpoint";
+import type { ComponentEnvironmentDeclaration } from "./component";
 
 /** The gate a pull request's environment waits on, under the pull request's op `pr-<n>`. */
 export const PR_ENV_GATE = "pr-env";
@@ -167,6 +173,35 @@ export function derivePrEnvironment(config: ChantConfig, template: string, pr: n
   return { env, template, stack, param: own.param, environments, ...(endpoint ? { endpoint } : {}) };
 }
 
+/** The placeholder a template's site URL or domain names the environment with (#4330). */
+export const PR_ENV_SITE_PLACEHOLDER = "{env}";
+
+/**
+ * A component's site in `env`, a pull request's environment, carried over
+ * from its site in `template` (#4330). An entry the component declares for
+ * `env` itself wins. Otherwise the template's runtime and lifecycle remote
+ * carry over as they are. Its URL and domain carry over only when they name
+ * the environment with `{env}`, which becomes `pr-<n>`: a literal URL or
+ * domain is the template's own release, so it is left out rather than
+ * pointing pr-<n> at it. Undefined when neither is declared.
+ */
+export function prEnvironmentSite(declared: readonly ComponentEnvironmentDeclaration[] | undefined, template: string, env: string): ComponentEnvironmentDeclaration | undefined {
+  const own = declared?.find((d) => d.name === env);
+  if (own) return { ...own };
+  const from = declared?.find((d) => d.name === template);
+  if (!from) return undefined;
+  const named = (v: string | undefined): string | undefined => (v && v.includes(PR_ENV_SITE_PLACEHOLDER) ? v.split(PR_ENV_SITE_PLACEHOLDER).join(env) : undefined);
+  const url = named(from.url);
+  const domain = named(from.domain);
+  return {
+    name: env,
+    ...(from.runtime ? { runtime: from.runtime } : {}),
+    ...(url ? { url } : {}),
+    ...(domain ? { domain } : {}),
+    ...(from.lifecycle ? { lifecycle: from.lifecycle } : {}),
+  };
+}
+
 // ── records ────────────────────────────────────────────────────────────────
 
 /** One line of `_pr-envs/records.jsonl`: an apply, or a teardown. */
@@ -186,6 +221,12 @@ export interface PrEnvRecord {
   commit: string;
   /** The components applied (up) or the lexicons torn down (down). */
   components: string[];
+  /**
+   * Up (#4330): where each component's copy lives, by component, as the
+   * adapter that applied it says (a Terraform root's suffixed state key).
+   * A teardown adapter reads it back from the live environment.
+   */
+  locations?: Record<string, string>;
   /** The change-set digest applied; empty for a teardown. */
   planDigest: string;
   /** `incomplete`: a teardown that left something, so the environment stays live and the sweep tries again. */
@@ -229,6 +270,8 @@ export interface LivePrEnvironment {
   commit: string;
   /** Every component an apply of it ever touched. */
   components: string[];
+  /** Where each component's copy lives, merged over every up (#4330). */
+  locations?: Record<string, string>;
   applied: string;
   expiresAt: string;
   /** Its last teardown left something, so the sweep tries again. */
@@ -245,6 +288,7 @@ export function livePrEnvironments(records: readonly PrEnvRecord[]): Map<string,
   for (const r of records) {
     if (r.kind === "up") {
       const was = live.get(r.env);
+      const locations = { ...(was?.locations ?? {}), ...(r.locations ?? {}) };
       live.set(r.env, {
         pr: r.pr,
         env: r.env,
@@ -253,6 +297,7 @@ export function livePrEnvironments(records: readonly PrEnvRecord[]): Map<string,
         marker: { ...r.marker },
         commit: r.commit,
         components: [...new Set([...(was?.components ?? []), ...r.components])],
+        ...(Object.keys(locations).length > 0 ? { locations } : {}),
         applied: r.timestamp,
         expiresAt: r.expiresAt ?? r.timestamp,
       });
@@ -302,12 +347,61 @@ export function ownedEntries(plan: TeardownPlan, marker: OwnershipMarker): { pla
   return { plan: { ...plan, entries: plan.entries.filter(owns) }, dropped: plan.entries.filter((e) => !owns(e)) };
 }
 
+/**
+ * A teardown a product supplies for what no lexicon tears down (#4330), such
+ * as a Terraform root's copy under a suffixed state key: chant has no
+ * Terraform runner, so terragucci supplies this. It takes part in the same
+ * two halves a lexicon's teardown does (`../lifecycle/teardown.ts`): `owned`
+ * names what the environment owns, each with the marker read back from it,
+ * and `teardown` deletes the candidates chant hands back. Every candidate
+ * whose marker is not exactly `{ stack, env: "pr-<n>" }` is dropped before
+ * `teardown` sees it, and a candidate it says nothing about counts as failed.
+ */
+export interface PrEnvTeardownAdapter {
+  /** The name outcomes are attributed to, as a lexicon's are. */
+  name: string;
+  /**
+   * The lexicons this adapter tears down in place of (`terraform`). Their own
+   * teardown is left out, so a lexicon with no teardown execution does not
+   * leave the environment incomplete when the adapter covers it.
+   */
+  lexicons?: string[];
+  /** What the environment owns: candidates with their read-back markers, and what could not be read. */
+  owned(input: PrEnvTeardownAdapterInput): Promise<TeardownEnumeration>;
+  /** Delete the candidates: one outcome per candidate, keyed by name. */
+  teardown(input: PrEnvTeardownAdapterInput & { candidates: TeardownCandidate[] }): Promise<TeardownExecution>;
+}
+
+/** What a {@link PrEnvTeardownAdapter} is told about the environment. */
+export interface PrEnvTeardownAdapterInput {
+  /** `pr-<n>`. */
+  environment: string;
+  /** The marker everything is selected on. */
+  marker: OwnershipMarker;
+  /** The environment as its records say it stands: the commit last applied, its components and their locations. */
+  live: LivePrEnvironment;
+}
+
+/** An adapter in the shape `planTeardown` and `executeTeardown` call: a lexicon with only its two teardown halves. */
+function adapterLexicon(adapter: PrEnvTeardownAdapter, live: LivePrEnvironment): ObservationLexicon {
+  const shaped: Pick<ObservationLexicon, "name" | "teardownOwned" | "executeTeardown"> = {
+    name: adapter.name,
+    teardownOwned: (o) => adapter.owned({ environment: o.environment, marker: o.marker, live }),
+    executeTeardown: (o) => adapter.teardown({ environment: o.environment, marker: o.marker, live, candidates: o.candidates }),
+  };
+  return shaped as ObservationLexicon;
+}
+
 /** What {@link tearDownPrEnvironment} needs. */
 export interface PrEnvTeardownInput {
   pr: number;
   live: LivePrEnvironment;
-  config: ChantConfig;
-  plugins: ObservationLexicon[];
+  /** The project's config, for its environments and stacks. Absent: a product with no chant.config.ts, whose adapters do the teardown. */
+  config?: ChantConfig;
+  /** The lexicons whose teardown runs. Default none. */
+  plugins?: ObservationLexicon[];
+  /** Teardowns a product supplies (#4330), run after the lexicons'. */
+  adapters?: PrEnvTeardownAdapter[];
   warn?: (message: string) => void;
 }
 
@@ -316,18 +410,30 @@ export interface PrEnvTeardownInput {
  * before any read when {@link teardownRefusal} says so; otherwise the live
  * resources under the record's marker are planned, every entry whose marker
  * is not exactly `{ stack, env: "pr-<n>" }` is dropped ({@link ownedEntries}),
- * and only the rest go to each lexicon's teardown. The endpoint is the one
- * the environment was applied at: its own `pr-*` entry's, else the template's.
+ * and only the rest go to each lexicon's or adapter's teardown. The endpoint
+ * is the one the environment was applied at: its own `pr-*` entry's, else the
+ * template's. A lexicon an adapter covers (`lexicons`) is left out.
  */
 export async function tearDownPrEnvironment(input: PrEnvTeardownInput): Promise<{ refusal: string } | { report: TeardownReport; dropped: number; marker: { stack: string; env: string } }> {
-  const { pr, live, config, plugins } = input;
+  const { pr, live } = input;
+  const config = input.config ?? {};
   const refusal = teardownRefusal(pr, live, config.environments);
   if (refusal) return { refusal };
+  const adapters = input.adapters ?? [];
+  const covered = new Set(adapters.flatMap((a) => a.lexicons ?? []));
+  const names = new Set<string>();
+  for (const a of adapters) {
+    if (names.has(a.name)) return { refusal: `two teardown adapters are named ${a.name}, so their outcomes could not be told apart; nothing was torn down` };
+    names.add(a.name);
+  }
+  const lexicons = (input.plugins ?? []).filter((x) => !covered.has(x.name));
+  if (lexicons.some((x) => names.has(x.name))) return { refusal: `a teardown adapter shares its name with a lexicon (${[...names].filter((n) => lexicons.some((x) => x.name === n)).join(", ")}), so their outcomes could not be told apart; nothing was torn down` };
   const env = prEnvironmentName(pr);
   const marker = { stack: live.marker.stack, env };
   const endpoint = environmentEndpoint(config.environments, env) ?? environmentEndpoint(config.environments, live.template);
-  const applied = applyLiveEndpoint(endpoint ? [{ name: env, endpoint }] : [], env, plugins.filter((x) => x.teardownOwned || x.describeResources || x.executeTeardown));
+  const applied = applyLiveEndpoint(endpoint ? [{ name: env, endpoint }] : [], env, lexicons.filter((x) => x.teardownOwned || x.describeResources || x.executeTeardown));
   if (applied.notice) input.warn?.(applied.notice);
+  const plugins = [...lexicons, ...adapters.map((a) => adapterLexicon(a, live))];
   const deployedStacks = (config.stacks ?? []).map((s) => ({ name: s.name, ...(s.region ? { region: s.region } : {}) }));
   try {
     const planned = await planTeardown({ environment: env, stack: marker.stack, plugins, ...(deployedStacks.length > 0 ? { deployedStacks } : {}) });
@@ -405,6 +511,7 @@ export function acceptHandedRecord(raw: unknown, check: HandedRecordCheck): { re
       marker: { stack: r.marker.stack, env },
       commit: check.head,
       components: [...r.components],
+      ...(handedLocations(r.locations) ? { locations: handedLocations(r.locations)! } : {}),
       planDigest: typeof r.planDigest === "string" ? r.planDigest : "",
       result: r.result,
       by: check.by,
@@ -417,6 +524,21 @@ export function acceptHandedRecord(raw: unknown, check: HandedRecordCheck): { re
   };
 }
 
+/** A handed-on report row's site, kept only as its three strings. */
+function handedSite(raw: unknown): PrEnvReportRow["site"] | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const r = raw as Record<string, unknown>;
+  const site = Object.fromEntries((["runtime", "url", "domain"] as const).filter((k) => typeof r[k] === "string").map((k) => [k, r[k] as string]));
+  return Object.keys(site).length > 0 ? site : undefined;
+}
+
+/** A handed-on record's locations, kept only as a map of strings to strings. */
+function handedLocations(raw: unknown): Record<string, string> | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+  const out = Object.fromEntries(Object.entries(raw as Record<string, unknown>).filter((e): e is [string, string] => typeof e[1] === "string"));
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /**
  * The report `pr-env up` handed on, checked as data before the post job
  * renders a note from it: an `up` report for this pull request's `pr-<n>`.
@@ -445,7 +567,16 @@ export function handedPrEnvReport(raw: unknown, check: { pr: number; head: strin
       status: r.status,
       ...(typeof r.message === "string" ? { message: r.message } : {}),
       ...(typeof r.endpoint === "string" ? { endpoint: r.endpoint } : {}),
-      components: (Array.isArray(r.components) ? r.components : []).map((c) => ({ component: str(c?.component), status: str(c?.status), create: num(c?.create), update: num(c?.update), replace: num(c?.replace), delete: num(c?.delete) })),
+      components: (Array.isArray(r.components) ? r.components : []).map((c) => ({
+        component: str(c?.component),
+        status: str(c?.status),
+        create: num(c?.create),
+        update: num(c?.update),
+        replace: num(c?.replace),
+        delete: num(c?.delete),
+        ...(typeof c?.location === "string" ? { location: c.location } : {}),
+        ...(handedSite(c?.site) ? { site: handedSite(c?.site)! } : {}),
+      })),
       ...(Array.isArray(r.approvedBy) ? { approvedBy: r.approvedBy.filter((a): a is string => typeof a === "string") } : {}),
     },
   };
@@ -453,6 +584,20 @@ export function handedPrEnvReport(raw: unknown, check: { pr: number; head: strin
 
 // ── the note ───────────────────────────────────────────────────────────────
 
+/** One component's row in the report and the note. */
+export interface PrEnvReportRow {
+  component: string;
+  status: string;
+  create: number;
+  update: number;
+  replace: number;
+  delete: number;
+  /** Where its copy lives, as the adapter says (#4330). */
+  location?: string;
+  /** Its site in pr-<n>: the runtime, URL and domain carried over from the template's (#4330, {@link prEnvironmentSite}). */
+  site?: { runtime?: string; url?: string; domain?: string };
+}
+
 /** What one `pr-env up` or `down` run came to, as `pr-env.json` holds it. */
 export interface PrEnvReport {
   stage: "up" | "down";
@@ -467,7 +612,7 @@ export interface PrEnvReport {
   status: "applied" | "nothing" | "waiting" | "changed" | "plan-failed" | "failed" | "refused" | "destroyed" | "incomplete" | "absent";
   message?: string;
   endpoint?: string;
-  components: Array<{ component: string; status: string; create: number; update: number; replace: number; delete: number }>;
+  components: PrEnvReportRow[];
   approvedBy?: string[];
   expiresAt?: string;
   outcomes?: PrEnvRecord["outcomes"];
@@ -505,8 +650,11 @@ export function renderPrEnvNote(r: PrEnvReport, approver = "<you>"): string {
   }
   if (r.message) out.push("", `> ${r.message.split("\n").join("\n> ")}`);
   if (r.components.length > 0) {
-    out.push("", "| Component | Status | Create | Update | Replace | Delete |", "|---|---|---:|---:|---:|---:|");
-    for (const c of r.components) out.push(`| ${code(c.component)} | ${c.status} | ${c.create} | ${c.update} | ${c.replace} | ${c.delete} |`);
+    // #4330: a Where column when a row has a URL or a location, as code: env-up ran the change's code, so the post job does not link it.
+    const at = (c: PrEnvReportRow): string | undefined => c.site?.url ?? c.site?.domain ?? c.location;
+    const where = r.components.some((c) => at(c));
+    out.push("", `| Component | Status | Create | Update | Replace | Delete |${where ? " Where |" : ""}`, `|---|---|---:|---:|---:|---:|${where ? "---|" : ""}`);
+    for (const c of r.components) out.push(`| ${code(c.component)} | ${c.status} | ${c.create} | ${c.update} | ${c.replace} | ${c.delete} |${where ? ` ${at(c) ? code(at(c)!) : ""} |` : ""}`);
   }
   if (r.digest) out.push("", `Plan digest: ${code(r.digest)}${r.approvedBy?.length ? `, approved by ${r.approvedBy.map(code).join(", ")}` : ""}`);
   out.push("", `${code(r.env)} is not a release target: releases come from green commits.`);

package/src/components/pr-pipeline.ts

@@ -89,7 +89,7 @@ import { EMPTY_TREE_SHA } from "./changed-files";
 import { layerWaves } from "../gated-waves";
 import type { DriverComponent } from "./driver";
 import type { GatedWavePipelineOptions } from "./gated-wave-pipeline";
-import type { PipelineCloudIdentity } from "../ci-identity";
+import type { CloudTradeSpec, PipelineCloudIdentity } from "../ci-identity";
 
 /** The variable `chant ci run` reads its runner key from (`RUNNER_KEY_ENV` in ../workspace/ci-green.ts). */
 const RUNNER_KEY_ENV = "CHANT_RUNNER_KEY";
@@ -211,6 +211,15 @@ export interface PrLoopPipelineOptions {
    * ({@link prEnvJobs}). Set from `--pr-env` beside `--pr-loop`. Default false.
    */
   prEnvironment?: boolean;
+  /**
+   * The cloud identity a pull request environment's jobs take (#4330), from
+   * `ci.identity.cloud` (`resolvePrEnvCloudIdentity` in ../ci-identity.ts):
+   * the apply identity of a rule that names the pull request environments.
+   * env-up, env-down and env-sweep trade their OIDC token for it before the
+   * checkout, and env-up's later steps start without the token variables.
+   * Absent: they request no OIDC token.
+   */
+  prEnvIdentity?: CloudTradeSpec;
 }
 
 /** One job's command and the forge values it reads, as environment variables for its step. */

package/src/config-environments.ts

@@ -0,0 +1,133 @@
+/**
+ * The pure helpers over a loaded config's `environments` and `ownership`:
+ * names, patterns, endpoints and the ownership stack. ./config.ts re-exports
+ * them. They import nothing at runtime, so ./components/pr-environment.ts and
+ * ./live-endpoint.ts use them without bundling the config loader.
+ */
+
+import type { ChantConfig } from "./config";
+
+/**
+ * One project-declared environment (chant #1166). Historically always a bare
+ * name (`"floci"`); an entry can now instead carry the endpoint that
+ * environment's `--live` reads should target (`{ name: "floci", endpoint:
+ * "http://localhost:4566" }`), so a project pointed at a local emulator is
+ * self-sufficient — no ambient `AWS_ENDPOINT_URL` export required to avoid
+ * 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; canary?: boolean };
+
+/**
+ * `ownership.env`: a literal environment identity, or a reference to a
+ * declared build parameter whose resolved value becomes the identity (#1396).
+ */
+export type OwnershipEnv = string | { param: string };
+
+/** The declared name of one `environments` entry, whichever form it takes. */
+export function environmentName(entry: EnvironmentDeclaration): string {
+  return typeof entry === "string" ? entry : entry.name;
+}
+
+/**
+ * Every declared environment's name, in `environments` order. `undefined` in,
+ * `undefined` out — mirrors the field itself being optional, so a caller that
+ * already writes `config.environments?.something` can keep doing so:
+ * `environmentNames(config.environments)?.includes(name)`.
+ */
+export function environmentNames(environments: EnvironmentDeclaration[] | undefined): string[] | undefined {
+  return environments?.map(environmentName);
+}
+
+/**
+ * Whether a declared environment name is a glob pattern rather than a literal
+ * (#1221) — it contains at least one `*`.
+ */
+export function isEnvironmentPattern(declaredName: string): boolean {
+  return declaredName.includes("*");
+}
+
+/**
+ * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
+ * characters (possibly empty); everything else matches itself. Deliberately
+ * the whole surface — no `?`, no character classes, no regex. A pattern with
+ * no `*` degenerates to string equality.
+ */
+export function matchesEnvironmentPattern(pattern: string, name: string): boolean {
+  const parts = pattern.split("*");
+  if (parts.length === 1) return pattern === name;
+  const first = parts[0];
+  const last = parts[parts.length - 1];
+  if (!name.startsWith(first)) return false;
+  let cursor = first.length;
+  for (let i = 1; i < parts.length - 1; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    const at = name.indexOf(part, cursor);
+    if (at === -1) return false;
+    cursor = at + part.length;
+  }
+  return name.length - cursor >= last.length && name.endsWith(last);
+}
+
+/**
+ * Environment-membership test (#1221): is `name` covered by this project's
+ * declared `environments`? A literal entry matches by equality; an entry
+ * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
+ * Literals are checked first across the whole list, then patterns — so a
+ * name that is declared outright never depends on pattern order. `undefined`
+ * / empty `environments` returns `false`; callers that treat "no declared
+ * environments" as "anything goes" (e.g. {@link unknownEnvError} in
+ * `./env.ts`) guard that case themselves.
+ */
+export function matchesDeclaredEnvironment(
+  environments: EnvironmentDeclaration[] | undefined,
+  name: string,
+): boolean {
+  const names = environmentNames(environments) ?? [];
+  if (names.includes(name)) return true;
+  return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
+}
+
+/**
+ * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
+ * entry, an entry with no `endpoint` set, or a name this project doesn't
+ * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
+ * it injects this into the ambient env var each observing lexicon's CLI
+ * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
+ * ambient always wins.
+ *
+ * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
+ * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
+ * entry always wins over a pattern — declaring `pr-special` alongside
+ * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
+ */
+export function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined {
+  const found =
+    environments?.find((e) => environmentName(e) === name) ??
+    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+  return found && typeof found !== "string" ? found.endpoint : undefined;
+}
+
+/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
+export function isOwnershipParamRef(env: OwnershipEnv | undefined): env is { param: string } {
+  return typeof env === "object" && env !== null && typeof env.param === "string";
+}
+
+/**
+ * The ownership stack identity alone — `ownership.stack` when marking is on
+ * (no `stack`, or `enabled: false`, means off). For callers that need the
+ * stack and nothing else (a field manager, a prune selector) and so have no
+ * build parameters to resolve `env` against.
+ */
+export function resolveOwnershipStack(config: Pick<ChantConfig, "ownership">): string | undefined {
+  const o = config.ownership;
+  if (!o || !o.stack || o.enabled === false) return undefined;
+  return o.stack;
+}

package/src/config.ts

@@ -14,113 +14,22 @@ import { lexiconNames, pathLexiconRoot, registerLexiconDeclarations, type Lexico
 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
- * name (`"floci"`); an entry can now instead carry the endpoint that
- * environment's `--live` reads should target (`{ name: "floci", endpoint:
- * "http://localhost:4566" }`), so a project pointed at a local emulator is
- * self-sufficient — no ambient `AWS_ENDPOINT_URL` export required to avoid
- * 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; canary?: boolean };
-
-/**
- * `ownership.env`: a literal environment identity, or a reference to a
- * declared build parameter whose resolved value becomes the identity (#1396).
- */
-export type OwnershipEnv = string | { param: string };
-
-/** The declared name of one `environments` entry, whichever form it takes. */
-export function environmentName(entry: EnvironmentDeclaration): string {
-  return typeof entry === "string" ? entry : entry.name;
-}
-
-/**
- * Every declared environment's name, in `environments` order. `undefined` in,
- * `undefined` out — mirrors the field itself being optional, so a caller that
- * already writes `config.environments?.something` can keep doing so:
- * `environmentNames(config.environments)?.includes(name)`.
- */
-export function environmentNames(environments: EnvironmentDeclaration[] | undefined): string[] | undefined {
-  return environments?.map(environmentName);
-}
-
-/**
- * Whether a declared environment name is a glob pattern rather than a literal
- * (#1221) — it contains at least one `*`.
- */
-export function isEnvironmentPattern(declaredName: string): boolean {
-  return declaredName.includes("*");
-}
-
-/**
- * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
- * characters (possibly empty); everything else matches itself. Deliberately
- * the whole surface — no `?`, no character classes, no regex. A pattern with
- * no `*` degenerates to string equality.
- */
-export function matchesEnvironmentPattern(pattern: string, name: string): boolean {
-  const parts = pattern.split("*");
-  if (parts.length === 1) return pattern === name;
-  const first = parts[0];
-  const last = parts[parts.length - 1];
-  if (!name.startsWith(first)) return false;
-  let cursor = first.length;
-  for (let i = 1; i < parts.length - 1; i++) {
-    const part = parts[i];
-    if (part === "") continue;
-    const at = name.indexOf(part, cursor);
-    if (at === -1) return false;
-    cursor = at + part.length;
-  }
-  return name.length - cursor >= last.length && name.endsWith(last);
-}
-
-/**
- * Environment-membership test (#1221): is `name` covered by this project's
- * declared `environments`? A literal entry matches by equality; an entry
- * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
- * Literals are checked first across the whole list, then patterns — so a
- * name that is declared outright never depends on pattern order. `undefined`
- * / empty `environments` returns `false`; callers that treat "no declared
- * environments" as "anything goes" (e.g. {@link unknownEnvError} in
- * `./env.ts`) guard that case themselves.
- */
-export function matchesDeclaredEnvironment(
-  environments: EnvironmentDeclaration[] | undefined,
-  name: string,
-): boolean {
-  const names = environmentNames(environments) ?? [];
-  if (names.includes(name)) return true;
-  return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
-}
-
-/**
- * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
- * entry, an entry with no `endpoint` set, or a name this project doesn't
- * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
- * it injects this into the ambient env var each observing lexicon's CLI
- * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
- * ambient always wins.
- *
- * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
- * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
- * entry always wins over a pattern — declaring `pr-special` alongside
- * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
- */
-export function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined {
-  const found =
-    environments?.find((e) => environmentName(e) === name) ??
-    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
-  return found && typeof found !== "string" ? found.endpoint : undefined;
-}
+// The environment and ownership helpers that read a config already loaded
+// live in ./config-environments.ts, which loads nothing, so a bundle that
+// needs only them stays clear of the loader below (#4356 follow-up).
+export {
+  environmentEndpoint,
+  environmentName,
+  environmentNames,
+  isEnvironmentPattern,
+  isOwnershipParamRef,
+  matchesDeclaredEnvironment,
+  matchesEnvironmentPattern,
+  resolveOwnershipStack,
+  type EnvironmentDeclaration,
+  type OwnershipEnv,
+} from "./config-environments";
+import { isOwnershipParamRef, resolveOwnershipStack, type EnvironmentDeclaration, type OwnershipEnv } from "./config-environments";
 
 /**
  * Zod schema for ChantConfig validation.
@@ -157,6 +66,10 @@ export const ChantConfigSchema = z.object({
   build: z.object({
     fold: z.boolean().optional(),
   }).optional(),
+  // Strict like `run`: a misspelt `lint` would leave the gate on with nothing said.
+  graph: z.object({
+    lint: z.enum(["gate", "report"]).optional(),
+  }).strict().optional(),
   buildParams: z.record(
     z.string(),
     z.object({
@@ -299,6 +212,23 @@ export interface ChantConfig {
   /** Lint configuration (rules, extends, overrides, plugins) */
   lint?: LintConfig;
 
+  /**
+   * How `chant graph` treats lint errors (INTENTIUS/behold#919).
+   *
+   * `"gate"` (the default) refuses to emit the entity graph for source that
+   * fails `chant lint`: the graph stands for source chant will build.
+   * `"report"` emits it anyway and carries every lint finding on the IR's
+   * `meta.lint`, for a project that only reads source it did not author. The
+   * reader project `chant workspace graph` writes for a terraform or choudoufu
+   * member sets it, and so does behold's scratch project for a bare Terraform
+   * folder: an error-severity finding there describes the estate, and the
+   * person needs the picture to look at it. A chant older than the key
+   * ignores it and gates as before.
+   */
+  graph?: {
+    lint?: "gate" | "report";
+  };
+
   /**
    * Telemetry attribution (#2558, D22): lexicons that declare workloads stamp
    * resource attributes (`chant.workspace`, `chant.member`, `chant.decl`,
@@ -764,23 +694,6 @@ function warnIfFragmentShadowsProjectConfig(configPath: string): void {
 /** Top-level keys that make a config a *project* config rather than a lint fragment. */
 const PROJECT_CONFIG_KEYS = new Set(Object.keys(ChantConfigSchema.shape).filter((k) => k !== "lint"));
 
-/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
-export function isOwnershipParamRef(env: OwnershipEnv | undefined): env is { param: string } {
-  return typeof env === "object" && env !== null && typeof env.param === "string";
-}
-
-/**
- * The ownership stack identity alone — `ownership.stack` when marking is on
- * (no `stack`, or `enabled: false`, means off). For callers that need the
- * stack and nothing else (a field manager, a prune selector) and so have no
- * build parameters to resolve `env` against.
- */
-export function resolveOwnershipStack(config: ChantConfig): string | undefined {
-  const o = config.ownership;
-  if (!o || !o.stack || o.enabled === false) return undefined;
-  return o.stack;
-}
-
 /**
  * Resolve the `env` half of the ownership marker (#1396). A literal is
  * returned as-is. A `{ param }` reference is looked up in this build's resolved