@intentius/chant 0.44.14 → 0.46.0

package/src/lint/rules/cor021-env-literal-name.ts

@@ -0,0 +1,114 @@
+import * as ts from "typescript";
+import type { LintRule, LintContext, LintDiagnostic, LintProjectConfig } from "../rule";
+
+/**
+ * COR021: Literal Name in a Multi-Environment Project (#1221)
+ *
+ * A project that declares two or more `environments` and binds its ownership
+ * marker to a build parameter (`ownership.env: { param: "env" }`) is built
+ * once per environment — and every physical name that does not vary with
+ * that parameter is the SAME name in every build. The collision is silent at
+ * build time and only surfaces at apply time, when the second environment's
+ * deploy walks over the first's resources.
+ *
+ * This rule warns on the declaration: a name-bearing property (`name`, or a
+ * `*Name` property like `bucketName`) whose value is a bare string literal,
+ * in a project shaped for per-environment builds. The fix is interpolation —
+ * `` `billing-${params.env}-uploads` `` — which folds to a per-environment
+ * literal because build parameters resolve before any file is imported
+ * (#1064). See the resource-naming guide's multi-environment section.
+ *
+ * Deliberately silent when:
+ * - no project config was threaded (a bare unit test, the LSP single-file path),
+ * - the project declares fewer than two environments (nothing to collide),
+ * - `ownership.env` is not param-bound — a literal `ownership.env` (or none)
+ *   means the project is not doing per-environment builds from one source
+ *   tree, so per-instance names are presumably managed another way (the
+ *   layered-config all-in-one pattern hand-names each instance),
+ * - the value is anything other than a bare string literal — a template
+ *   interpolating `params.<name>` is the fixed shape, and other non-literal
+ *   values are EVL territory, not this rule's.
+ */
+
+/** Does this property name carry a physical resource name — `name` or a camelCase `*Name`? */
+function isNameBearingProperty(propName: string): boolean {
+  return propName === "name" || /^[a-z][A-Za-z0-9]*Name$/.test(propName);
+}
+
+/** The property's declared name, for Identifier and string-literal keys; undefined for computed keys. */
+function propertyName(prop: ts.PropertyAssignment): string | undefined {
+  if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) return prop.name.text;
+  return undefined;
+}
+
+/** Whether the rule's preconditions hold: 2+ declared environments and a param-bound ownership.env. */
+function projectIsMultiEnvParamBound(config: LintProjectConfig | undefined): string | undefined {
+  const env = config?.ownership?.env;
+  const paramBound = typeof env === "object" && env !== null && typeof env.param === "string";
+  if (!paramBound) return undefined;
+  if ((config?.environments?.length ?? 0) < 2) return undefined;
+  return env.param;
+}
+
+/** Walk an object literal (nested included, e.g. k8s `metadata: { name }`), flagging literal name-bearing values. */
+function checkObjectLiteral(
+  obj: ts.ObjectLiteralExpression,
+  paramName: string,
+  context: LintContext,
+  diagnostics: LintDiagnostic[],
+): void {
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const name = propertyName(prop);
+    const value = prop.initializer;
+    if (
+      name !== undefined &&
+      isNameBearingProperty(name) &&
+      (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value))
+    ) {
+      const { line, character } = context.sourceFile.getLineAndCharacterOfPosition(
+        value.getStart(context.sourceFile),
+      );
+      diagnostics.push({
+        file: context.filePath,
+        line: line + 1,
+        column: character + 1,
+        ruleId: "COR021",
+        severity: "warning",
+        message:
+          `Literal ${name}: "${value.text}" in a multi-environment project — every environment's build ` +
+          `produces this same physical name, so two deployed environments collide. Interpolate the env ` +
+          `parameter: \`${value.text}-\${params.${paramName}}\` (see the resource-naming guide's ` +
+          `multi-environment section).`,
+      });
+    }
+    if (ts.isObjectLiteralExpression(value)) {
+      checkObjectLiteral(value, paramName, context, diagnostics);
+    }
+  }
+}
+
+function checkNode(node: ts.Node, paramName: string, context: LintContext, diagnostics: LintDiagnostic[]): void {
+  if (ts.isNewExpression(node) && node.arguments && node.arguments.length > 0) {
+    const firstArg = node.arguments[0];
+    if (ts.isObjectLiteralExpression(firstArg)) {
+      checkObjectLiteral(firstArg, paramName, context, diagnostics);
+    }
+  }
+  ts.forEachChild(node, (child) => checkNode(child, paramName, context, diagnostics));
+}
+
+export const cor021EnvLiteralNameRule: LintRule = {
+  id: "COR021",
+  severity: "warning",
+  category: "correctness",
+  description:
+    "In a multi-environment project with a param-bound ownership.env, name-bearing properties should interpolate the env parameter, not hold a bare literal",
+  check(context: LintContext): LintDiagnostic[] {
+    const paramName = projectIsMultiEnvParamBound(context.projectConfig);
+    if (paramName === undefined) return [];
+    const diagnostics: LintDiagnostic[] = [];
+    checkNode(context.sourceFile, paramName, context, diagnostics);
+    return diagnostics;
+  },
+};

