@intentius/chant 0.44.14 → 0.46.0

package/src/components/capability-plugin.ts

@@ -44,7 +44,7 @@ import type { Capability } from "./capability";
 export interface CapabilityManifest {
   /** Package/plugin name (e.g. "aws", "gcp"), not a capability `kind`. */
   name: string;
-  /** Plugin package version (semver). */
+  /** The plugin package's version (semver), read from its `package.json`. */
   version: string;
   /** Minimum/compatible chant core version, checked the same way as `LexiconManifest.chantVersion` (see ../lexicon-manifest.ts's `checkVersionCompatibility`). */
   chantVersion?: string;
@@ -69,7 +69,13 @@ export interface CapabilityPlugin {
   /** Human-readable plugin/package name (e.g. "aws", "gcp"), not a capability `kind`. */
   readonly name: string;
 
-  /** Plugin package version (semver), mirrors `LexiconManifest.version`. */
+  /**
+   * The plugin package's version (semver), read from its `package.json`
+   * (chant #1505). Mirrors `LexiconManifest.version`. Informational — nothing
+   * gates on it. The built-in plugins expose it as a lazy getter over
+   * `ownPackageVersion`, so the read happens on first access and never at
+   * module scope.
+   */
   readonly version: string;
 
   /** Return every `Capability` this plugin contributes, keyed for registration by its own `kind`. */
@@ -124,8 +130,23 @@ export function isCapabilityPlugin(value: unknown): value is CapabilityPlugin {
  *
  * Returns `"0.0.0"` when no versioned `package.json` is found — a visible
  * sentinel rather than a guess; nothing gates on the field.
+ *
+ * Call it lazily (from a `get version()` accessor, as the built-in plugins
+ * do), not at module scope: the read touches the filesystem, and a plugin
+ * module must stay importable where `fs` is absent (workerd, chant #1081).
+ * The result is cached per module URL, so the walk happens once.
  */
 export function ownPackageVersion(moduleUrl: string): string {
+  const cached = ownVersionCache.get(moduleUrl);
+  if (cached !== undefined) return cached;
+  const found = findPackageVersion(moduleUrl);
+  ownVersionCache.set(moduleUrl, found);
+  return found;
+}
+
+const ownVersionCache = new Map<string, string>();
+
+function findPackageVersion(moduleUrl: string): string {
   let dir = dirname(fileURLToPath(moduleUrl));
   for (;;) {
     try {

package/src/components/driver.test.ts

@@ -18,6 +18,8 @@ import {
   DriverGateUnsupportedError,
   DriverRunFailure,
   UnknownDependencyError,
+  accumulateComponentOutputs,
+  collectComponentOutputs,
   resolveComponentGraph,
   resolveWiring,
   runComponentDeploy,
@@ -411,6 +413,49 @@ describe("runComponentDeploy — output wiring", () => {
   });
 });
 
+describe("collectComponentOutputs / accumulateComponentOutputs — the shared accumulator (#700)", () => {
+  // Exported so the durable path's `accumulateComponentOutputs` activity
+  // (lexicons/temporal/src/component-op/activities.ts) captures outputs via
+  // the same function `runComponentDeploy` does — the accumulation twin of
+  // the already-shared `resolveStepInput`.
+  const phaseOutputs = {
+    Apply: { stackStatus: "CREATE_COMPLETE", outputs: { ClusterArn: "arn:cluster", ApiRepoUri: "repo" } },
+    Publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
+  };
+
+  it("namespaces publish outputs under `publish` and merges stack outputs at the top level", () => {
+    expect(collectComponentOutputs(phaseOutputs)).toEqual({
+      ClusterArn: "arn:cluster",
+      ApiRepoUri: "repo",
+      publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
+    });
+  });
+
+  it("returns undefined when no phase output looks like a publish or stack result", () => {
+    expect(collectComponentOutputs({ Verify: { ok: true } })).toBeUndefined();
+  });
+
+  it("records under the component name, merging over a seeded entry, and returns the map", () => {
+    const seeded = { "shared-alb": { Seeded: "keep" }, other: { x: 1 } };
+    const out = accumulateComponentOutputs(seeded, "shared-alb", phaseOutputs);
+    expect(out).toBe(seeded);
+    expect(out["shared-alb"]).toEqual({
+      Seeded: "keep",
+      ClusterArn: "arn:cluster",
+      ApiRepoUri: "repo",
+      publish: { uri: "repo@sha256:abc", digest: "sha256:abc" },
+    });
+    expect(out.other).toEqual({ x: 1 });
+    // Plain data throughout — survives the Temporal activity JSON boundary unchanged.
+    expect(JSON.parse(JSON.stringify(out))).toEqual(out);
+  });
+
+  it("is a no-op when the component exposed nothing", () => {
+    const map = { other: { x: 1 } };
+    expect(accumulateComponentOutputs(map, "svc", { Verify: { ok: true } })).toEqual({ other: { x: 1 } });
+  });
+});
+
 describe("runInterpretDriver — end to end", () => {
   it("runs a producer before its consumer and threads env/vars into every capability call", async () => {
     const registry = new CapabilityRegistry();

package/src/components/driver.ts

@@ -603,37 +603,77 @@ export async function runComponentDeploy(
     return { component: component.name, ok: false, records };
   }
 
-  // Publish-family outputs (publish-image / publish-artifact / load-image-on-host all
-  // return at least one of uri/digest/key — see ../verbs/publish.ts) become this
-  // component's `@<name>.publish.*` for downstream cross-component references.
-  const publishOutput = findPublishOutput(phaseOutputs);
-  if (publishOutput) {
-    componentOutputs[component.name] = { ...componentOutputs[component.name], publish: publishOutput };
-  }
+  // Publish-family and stack outputs become this component's entry in
+  // `componentOutputs` — through the same exported accumulator the durable
+  // path's `accumulateComponentOutputs` activity calls (#700), so local and
+  // Temporal runs can never diverge on what downstream references see.
+  accumulateComponentOutputs(componentOutputs, component.name, phaseOutputs);
+
+  return { component: component.name, ok: true, records };
+}
 
-  // Stack outputs from an apply step (cfn-deploy returns `CfnDeployOutput.outputs`)
-  // become resolvable by downstream components' `stackOutput(<name>, ...)`
-  // references — the cross-stack apply-order integration deferred in #556.
-  // Merged at the top level of this component's entry (peer to `publish`, which
-  // is namespaced under its own key), so `resolveWiring`'s stackOutput branch —
-  // `resolvePath(componentOutputs[stack], name)` — finds each output by name.
-  // Keyed by the component's own name, which by convention is the stack name a
-  // `stackOutput` reference targets (see the pilots and composition-and-wiring.mdx).
+/**
+ * Collect the cross-component outputs one finished component exposes to its
+ * downstream consumers, from every phase output it produced:
+ *
+ *   - publish-family outputs (publish-image / publish-artifact /
+ *     load-image-on-host all return at least one of uri/digest/key — see
+ *     ./verbs/publish.ts) are namespaced under `publish`, so downstream
+ *     `@<name>.publish.*` references resolve;
+ *   - stack outputs from an apply step (cfn-deploy returns
+ *     `CfnDeployOutput.outputs`) are merged at the top level, peer to
+ *     `publish`, so `resolveWiring`'s stackOutput branch —
+ *     `resolvePath(componentOutputs[stack], name)` — finds each output by
+ *     name (the cross-stack apply-order integration deferred in #556, closed
+ *     in #699). The entry is keyed by the component's own name, which by
+ *     convention is the stack name a `stackOutput` reference targets (see the
+ *     pilots and composition-and-wiring.mdx).
+ *
+ * Both halves are generic by output *shape*, not by capability `kind`, keeping
+ * the driver free of per-capability branching. Returns `undefined` when the
+ * component exposed nothing.
+ *
+ * Exported, like `resolveStepInput`, so the durable Temporal path
+ * (lexicons/temporal/src/component-op/activities.ts) accumulates outputs via
+ * this exact function rather than re-deriving it (#700). The resolver and the
+ * accumulator are the two halves of one contract; sharing only the resolver
+ * is how the cross-stack gap #699 closed locally could reopen durably.
+ */
+export function collectComponentOutputs(
+  phaseOutputs: Record<string, Record<string, unknown>>,
+): Record<string, unknown> | undefined {
+  const publishOutput = findPublishOutput(phaseOutputs);
   const stackOutputs = findStackOutputs(phaseOutputs);
-  if (stackOutputs) {
-    componentOutputs[component.name] = { ...componentOutputs[component.name], ...stackOutputs };
-  }
+  if (!publishOutput && !stackOutputs) return undefined;
+  return { ...(stackOutputs ?? {}), ...(publishOutput ? { publish: publishOutput } : {}) };
+}
 
-  return { component: component.name, ok: true, records };
+/**
+ * Record a finished component's outputs (`collectComponentOutputs`) into the
+ * shared `componentOutputs` map under the component's own name, merging over
+ * any seeded entry (`--seed-outputs`, or a durable parent workflow's
+ * thread-through). Mutates and returns `componentOutputs`, so a Temporal
+ * activity can hand the updated map back to its workflow over the JSON
+ * boundary — every value in it is plain activity-result data, so the map is
+ * serializable by construction. A no-op when the component exposed nothing.
+ */
+export function accumulateComponentOutputs(
+  componentOutputs: Record<string, Record<string, unknown>>,
+  componentName: string,
+  phaseOutputs: Record<string, Record<string, unknown>>,
+): Record<string, Record<string, unknown>> {
+  const collected = collectComponentOutputs(phaseOutputs);
+  if (collected) {
+    componentOutputs[componentName] = { ...componentOutputs[componentName], ...collected };
+  }
+  return componentOutputs;
 }
 
 /**
  * Find the output of the last step that looks like a publish result (carries
- * `uri`, `digest`, or `key`) across every phase this component ran, so the
- * driver can populate `@<component>.publish.*` for a downstream consumer.
- * Generic by shape, not by capability `kind` — any capability whose output
- * carries one of these fields is eligible, keeping the driver free of
- * per-capability branching.
+ * `uri`, `digest`, or `key`) across every phase this component ran, so
+ * `collectComponentOutputs` can populate `@<component>.publish.*` for a
+ * downstream consumer.
  */
 function findPublishOutput(
   phaseOutputs: Record<string, Record<string, unknown>>,
@@ -651,9 +691,6 @@ function findPublishOutput(
  * Find the stack `outputs` map produced by an apply-style step (cfn-deploy
  * returns `CfnDeployOutput.outputs`) across every phase this component ran, so
  * a deployed stack's outputs can seed downstream `stackOutput()` resolution.
- * Generic by shape — any output carrying an `outputs` record is eligible —
- * keeping the driver free of per-capability branching, the same way
- * `findPublishOutput` is.
  */
 function findStackOutputs(
   phaseOutputs: Record<string, Record<string, unknown>>,

package/src/components/index.ts

@@ -91,6 +91,8 @@ export {
   resolveComponentGraph,
   resolveWiring,
   resolveStepInput,
+  collectComponentOutputs,
+  accumulateComponentOutputs,
   runComponentDeploy,
   runInterpretDriver,
   DriverGateUnsupportedError,

package/src/components/starter-plugin.ts

@@ -100,8 +100,11 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
 export const starterCapabilityPlugin: CapabilityPlugin = {
   name: "starter",
   // The core package's own version (#1505) — lockstep releases bump it, so a
-  // literal here would go stale every `just release`.
-  version: ownPackageVersion(import.meta.url),
+  // literal here would go stale every `just release`. A getter, so the
+  // package.json read happens on first access rather than at import time.
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
   capabilities: starterCapabilities,
   families: () => STARTER_VERB_FAMILIES,
 };

package/src/config.test.ts

@@ -9,6 +9,8 @@ import {
   environmentName,
   environmentNames,
   environmentEndpoint,
+  matchesEnvironmentPattern,
+  matchesDeclaredEnvironment,
 } from "./config";
 import { writeFileSync, mkdirSync, rmSync } from "fs";
 import { join } from "path";
@@ -336,6 +338,44 @@ describe("environmentName / environmentNames / environmentEndpoint (#1166)", ()
     expect(environmentEndpoint(environments, "unknown")).toBeUndefined(); // not declared at all
     expect(environmentEndpoint(undefined, "floci")).toBeUndefined();
   });
+
+  test("environmentEndpoint resolves through a pattern entry, literal entry winning (#1221)", () => {
+    const environments = [
+      { name: "pr-special", endpoint: "http://special:1111" },
+      { name: "pr-*", endpoint: "http://preview:4566" },
+    ];
+    expect(environmentEndpoint(environments, "pr-42")).toBe("http://preview:4566");
+    expect(environmentEndpoint(environments, "pr-special")).toBe("http://special:1111"); // literal wins over the pattern
+    expect(environmentEndpoint(environments, "prod")).toBeUndefined();
+  });
+});
+
+describe("environment glob patterns (#1221)", () => {
+  test("matchesEnvironmentPattern: a * matches any run of characters, anchored", () => {
+    expect(matchesEnvironmentPattern("pr-*", "pr-42")).toBe(true);
+    expect(matchesEnvironmentPattern("pr-*", "pr-")).toBe(true); // empty run is a run
+    expect(matchesEnvironmentPattern("pr-*", "pr")).toBe(false);
+    expect(matchesEnvironmentPattern("pr-*", "xpr-42")).toBe(false); // anchored at the start
+    expect(matchesEnvironmentPattern("*-preview", "42-preview")).toBe(true);
+    expect(matchesEnvironmentPattern("*-preview", "42-preview-old")).toBe(false); // anchored at the end
+    expect(matchesEnvironmentPattern("test-*-eu", "test-a-eu")).toBe(true);
+    expect(matchesEnvironmentPattern("test-*-eu", "test-a-us")).toBe(false);
+  });
+
+  test("matchesEnvironmentPattern without a * is plain equality", () => {
+    expect(matchesEnvironmentPattern("prod", "prod")).toBe(true);
+    expect(matchesEnvironmentPattern("prod", "prod2")).toBe(false);
+  });
+
+  test("matchesDeclaredEnvironment: literal first, then pattern, across entry forms", () => {
+    const environments = ["dev", "prod", "pr-*", { name: "test-*", endpoint: "http://localhost:4566" }];
+    expect(matchesDeclaredEnvironment(environments, "prod")).toBe(true);
+    expect(matchesDeclaredEnvironment(environments, "pr-42")).toBe(true);
+    expect(matchesDeclaredEnvironment(environments, "test-suite-a")).toBe(true); // object-form pattern entry
+    expect(matchesDeclaredEnvironment(environments, "stage")).toBe(false);
+    expect(matchesDeclaredEnvironment(undefined, "prod")).toBe(false);
+    expect(matchesDeclaredEnvironment([], "prod")).toBe(false);
+  });
 });
 
 describe("resolveFoldEnabled (#1134 — fold is the default build path)", () => {

package/src/config.ts

@@ -7,6 +7,7 @@ import { DEFAULT_SBOM_FORMAT, type SbomFormat } from "./components/verbs/sbom-ge
 import type { Severity } from "./components/verbs/vuln-scan";
 import type { VulnPolicy } from "./components/verbs/vuln-gate";
 import type { BuildParamsConfig } from "./build-params";
+import type { BuildParamProvenance } from "./provenance";
 import { findProjectConfig } from "./project-root";
 import { evaluateProjectConfig } from "./config-sandbox";
 
@@ -22,6 +23,12 @@ import { evaluateProjectConfig } from "./config-sandbox";
  */
 export type EnvironmentDeclaration = string | { name: string; endpoint?: string };
 
+/**
+ * `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;
@@ -37,6 +44,56 @@ export function environmentNames(environments: EnvironmentDeclaration[] | undefi
   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
@@ -44,9 +101,16 @@ export function environmentNames(environments: EnvironmentDeclaration[] | undefi
  * 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);
+  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;
 }
 
@@ -69,7 +133,7 @@ export const ChantConfigSchema = z.object({
   lint: z.record(z.string(), z.unknown()).optional(),
   ownership: z.object({
     stack: z.string().min(1).optional(),
-    env: z.string().min(1).optional(),
+    env: z.union([z.string().min(1), z.object({ param: z.string().min(1) })]).optional(),
     enabled: z.boolean().optional(),
   }).optional(),
   build: z.object({
@@ -193,8 +257,17 @@ export interface ChantConfig {
   ownership?: {
     /** Stack identity stamped onto resources (required to enable stamping). */
     stack?: string;
-    /** Optional environment identity. */
-    env?: string;
+    /**
+     * Optional environment identity. Either a literal, or a reference to one
+     * of this project's declared `buildParams` (`{ param: "env" }`), in which
+     * case the marker takes whatever value that parameter resolves to for the
+     * build — the same value `params.env` reads in source (#1396). A
+     * reference is the only way to make the marker follow `--param env=prod`:
+     * the config is evaluated before build parameters exist, so a literal
+     * computed from `process.env` here and a parameter mapped to the same
+     * variable are two sources of truth that nothing keeps in step.
+     */
+    env?: OwnershipEnv;
     /** Set false to disable stamping even when `stack` is present. */
     enabled?: boolean;
   };
@@ -490,14 +563,92 @@ 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";
+}
+
 /**
- * Resolve the ownership marker to stamp from project config, or undefined when
- * ownership marking is off (no `stack`, or `enabled: false`).
+ * 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 resolveOwnershipMarker(config: ChantConfig): OwnershipMarker | undefined {
+export function resolveOwnershipStack(config: ChantConfig): string | undefined {
   const o = config.ownership;
   if (!o || !o.stack || o.enabled === false) return undefined;
-  return { stack: o.stack, env: o.env };
+  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
+ * build parameters and must find one: a reference to a parameter that was
+ * never declared, or that resolved to no value, throws rather than quietly
+ * stamping a marker without an env — an env-less marker is exactly what lets
+ * a prod deployment go unseen by `--owned` filtering scoped to prod.
+ */
+export function resolveOwnershipEnv(
+  config: ChantConfig,
+  buildParams: readonly BuildParamProvenance[] | undefined,
+): string | undefined {
+  const env = config.ownership?.env;
+  if (!isOwnershipParamRef(env)) return env;
+  const name = env.param;
+  const declared = config.buildParams?.[name];
+  if (!declared) {
+    throw new Error(
+      `ownership.env references build parameter "${name}", which chant.config.ts's buildParams does not declare`,
+    );
+  }
+  const resolved = buildParams?.find((p) => p.name === name);
+  if (!resolved) {
+    throw new Error(
+      `ownership.env references build parameter "${name}", which resolved to no value for this build — pass --param ${name}=<value>${declared.env ? `, set ${declared.env}` : ""}, or give it a default`,
+    );
+  }
+  return String(resolved.value);
+}
+
+/**
+ * Resolve the ownership marker to stamp from project config, or undefined when
+ * ownership marking is off (no `stack`, or `enabled: false`). `buildParams` is
+ * this build's resolved parameters (`resolveBuildParams`'s provenance), which
+ * an `ownership.env: { param }` reference resolves against — see {@link
+ * resolveOwnershipEnv}; it throws when the reference cannot be satisfied.
+ */
+export function resolveOwnershipMarker(
+  config: ChantConfig,
+  buildParams?: readonly BuildParamProvenance[],
+): OwnershipMarker | undefined {
+  const stack = resolveOwnershipStack(config);
+  if (stack === undefined) return undefined;
+  return { stack, env: resolveOwnershipEnv(config, buildParams) };
+}
+
+/**
+ * The divergence #1396 is about, made loud when it cannot be removed: a
+ * project whose `ownership.env` is a literal while it also declares a build
+ * parameter named `env` has two answers to "which environment is this", and
+ * the manifest carries both (the ownership marker from config, the labels
+ * from the parameter). Returns a warning naming both values when they differ;
+ * undefined when there is nothing to say (no literal, no `env` parameter, or
+ * the two agree). The fix is the `{ param: "env" }` reference.
+ */
+export function ownershipEnvDisagreement(
+  config: ChantConfig,
+  buildParams: readonly BuildParamProvenance[] | undefined,
+): string | undefined {
+  const literal = config.ownership?.env;
+  if (typeof literal !== "string") return undefined;
+  if (resolveOwnershipStack(config) === undefined) return undefined;
+  const param = buildParams?.find((p) => p.name === "env");
+  if (!param || String(param.value) === literal) return undefined;
+  return (
+    `ownership.env is "${literal}" but the env build parameter resolved to ${JSON.stringify(param.value)} (${param.source}) — ` +
+    `the ownership marker and params.env disagree about which environment this build is for. ` +
+    `Use ownership: { env: { param: "env" } } so the marker follows the parameter.`
+  );
 }
 
 /**