package/src/lint/rules/index.ts

@@ -25,6 +25,7 @@ export { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant";
 export { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform";
 export { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 export { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
+export { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
 export { isInsideCompositeFactory } from "./composite-scope";
 
 import { flatDeclarationsRule } from "./flat-declarations";
@@ -48,9 +49,10 @@ import { evl009CompositeNoConstantRule } from "./evl009-composite-no-constant";
 import { evl010CompositeNoTransformRule } from "./evl010-composite-no-transform";
 import { cor017CompositeNameMatchRule } from "./cor017-composite-name-match";
 import { cor018CompositePreferLexiconTypeRule } from "./cor018-composite-prefer-lexicon-type";
+import { cor021EnvLiteralNameRule } from "./cor021-env-literal-name";
 
 /**
- * Load all 21 core lint rules (COR + EVL).
+ * Load all 22 core lint rules (COR + EVL).
  */
 export function loadCoreRules(): LintRule[] {
   return [
@@ -75,5 +77,6 @@ export function loadCoreRules(): LintRule[] {
     evl010CompositeNoTransformRule,
     cor017CompositeNameMatchRule,
     cor018CompositePreferLexiconTypeRule,
+    cor021EnvLiteralNameRule,
   ];
 }

package/src/managed-fields.test.ts

@@ -2,28 +2,16 @@ import { describe, test, expect } from "vitest";
 import {
   K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS,
   k8sListMapOrderKey,
+  K8S_SYSTEM_METADATA_PRUNE_PATTERNS,
   buildOwnershipSets,
-  pruneByOwnership,
-  type OwnershipSets,
 } from "./managed-fields";
-import { normalizeDeepProperties, type DeepNode } from "./deep-observation";
+import { normalizeDeepProperties } from "./deep-observation";
 
 /** The naming scheme both the k8s lexicon (via `@intentius/chant-k8s-client`'s `isChantFieldManager`) and gcp restate use in their own tests. */
 function isChantManager(manager: string | undefined): boolean {
   return !!manager && (manager === "chant" || manager.startsWith("chant:"));
 }
 
-function node(partial: Partial<DeepNode> & Pick<DeepNode, "path" | "pattern">): DeepNode {
-  return {
-    entityType: "Test::Entity",
-    key: partial.pattern,
-    value: undefined,
-    side: "live",
-    counterpart: "unknown",
-    ...partial,
-  };
-}
-
 describe("K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS — the generic Kubernetes object envelope", () => {
   test("covers status and the server-minted metadata fields", () => {
     for (const p of [
@@ -150,36 +138,21 @@ describe("buildOwnershipSets — resolving managedFields against live and declar
   });
 });
 
-describe("pruneByOwnership — the shared three-question rule", () => {
-  const sets: OwnershipSets = {
-    chantOwned: new Set(["metadata.labels.tier"]),
-    foreignOwned: new Set(["spec.replicas", "metadata.annotations.noise"]),
-    foreignContested: new Set(["spec.replicas"]),
-    owners: new Map([
-      ["metadata.labels.tier", "chant"],
-      ["spec.replicas", "hpa-controller"],
-      ["metadata.annotations.noise", "kube-controller-manager"],
-    ]),
-  };
-
-  test("never prunes the declared side", () => {
-    expect(pruneByOwnership(node({ path: "spec.replicas", pattern: "spec.replicas", side: "declared" }), sets)).toBe(false);
-  });
-
-  test("never prunes a chant-owned path", () => {
-    expect(pruneByOwnership(node({ path: "metadata.labels.tier", pattern: "metadata.labels.tier" }), sets)).toBe(false);
-  });
-
-  test("prunes a foreign-owned, uncontested (undeclared) path", () => {
-    expect(pruneByOwnership(node({ path: "metadata.annotations.noise", pattern: "metadata.annotations.noise" }), sets)).toBe(true);
-  });
-
-  test("keeps a foreign-owned, contested (declared) path", () => {
-    expect(pruneByOwnership(node({ path: "spec.replicas", pattern: "spec.replicas" }), sets)).toBe(false);
+describe("K8S_SYSTEM_METADATA_PRUNE_PATTERNS — what the controllers stamp, not what a human labels (#1191)", () => {
+  test("covers client-side apply bookkeeping, the Deployment controller's rollout counters and the controllers' selector labels", () => {
+    for (const p of [
+      "metadata.annotations.kubectl.kubernetes.io/last-applied-configuration",
+      "metadata.annotations.deployment.kubernetes.io/revision",
+      "metadata.labels.pod-template-hash",
+      "metadata.labels.controller-revision-hash",
+    ]) {
+      expect(K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has(p)).toBe(true);
+    }
   });
 
-  test("leaves a path with no ownership information alone (never pruned by this rule)", () => {
-    expect(pruneByOwnership(node({ path: "spec.selector", pattern: "spec.selector" }), sets)).toBe(false);
+  test("an out-of-band user label is not on the list — it has to reach the diff as undeclared", () => {
+    expect(K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has("metadata.labels.team")).toBe(false);
+    expect(K8S_SYSTEM_METADATA_PRUNE_PATTERNS.has("metadata.annotations.kubernetes.io/change-cause")).toBe(false);
   });
 });
 

package/src/managed-fields.ts

@@ -142,17 +142,18 @@ export interface OwnershipSets {
   chantOwned: ReadonlySet<string>;
   /** Paths owned by a manager that is not chant. */
   foreignOwned: ReadonlySet<string>;
-  /** The subset of `foreignOwned` where the declared manifest also sets the path — drift-relevant despite foreign ownership. */
+  /** The subset of `foreignOwned` where the declared manifest also sets the path — a contested field. */
   foreignContested: ReadonlySet<string>;
   /**
    * Path → the name of the manager that owns it (#1189).
    *
-   * The three sets above answer *which category* owns a path, which is all the
-   * prune rule needs. A reader needs the other question — "owned by
-   * `kubectl-client-side-apply`" and "owned by `hpa-controller`" are the same
-   * category and mean very different things to an operator. Last writer wins
-   * where several managers touch one path, matching what the API server itself
-   * reports.
+   * The three sets above answer *which category* owns a path. A reader needs
+   * the other question — "owned by `kubectl-client-side-apply`" and "owned by
+   * `hpa-controller`" are the same category and mean very different things to
+   * an operator. Since chant #1191 no category is pruned from the diff, so
+   * this map is what tells the two apart in the report. Last writer wins
+   * where several managers touch one path, matching what the API server
+   * itself reports.
    */
   owners: ReadonlyMap<string, string>;
 }
@@ -323,25 +324,41 @@ export function buildOwnershipSets(
 }
 
 /**
- * The three-question managed-fields prune rule, as a predicate over a
- * {@link DeepNode} plus one object's precomputed {@link OwnershipSets} —
- * shared by every lexicon layering a per-resource managed-fields prune on
- * top of its own static rules (k8s's `perResourceHooks`, gcp's equivalent):
+ * Well-known metadata the control plane writes on an object regardless of
+ * who applied it — matched on the exact index-erased pattern, like
+ * {@link K8S_OBJECT_ENVELOPE_PRUNE_PATTERNS}, but gated by the caller on
+ * `side === "live" && counterpart === "absent"` so a manifest that *does*
+ * declare one of these (a hand-pinned `change-cause`, say) is still compared.
  *
- * 1. Chant owns the path (any chant manager) → never pruned by this rule.
- * 2. A different manager owns it, chant does not, and it is not declared →
- *    controller-managed noise, pruned.
- * 3. It is declared, regardless of who owns it live → never pruned by this
- *    rule, because chant's source is a statement of intent independent of
- *    which write currently holds the field.
+ * This list is the noise valve that replaced the managed-fields prune
+ * (chant #1191). Until then a foreign-owned, undeclared path was dropped
+ * before the diff ever saw it, which silenced `kubectl label deploy web
+ * team=platform` — the exact console-edit class the `undeclared` drift kind
+ * exists for. Now a foreign-owned path nobody declared is reported as
+ * `undeclared` (with its owner named, #1189) unless the accepted baseline
+ * already carries it — and what remains to subtract statically is only the
+ * handful of annotations and labels Kubernetes' own controllers stamp on
+ * every object of a kind. Widening this set is additive; each entry must be
+ * something *no* human writes out of band.
  *
- * Only applies to the live side — the declared tree carries no managedFields
- * to prune by.
+ * - `kubectl.kubernetes.io/last-applied-configuration` — client-side apply's
+ *   bookkeeping, a JSON copy of whatever was last applied.
+ * - `deployment.kubernetes.io/revision` (+ `revision-history`,
+ *   `desired-replicas`, `max-replicas`) — the Deployment controller's
+ *   rollout counters, written to Deployments and their ReplicaSets.
+ * - `pod-template-hash` / `controller-revision-hash` /
+ *   `statefulset.kubernetes.io/pod-name` — the selector labels the
+ *   ReplicaSet, DaemonSet and StatefulSet controllers add to what they own.
  */
-export function pruneByOwnership(node: DeepNode, sets: OwnershipSets): boolean {
-  if (node.side !== "live") return false;
-  if (sets.chantOwned.has(node.path)) return false;
-  if (!sets.foreignOwned.has(node.path)) return false;
-  if (sets.foreignContested.has(node.path)) return false;
-  return true;
-}
+export const K8S_SYSTEM_METADATA_PRUNE_PATTERNS: ReadonlySet<string> = new Set([
+  "metadata.annotations.kubectl.kubernetes.io/last-applied-configuration",
+  "metadata.annotations.deployment.kubernetes.io/revision",
+  "metadata.annotations.deployment.kubernetes.io/revision-history",
+  "metadata.annotations.deployment.kubernetes.io/desired-replicas",
+  "metadata.annotations.deployment.kubernetes.io/max-replicas",
+  "metadata.labels.pod-template-hash",
+  "metadata.labels.controller-revision-hash",
+  "metadata.labels.statefulset.kubernetes.io/pod-name",
+  "spec.template.metadata.labels.pod-template-hash",
+  "spec.template.metadata.labels.controller-revision-hash",
+]);

package/src/observation.test.ts

@@ -29,7 +29,7 @@ const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
 
 describe("normalizeObservation", () => {
   test("a bare map means 'I looked at everything'", () => {
-    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {}, queried: {} });
+    expect(normalizeObservation({ a: meta() })).toEqual({ resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] });
   });
 
   test("the envelope carries both halves", () => {
@@ -38,11 +38,19 @@ describe("normalizeObservation", () => {
       resources: { a: meta() },
       unobserved: { b: { reason: "read-failed" } },
       queried: {},
+      notes: [],
     });
   });
 
+  test("run-level notes ride the envelope, distinct (#1265)", () => {
+    const value = observation({ a: meta() }, undefined, undefined, ["ownership unknown", "ownership unknown"]);
+    expect(value.notes).toEqual(["ownership unknown", "ownership unknown"]);
+    expect(normalizeObservation(value).notes).toEqual(["ownership unknown"]);
+    expect(observation({}).notes).toBeUndefined();
+  });
+
   test("undefined normalizes to empty maps", () => {
-    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {} });
+    expect(normalizeObservation(undefined)).toEqual({ resources: {}, unobserved: {}, queried: {}, notes: [] });
   });
 
   test("the envelope carries the queried addresses through normalization (#1620)", () => {
@@ -84,25 +92,33 @@ describe("unobservedAll", () => {
 describe("mergeObservations (multi-stack)", () => {
   test("present beats not-observed beats absent", () => {
     const merged = mergeObservations([
-      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } }, queried: {} },
-      { resources: { a: meta() }, unobserved: {}, queried: {} },
+      { resources: {}, unobserved: { a: { reason: "read-failed" }, b: { reason: "no-binding" } }, queried: {}, notes: [] },
+      { resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] },
     ]);
     expect(Object.keys(merged.resources)).toEqual(["a"]);
     expect(Object.keys(merged.unobserved)).toEqual(["b"]);
   });
 
+  test("the same note from four stacks is one note (#1265)", () => {
+    const note = "ownership filter unavailable";
+    const merged = mergeObservations(
+      ["a", "b", "c", "d"].map((k) => ({ resources: { [k]: meta() }, unobserved: {}, queried: {}, notes: [note] })),
+    );
+    expect(merged.notes).toEqual([note]);
+  });
+
   test("an entity nobody looked for in any stack stays absent", () => {
     const merged = mergeObservations([
-      { resources: { a: meta() }, unobserved: {}, queried: {} },
-      { resources: { b: meta() }, unobserved: {}, queried: {} },
+      { resources: { a: meta() }, unobserved: {}, queried: {}, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: {}, notes: [] },
     ]);
     expect(merged.unobserved).toEqual({});
   });
 
   test("queried addresses union across stacks (#1620)", () => {
     const merged = mergeObservations([
-      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" } },
-      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" } },
+      { resources: {}, unobserved: {}, queried: { a: "stack-1/a" }, notes: [] },
+      { resources: { b: meta() }, unobserved: {}, queried: { b: "stack-2/b" }, notes: [] },
     ]);
     expect(merged.queried).toEqual({ a: "stack-1/a", b: "stack-2/b" });
   });

package/src/observation.ts

@@ -112,6 +112,24 @@ export interface ObservationResult {
    * namespace, endpoint or region was read, not the one the resource lives in.
    */
   queried?: Record<string, string>;
+  /**
+   * Notices about the read as a whole, not about any one entity (#1265) —
+   * "the ownership filter could not be applied on this surface" is the
+   * canonical one. A note is a property of the environment or the read path,
+   * so core says each distinct note once per run, after the answer, however
+   * many stacks or lexicons reported it. A lexicon returns it here instead of
+   * printing, so the note cannot land ahead of the rows it qualifies.
+   */
+  notes?: string[];
+  /**
+   * What the deployable unit publishes, keyed by the stack that publishes it
+   * (#1279) — a CloudFormation stack's outputs, for instance. Stack-level, so it
+   * lives here once rather than on every resource: a node's `attributes` are
+   * that resource's own properties, and a VPC that carried the stack's
+   * `expWebIp` beside no `CidrBlock` of its own was answering the wrong
+   * question. Values are already scrubbed of anything that looks secret.
+   */
+  stackExports?: Record<string, Record<string, unknown>>;
 }
 
 /**
@@ -126,6 +144,10 @@ export interface NormalizedObservation {
   unobserved: Record<string, UnobservedEntity>;
   /** Resolved query address per entity name (#1620). Empty when the lexicon reported none. */
   queried: Record<string, string>;
+  /** Run-level notices (#1265), distinct. Empty when the lexicon reported none. */
+  notes: string[];
+  /** Per-stack exports (#1279), keyed by stack name. Absent when the lexicon reported none. */
+  stackExports?: Record<string, Record<string, unknown>>;
 }
 
 /** True when `value` is the versioned {@link ObservationResult} envelope. */
@@ -145,12 +167,16 @@ export function observation(
   resources: Record<string, ResourceMetadata>,
   unobserved?: Record<string, UnobservedEntity>,
   queried?: Record<string, string>,
+  notes?: string[],
+  stackExports?: Record<string, Record<string, unknown>>,
 ): ObservationResult {
   return {
     observation: "v1",
     resources,
     ...(unobserved && Object.keys(unobserved).length > 0 ? { unobserved } : {}),
     ...(queried && Object.keys(queried).length > 0 ? { queried } : {}),
+    ...(notes && notes.length > 0 ? { notes } : {}),
+    ...(stackExports && Object.keys(stackExports).length > 0 ? { stackExports } : {}),
   };
 }
 
@@ -161,11 +187,17 @@ export function observation(
  * {@link unobservedAll} rather than returning nothing.
  */
 export function normalizeObservation(value: DescribeResourcesResult | undefined): NormalizedObservation {
-  if (!value) return { resources: {}, unobserved: {}, queried: {} };
+  if (!value) return { resources: {}, unobserved: {}, queried: {}, notes: [] };
   if (isObservationResult(value)) {
-    return { resources: value.resources ?? {}, unobserved: value.unobserved ?? {}, queried: value.queried ?? {} };
+    return {
+      resources: value.resources ?? {},
+      unobserved: value.unobserved ?? {},
+      queried: value.queried ?? {},
+      notes: [...new Set(value.notes ?? [])],
+      ...(value.stackExports && Object.keys(value.stackExports).length > 0 ? { stackExports: value.stackExports } : {}),
+    };
   }
-  return { resources: value, unobserved: {}, queried: {} };
+  return { resources: value, unobserved: {}, queried: {}, notes: [] };
 }
 
 /**
@@ -205,15 +237,27 @@ export function mergeObservations(parts: Iterable<NormalizedObservation>): Norma
   const resources: Record<string, ResourceMetadata> = {};
   const unobserved: Record<string, UnobservedEntity> = {};
   const queried: Record<string, string> = {};
+  // A note is about the read, not a stack; four stacks saying the same thing
+  // is one note (#1265).
+  const notes = new Set<string>();
+  const stackExports: Record<string, Record<string, unknown>> = {};
   for (const part of parts) {
     Object.assign(resources, part.resources);
     Object.assign(unobserved, part.unobserved);
     Object.assign(queried, part.queried);
+    for (const n of part.notes) notes.add(n);
+    Object.assign(stackExports, part.stackExports ?? {});
   }
   // Present wins: a stack that could not be read does not un-observe a resource
   // another stack returned.
   for (const name of Object.keys(resources)) delete unobserved[name];
-  return { resources, unobserved, queried };
+  return {
+    resources,
+    unobserved,
+    queried,
+    notes: [...notes],
+    ...(Object.keys(stackExports).length > 0 ? { stackExports } : {}),
+  };
 }
 
 /** One-line human phrasing of a reason, for CLI output. */

package/src/op/builders.ts

@@ -137,6 +137,37 @@ export const shell = (
 export const teardown = (path: string): ActivityStep =>
   activity("chantTeardown", { path }, "longInfra");
 
+/**
+ * Tear down one environment's marker-owned resources — the durable form of
+ * `chant lifecycle teardown <env> --yes` (#1222). The activity runs core's
+ * teardown engine in-process: enumerate by ownership marker (this project's
+ * `ownership.stack` + `env`), delete through each lexicon's `executeTeardown`
+ * capability, retry failures once, and fail the step when any candidate is
+ * still failed. Distinct from {@link teardown}, which runs a project's own
+ * `npm run teardown` script.
+ *
+ * The CLI's guards apply unchanged, and a production-like environment name
+ * needs `confirmProd: true` in `opts` — the authored counterpart of
+ * `--confirm-prod`, since an Op never prompts. An ordinary {@link gate} step
+ * placed before this one composes as usual (steps run in authored order), so
+ * a human approval can precede the deletion:
+ *
+ * ```ts
+ * phase("Teardown", [
+ *   gate("approve-teardown", { description: "Release the staging teardown" }),
+ *   envTeardown("staging"),
+ * ]),
+ * ```
+ *
+ * `opts` also accepts `path` (the chant project directory, default the
+ * worker's cwd). Defaults to the `longInfra` profile (override via
+ * `opts.profile`).
+ */
+export const envTeardown = (env: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("envTeardown", { env, ...args }, profile ?? "longInfra");
+};
+
 /**
  * Create a local k3d cluster (vanilla Kubernetes in Docker). Idempotent: skips
  * creation if a cluster of the same name already exists. Defaults to the
@@ -279,8 +310,8 @@ export const azDelete = (templatePath: string, opts?: Record<string, unknown>):
  * Deploy a built CloudFormation template by calling the CloudFormation API
  * directly (create-or-update + poll) — the direct twin of {@link azApply} /
  * {@link gcpApply} for AWS, targeting a local Floci emulator or real AWS by
- * endpoint override. Speaks the CFN API over HTTP rather than shelling `aws`
- * (that path is still `nativeApply({ target: "cloudformation" })`). Provided by
+ * endpoint override. Speaks the CFN API over HTTP rather than shelling `aws` —
+ * `nativeApply({ target: "cloudformation" })` routes here too (#1449). Provided by
  * the aws lexicon; loaded when the project lists `aws`. Defaults to the
  * `longInfra` profile. `opts` requires `stackName`; accepts `endpoint`, `region`,
  * `capabilities`, `timeoutMs`, `intervalMs`.
@@ -297,13 +328,15 @@ export const awsDelete = (templatePath: string, opts?: Record<string, unknown>):
 };
 
 /**
- * Apply chant's built GCP (CNRM) resources directly to the GCS REST API,
+ * Apply chant's built GCP (CNRM) resources directly to their GCP REST APIs,
  * targeting a local floci-gcp emulator or real GCP by endpoint override — the
- * native GCP applier (#706 starter #711), currently handling `StorageBucket`.
- * Defaults to the `longInfra` profile (override via `opts.profile`).
+ * native GCP applier (#706 starter #711). `nativeApply({ target: "gcp" })`
+ * routes here too (#1449). Defaults to the `longInfra` profile (override via
+ * `opts.profile`).
  *
- * `opts` accepts `endpoint` (default `STORAGE_EMULATOR_HOST` env / real GCS) and
- * `project` (default `GOOGLE_CLOUD_PROJECT` env / the CNRM project-id annotation).
+ * `opts` accepts `endpoint` (default `GCP_ENDPOINT_URL` env / each kind's
+ * real-GCP host) and `project` (default `GOOGLE_CLOUD_PROJECT` env / the CNRM
+ * project-id annotation).
  */
 export const gcpApply = (manifestPath: string, opts?: Record<string, unknown>): ActivityStep => {
   const { args, profile } = takeProfile(opts);

package/src/op/index.ts

@@ -1,5 +1,5 @@
 export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, teardown, k3dUp, k3dDown, flociUp, flociDown,
+         gitlabPipeline, lifecycleSnapshot, shell, teardown, envTeardown, k3dUp, k3dDown, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,

package/src/ownership.test.ts

@@ -9,7 +9,12 @@ import {
   OWNERSHIP_MANAGED_BY_VALUE,
   type ChannelKeys,
 } from "./ownership";
-import { resolveOwnershipMarker } from "./config";
+import {
+  resolveOwnershipMarker,
+  resolveOwnershipEnv,
+  resolveOwnershipStack,
+  ownershipEnvDisagreement,
+} from "./config";
 
 // A stand-in for a lexicon-provided convention (e.g. AWS's colon keys), to
 // prove the core helpers are generic over any `ChannelKeys` — the per-provider
@@ -105,3 +110,60 @@ describe("resolveOwnershipMarker (config opt-in)", () => {
     expect(resolveOwnershipMarker({ ownership: { stack: "billing", enabled: false } })).toBeUndefined();
   });
 });
+
+describe("ownership.env as a build-parameter reference (#1396)", () => {
+  const config = {
+    ownership: { stack: "fountain", env: { param: "env" } },
+    buildParams: { env: { type: "string" as const, default: "dev", env: "FOUNTAIN_ENV" } },
+  };
+
+  test("takes the resolved parameter value — --param env=prod drives the marker", () => {
+    expect(resolveOwnershipMarker(config, [{ name: "env", value: "prod", source: "cli" }])).toEqual({
+      stack: "fountain",
+      env: "prod",
+    });
+    expect(resolveOwnershipMarker(config, [{ name: "env", value: "dev", source: "default" }])).toEqual({
+      stack: "fountain",
+      env: "dev",
+    });
+  });
+
+  test("a reference to an undeclared parameter is an error, not an env-less marker", () => {
+    expect(() => resolveOwnershipMarker({ ownership: { stack: "s", env: { param: "env" } } }, [])).toThrow(
+      /does not declare/,
+    );
+  });
+
+  test("a reference to a parameter that resolved to nothing is an error", () => {
+    expect(() => resolveOwnershipMarker(config, [])).toThrow(
+      /resolved to no value.*--param env=<value>.*FOUNTAIN_ENV/,
+    );
+  });
+
+  test("the stack-only resolver needs no parameters", () => {
+    expect(resolveOwnershipStack(config)).toBe("fountain");
+    expect(resolveOwnershipStack({ ownership: { stack: "s", enabled: false } })).toBeUndefined();
+  });
+
+  test("a literal env is returned untouched, with or without parameters", () => {
+    expect(resolveOwnershipEnv({ ownership: { stack: "s", env: "prod" } }, undefined)).toBe("prod");
+    expect(resolveOwnershipEnv({ ownership: { stack: "s" } }, [])).toBeUndefined();
+  });
+
+  test("a literal env disagreeing with an env parameter is reported", () => {
+    const literal = {
+      ownership: { stack: "fountain", env: "dev" },
+      buildParams: { env: { type: "string" as const, default: "dev" } },
+    };
+    expect(ownershipEnvDisagreement(literal, [{ name: "env", value: "dev", source: "default" }])).toBeUndefined();
+    expect(ownershipEnvDisagreement(literal, [{ name: "env", value: "prod", source: "cli" }])).toMatch(
+      /ownership\.env is "dev" but the env build parameter resolved to "prod" \(cli\)/,
+    );
+    // A reference never disagrees — there is one source.
+    expect(ownershipEnvDisagreement(config, [{ name: "env", value: "prod", source: "cli" }])).toBeUndefined();
+    // Marking off — nothing is stamped, nothing to disagree with.
+    expect(
+      ownershipEnvDisagreement({ ownership: { env: "dev" } }, [{ name: "env", value: "prod", source: "cli" }]),
+    ).toBeUndefined();
+  });
+});