@intentius/chant 0.41.0 → 0.41.2

package/src/cli/handlers/lifecycle.ts

@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { commandBuildParams } from "../build-params-cli";
 import { build } from "../../build";
 import { takeSnapshot } from "../../lifecycle/snapshot";
 import { readSnapshot, readSnapshotAt, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, pushLifecycle, snapshotStorageKey, StaleLifecycleBranchError } from "../../lifecycle/git";
@@ -101,6 +102,10 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   // Validate environment against config
   const projectPath = resolve(".");
   const { config } = await loadChantConfig(projectPath);
+  // This invocation's parameters, so the declared side of the comparison is the estate
+  // the caller asked for rather than the parameter defaults (#1483).
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
   const declaredEnvNames = environmentNames(config.environments);
   if (declaredEnvNames && !declaredEnvNames.includes(environment)) {
     console.error(formatError({
@@ -146,7 +151,7 @@ export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number>
   const built: Array<{ target: (typeof targets)[number]; buildResult: Awaited<ReturnType<typeof build>> }> = [];
   for (const target of targets) {
     const label = target.stack ? `stack "${target.stack}"` : "project";
-    const buildResult = await build(target.root, targetSerializers);
+    const buildResult = await build(target.root, targetSerializers, undefined, { buildParams: declaredParams });
     if (buildResult.errors.length > 0) {
       console.error(formatError({ message: `Build failed for ${label} — fix errors before taking a snapshot` }));
       anyHardError = true;
@@ -326,6 +331,10 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
 
   // Fetch previous snapshots once (all stacks share the orphan branch).
   const { config } = await loadChantConfig(resolve("."));
+  // This invocation's parameters, so the declared side of the comparison is the estate
+  // the caller asked for rather than the parameter defaults (#1483).
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
   await fetchLifecycle();
 
   // One target per stack (single-stack projects: exactly one), each built from
@@ -355,7 +364,7 @@ export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
 
   try {
     for (const target of targets) {
-      const buildResult = await build(target.root, targetSerializers);
+      const buildResult = await build(target.root, targetSerializers, undefined, { buildParams: declaredParams });
       if (buildResult.errors.length > 0) {
         const label = target.stack ? `stack "${target.stack}"` : "project";
         console.error(formatError({ message: `Build failed for ${label} — fix errors before diffing` }));
@@ -1021,7 +1030,13 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     : serializers;
 
   const { config } = await loadChantConfig(resolve("."));
-  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
+  // This invocation's parameters, so the declared side of the comparison is the estate
+  // the caller asked for rather than the parameter defaults (#1483).
+  const declaredParams = await commandBuildParams(config.buildParams, args);
+  if (!declaredParams) return 1;
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers, undefined, {
+    buildParams: declaredParams,
+  });
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before planning" }));
     return 1;

package/src/components/capability-plugin.test.ts

@@ -233,3 +233,24 @@ describe("MalformedCapabilityPluginError", () => {
     expect(err.name).toBe("MalformedCapabilityPluginError");
   });
 });
+
+// #1505 — plugin versions track the lockstep release instead of a literal that
+// goes stale on every `just release` (aws shipped "1.0.0" from its extraction;
+// the k8s plugin's authoring-time literal was stale one release later).
+describe("ownPackageVersion (#1505)", () => {
+  test("resolves this module's own package version — core's package.json, exactly", async () => {
+    const { ownPackageVersion } = await import("./capability-plugin");
+    const { readFileSync } = await import("node:fs");
+    const { version } = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+    ) as { version: string };
+    expect(ownPackageVersion(import.meta.url)).toBe(version);
+  });
+
+  test("the starter plugin reports that version, not a literal", async () => {
+    const { starterCapabilityPlugin } = await import("./starter-plugin");
+    const { ownPackageVersion } = await import("./capability-plugin");
+    expect(starterCapabilityPlugin.version).toBe(ownPackageVersion(import.meta.url));
+    expect(starterCapabilityPlugin.version).not.toBe("1.0.0");
+  });
+});

package/src/components/capability-plugin.ts

@@ -28,6 +28,9 @@
  * migration path and the "no behavior change" guarantee.
  */
 
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { Capability } from "./capability";
 
 /**
@@ -106,3 +109,33 @@ export function isCapabilityPlugin(value: unknown): value is CapabilityPlugin {
   const obj = value as Record<string, unknown>;
   return typeof obj.capabilities === "function";
 }
+
+/**
+ * The calling module's own package version, read from the nearest
+ * `package.json` above it (chant #1505).
+ *
+ * `CapabilityPlugin.version` documents itself as the plugin package's semver,
+ * but chant's packages release in lockstep, so a hardcoded literal goes stale
+ * on every `just release` — the aws plugin shipped `"1.0.0"` from the day it
+ * was extracted from the starter set (#681), and the k8s plugin's authoring-
+ * time `"0.41.0"` was stale one release later. Walking up from the module's
+ * own URL survives both the `src/` (development condition) and `dist/`
+ * layouts, and an npm install, without any build-time stamping.
+ *
+ * Returns `"0.0.0"` when no versioned `package.json` is found — a visible
+ * sentinel rather than a guess; nothing gates on the field.
+ */
+export function ownPackageVersion(moduleUrl: string): string {
+  let dir = dirname(fileURLToPath(moduleUrl));
+  for (;;) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")) as { version?: unknown };
+      if (typeof pkg.version === "string") return pkg.version;
+    } catch {
+      // No package.json here (or unreadable) — keep walking up.
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return "0.0.0";
+    dir = parent;
+  }
+}

package/src/components/cli-support.test.ts

@@ -275,6 +275,23 @@ describe("computeComponentGraph", () => {
     expect(result.success).toBe(false);
     expect(result.error).toMatch(/unknown component|ghost/i);
   });
+
+  test("carries each component's liveNames, with the [name] identity fallback (#1491)", async () => {
+    await writeFile(
+      join(testDir, "pg.component.ts"),
+      `export const pg = { name: "postgres", liveNames: ["pgDeployment", "pgService", "pgClaim"], dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+    await writeFile(
+      join(testDir, "plain.component.ts"),
+      `export const plain = { name: "plain", dependsOn: [], deploy: [{ phase: "Apply", steps: [{ kind: "shell", reason: "test" }] }] };`,
+    );
+
+    const result = await computeComponentGraph(testDir);
+
+    expect(result.success).toBe(true);
+    expect(result.liveNames?.postgres).toEqual(["pgDeployment", "pgService", "pgClaim"]);
+    expect(result.liveNames?.plain).toEqual(["plain"]);
+  });
 });
 
 // ── runComponents (#585) ─────────────────────────────────────────────────────

package/src/components/cli-support.ts

@@ -136,6 +136,11 @@ export interface ComponentGraphResult {
    * so a renderer can deep-link a component node to source (`chant graph
    * --components --format ir` sets `sourceLoc` from this). */
   files?: Record<string, string>;
+  /** Component name → the live resource names it owns (#1491): the declared
+   * `liveNames`, or `[name]` when undeclared — the identity-join fallback the
+   * `Component` contract already specifies. This is what lets a consumer join
+   * the component DAG to the resource graph without guessing at kinds. */
+  liveNames?: Record<string, string[]>;
   error?: string;
 }
 
@@ -154,8 +159,13 @@ export async function computeComponentGraph(path: string, sandbox?: boolean): Pr
 
   // component name → its declaring file, relative to `path`, for node deep-links.
   const files: Record<string, string> = {};
+  // component name → owned live resource names (#1491), declared or the
+  // contract's identity fallback.
+  const liveNames: Record<string, string[]> = {};
   for (const [name, discovered] of result.components) {
     files[name] = relative(path, discovered.filePath);
+    const declared = discovered.component.liveNames;
+    liveNames[name] = declared && declared.length > 0 ? [...declared] : [name];
   }
 
   try {
@@ -164,7 +174,7 @@ export async function computeComponentGraph(path: string, sandbox?: boolean): Pr
     for (const c of driverComponents) {
       for (const dep of c.dependsOn ?? []) edges.push({ from: c.name, to: dep });
     }
-    return { success: true, order, waves, edges, files };
+    return { success: true, order, waves, edges, files, liveNames };
   } catch (err) {
     if (err instanceof UnknownDependencyError || err instanceof DependencyCycleError) {
       return { success: false, order: [], waves: [], edges: [], error: err.message };

package/src/components/deploy-units.test.ts

@@ -0,0 +1,42 @@
+import { describe, test, expect } from "vitest";
+import { deployUnits } from "./deploy-units";
+import type { Phase } from "./component";
+
+const phase = (name: string, steps: Phase["steps"]): Phase => ({ phase: name, steps });
+
+describe("deployUnits (#1495 piece 1)", () => {
+  test("resolves a cfn-deploy step to its stack, keyed to the aws observer", () => {
+    const deploy = [phase("Apply", [{ kind: "cfn-deploy", stack: "cc-canonical", template: "t.json" }])];
+    expect(deployUnits(deploy)).toEqual([{ unit: "cc-canonical", lexicon: "aws" }]);
+  });
+
+  test("resolves kubectl-apply and helm-upgrade units once their steps exist", () => {
+    const deploy = [
+      phase("Apply", [
+        { kind: "kubectl-apply", stack: "kubemicrovm-ops" },
+        { kind: "helm-upgrade", release: "operator" },
+      ]),
+    ];
+    expect(deployUnits(deploy)).toEqual([
+      { unit: "kubemicrovm-ops", lexicon: "k8s" },
+      { unit: "operator", lexicon: "helm" },
+    ]);
+  });
+
+  test("walks nested phases, dedupes per lexicon, and skips unitless steps", () => {
+    const deploy = [
+      phase("Outer", [
+        phase("Inner", [{ kind: "cfn-deploy", stack: "web" }]) as never,
+        { kind: "cfn-deploy", stack: "web" },
+        { kind: "shell", cmd: "echo", reason: "no capability yet" },
+        { kind: "cfn-deploy" }, // no stack named — contributes nothing
+      ]),
+    ];
+    expect(deployUnits(deploy)).toEqual([{ unit: "web", lexicon: "aws" }]);
+  });
+
+  test("an unlisted kind contributes no unit — the registry is the rule", () => {
+    const deploy = [phase("Apply", [{ kind: "gcloud-deploy", stack: "x" }])];
+    expect(deployUnits(deploy)).toEqual([]);
+  });
+});

package/src/components/deploy-units.ts

@@ -0,0 +1,82 @@
+/**
+ * Deploy units — which live unit(s) a component's composition targets (#1495).
+ *
+ * `chant components status --live` (and `chant graph --live`) need to know
+ * what a component deployed in order to observe it. That answer used to be a
+ * string literal in the walk — `kind === "cfn-deploy"` — which made the whole
+ * chain CloudFormation-shaped: a component whose deploy phase is a server-side
+ * apply or a Helm upgrade contributed nothing and was skipped, not
+ * "unobserved", simply absent from the result.
+ *
+ * This module is the seam that fixes the walk (piece 1 of #1495's
+ * decomposition): a registry mapping a deploy-family step `kind` to the field
+ * naming its unit and the lexicon whose `describeStackStatus` can observe it.
+ * The registry is data, not a rule about what steps look like — a kind not
+ * listed here contributes no unit, exactly as before.
+ */
+import type { Phase } from "./component";
+
+/** A deploy-family step kind that names a live unit, and who observes it. */
+export interface DeployUnitRule {
+  /** The step `kind` (the capability's registered name). */
+  kind: string;
+  /** The step field carrying the unit's name (`stack`, `release`). */
+  field: string;
+  /** The lexicon whose `describeStackStatus` reads this kind of unit. */
+  lexicon: string;
+}
+
+/**
+ * The deploy-family kinds that name a unit. cfn-deploy's unit is its stack;
+ * kubectl-apply's is the ownership stack its labels carry (#1495 piece 2);
+ * helm-upgrade's is its release (#1495 piece 4). Listing a kind here is safe
+ * before its lexicon implements `describeStackStatus` — units whose lexicon
+ * has no observer are skipped by the caller, the same absent-observer path as
+ * before.
+ */
+export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
+  { kind: "cfn-deploy", field: "stack", lexicon: "aws" },
+  { kind: "kubectl-apply", field: "stack", lexicon: "k8s" },
+  { kind: "helm-upgrade", field: "release", lexicon: "helm" },
+];
+
+/** One resolved unit a component's deploy composition targets. */
+export interface DeployUnit {
+  /** The unit's name — a stack, a release. */
+  unit: string;
+  /** The lexicon that observes this kind of unit. */
+  lexicon: string;
+}
+
+/**
+ * Every distinct deploy unit a component's phases target, in declaration
+ * order. A step may itself be a nested `Phase`, so the walk recurses; a
+ * resolved component carries the unit as a concrete string. Pure.
+ */
+export function deployUnits(deploy: Phase[]): DeployUnit[] {
+  const byKind = new Map(DEPLOY_UNIT_RULES.map((r) => [r.kind, r]));
+  const seen = new Set<string>();
+  const units: DeployUnit[] = [];
+  const walkSteps = (steps: Phase["steps"]): void => {
+    for (const step of steps) {
+      // A step may itself be a nested Phase (it carries its own `steps`). Step
+      // is open-typed (capability inputs), so discriminate structurally.
+      const nested = (step as { steps?: unknown }).steps;
+      if (Array.isArray(nested)) {
+        walkSteps(nested as Phase["steps"]);
+        continue;
+      }
+      const s = step as { kind?: string } & Record<string, unknown>;
+      const rule = s.kind ? byKind.get(s.kind) : undefined;
+      if (!rule) continue;
+      const unit = s[rule.field];
+      if (typeof unit !== "string" || unit.length === 0) continue;
+      const key = `${rule.lexicon}\0${unit}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      units.push({ unit, lexicon: rule.lexicon });
+    }
+  };
+  for (const phase of deploy) walkSteps(phase.steps);
+  return units;
+}

package/src/components/starter-plugin.ts

@@ -42,7 +42,7 @@ import {
   healthGateCapability,
   shellCapability,
 } from "./verbs/index";
-import type { CapabilityPlugin } from "./capability-plugin";
+import { ownPackageVersion, type CapabilityPlugin } from "./capability-plugin";
 
 /**
  * Every `kind` in the starter verb set, grouped by family, per epic #551 and
@@ -99,7 +99,9 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
  */
 export const starterCapabilityPlugin: CapabilityPlugin = {
   name: "starter",
-  version: "1.0.0",
+  // 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),
   capabilities: starterCapabilities,
   families: () => STARTER_VERB_FAMILIES,
 };

package/src/config.test.ts

@@ -1,6 +1,7 @@
 import { describe, test, expect, beforeEach, afterEach } from "vitest";
 import {
   loadChantConfig,
+  loadChantConfigUpward,
   DEFAULT_CHANT_CONFIG,
   resolveAutoReleaseDisabled,
   resolveFoldEnabled,
@@ -137,6 +138,58 @@ describe("loadChantConfig", () => {
   });
 });
 
+// #1502 — the upward walk skips lint-scoping fragments. A `src/chant.config.json`
+// holding only `extends`/`rules` (the examples/ convention) must not shadow the
+// project config above it, or `chant build src` silently loses `ownership`/
+// `buildParams` — the exact fallback #1117's walk exists to prevent.
+describe("loadChantConfigUpward (#1502 — lint fragments do not end the walk)", () => {
+  const SRC = join(TEST_DIR, "src");
+
+  test("walks past a lint-only src/chant.config.json to the project config", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ extends: ["@intentius/chant/lint/presets/strict"], rules: { COR001: "off" } }),
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "billing", env: "prod" } }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config.ownership).toEqual({ stack: "billing", env: "prod" });
+    expect(result.configPath).toBe(join(TEST_DIR, "chant.config.json"));
+  });
+
+  test("a src/chant.config.json declaring any project-level key still wins in place", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "nested" }, rules: { COR001: "off" } }),
+    );
+    writeFileSync(
+      join(TEST_DIR, "chant.config.json"),
+      JSON.stringify({ ownership: { stack: "root" } }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config.ownership?.stack).toBe("nested");
+  });
+
+  test("a fragment-only project resolves to the default config at the boundary", async () => {
+    mkdirSync(SRC, { recursive: true });
+    writeFileSync(join(TEST_DIR, "package.json"), JSON.stringify({ name: "boundary" }));
+    writeFileSync(
+      join(SRC, "chant.config.json"),
+      JSON.stringify({ extends: ["@intentius/chant/lint/presets/strict"] }),
+    );
+
+    const result = await loadChantConfigUpward(SRC);
+    expect(result.config).toEqual(DEFAULT_CHANT_CONFIG);
+    expect(result.configPath).toBeUndefined();
+  });
+});
+
 // #1166 — `environments` accepts either a bare name (unchanged) or
 // `{ name, endpoint }`, so a declared environment can be self-sufficient for
 // `--live` reads without an ambient AWS_ENDPOINT_URL export.

package/src/config.ts

@@ -1,5 +1,5 @@
-import { existsSync } from "fs";
-import { join } from "path";
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
 import { z } from "zod";
 import type { LintConfig } from "./lint/config";
 import type { OwnershipMarker } from "./ownership";
@@ -384,12 +384,50 @@ export async function loadChantConfig(dir: string): Promise<ResolvedConfig> {
  * same walk `chant lint`/`chant graph` already used ({@link findProjectConfig},
  * shared with `./lint/config.ts`'s `findProjectRoot`) — one config-discovery
  * contract for the whole CLI.
+ *
+ * chant #1502 — a lint-scoping fragment does not end the walk. The convention
+ * of a `src/chant.config.json` holding only `extends`/`rules` (cc-aws-canonical
+ * and most of examples/) sits BETWEEN the build directory and the real
+ * `chant.config.ts`, and stopping there re-introduced the exact silent
+ * fallback this walk exists to prevent: `chant build src` resolved the
+ * fragment, found no `ownership`, and built unstamped manifests that every
+ * owned-scoped live read then withheld. A fragment is skipped, not merged —
+ * lint resolution keeps its own nearest-wins walk untouched, and a JSON
+ * config declaring any project-level key still wins where it stands.
  */
 export async function loadChantConfigUpward(startDir: string): Promise<ResolvedConfig> {
-  const { dir } = findProjectConfig(startDir);
+  let { dir, configPath } = findProjectConfig(startDir);
+  while (configPath && isLintOnlyFragment(configPath)) {
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    ({ dir, configPath } = findProjectConfig(parent));
+  }
   return loadChantConfig(dir);
 }
 
+/**
+ * The top-level keys of `./lint/config.ts`'s `LintConfigSchema` (plus the
+ * `$schema` editor convention). A `chant.config.json` whose keys all come from
+ * this set is a lint-scoping fragment, not a project config — see
+ * {@link loadChantConfigUpward}. `chant.config.ts` is never a fragment: it is
+ * project-authored code, and inspecting it would mean evaluating it.
+ */
+const LINT_FRAGMENT_KEYS = new Set(["$schema", "extends", "rules", "overrides", "plugins", "policies"]);
+
+function isLintOnlyFragment(configPath: string): boolean {
+  if (!configPath.endsWith("chant.config.json")) return false;
+  try {
+    const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as unknown;
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return false;
+    const keys = Object.keys(parsed);
+    return keys.length > 0 && keys.every((k) => LINT_FRAGMENT_KEYS.has(k));
+  } catch {
+    // Unreadable/unparseable JSON: let loadChantConfig surface the real error
+    // in place rather than silently walking past it.
+    return false;
+  }
+}
+
 /**
  * Resolve the ownership marker to stamp from project config, or undefined when
  * ownership marking is off (no `stack`, or `enabled: false`).

package/src/graph-detail.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { applyDetail, DETAIL } from "./graph-detail";
+import { applyDetail, DETAIL, detailInertNotice } from "./graph-detail";
 import type { GraphIR } from "./graph-ir";
 
 // A small graph: a gcp vpc/subnet pair plus a k8s namespace and deployment that
@@ -90,3 +90,39 @@ describe("applyDetail", () => {
     });
   });
 });
+
+// #1489 — an inert --detail 3 names itself instead of silently emitting the
+// same bytes as --detail 2 (the k8s lexicon links by name/label convention, so
+// its graphs never have a producer attribute to annotate).
+describe("detailInertNotice (#1489)", () => {
+  test("detail 3 that added toAttr annotations: no notice", () => {
+    const detailed = applyDetail(base, DETAIL.ATTRIBUTES);
+    expect(detailInertNotice(base, detailed)).toBeUndefined();
+  });
+
+  test("edges without producer attributes: notice names the convention-linking cause", () => {
+    const labelLinked: GraphIR = {
+      nodes: [
+        { id: "svc", kind: "Service", lexicon: "k8s", attrs: { spec: { selector: { app: "web" } } } },
+        { id: "web", kind: "Deployment", lexicon: "k8s", attrs: { metadata: { labels: { app: "web" } } } },
+      ],
+      edges: [{ from: "svc", to: "web", kind: "ref", viaAttr: "spec.selector" }],
+      groups: {},
+    };
+    const detailed = applyDetail(labelLinked, DETAIL.ATTRIBUTES);
+    const notice = detailInertNotice(labelLinked, detailed);
+    expect(notice).toContain("--detail 3");
+    expect(notice).toContain("1 edge(s)");
+    expect(notice).toContain("identical to --detail 2");
+  });
+
+  test("no edges at all: notice says so", () => {
+    const edgeless: GraphIR = {
+      nodes: [{ id: "ns", kind: "Namespace", lexicon: "k8s", attrs: {} }],
+      edges: [],
+      groups: {},
+    };
+    const detailed = applyDetail(edgeless, DETAIL.ATTRIBUTES);
+    expect(detailInertNotice(edgeless, detailed)).toContain("no edges at all");
+  });
+});

package/src/graph-detail.ts

@@ -158,3 +158,31 @@ function findRefAttr(attrs: Record<string, unknown>, producer: string): string |
   visit(attrs);
   return found;
 }
+
+/**
+ * chant #1489 — the message to print when `--detail 3` changed nothing.
+ *
+ * T3's only addition over T2 is the producer attribute on `$ref`-derived
+ * edges. A graph whose resources link by name or label convention instead of
+ * attribute references (the k8s lexicon end to end) has nothing to annotate,
+ * so levels 2 and 3 come out byte-identical — which reads as a broken dial
+ * from any consumer stepping through the levels (behold#131 was filed over
+ * exactly this). Accepting a value that changes nothing without saying so is
+ * the bug; this names it.
+ *
+ * Returns the warning text, or undefined when detail 3 did add something.
+ * Callers print it through their own sink; the compare is over the two IRs
+ * the caller already holds, so this stays a pure function.
+ */
+export function detailInertNotice(base: GraphIR, detailed: GraphIR): string | undefined {
+  if (JSON.stringify(detailed) !== JSON.stringify(base)) return undefined;
+  const edges = base.edges.length;
+  const why =
+    edges === 0
+      ? "this graph has no edges at all"
+      : `none of this graph's ${edges} edge(s) reference a producer attribute — they link by name or label convention`;
+  return (
+    `--detail 3 adds the producer attribute to reference edges, but ${why}, ` +
+    `so the output is identical to --detail 2.`
+  );
+}

package/src/kubectl-context.test.ts

@@ -16,7 +16,7 @@ vi.mock("node:child_process", async () => {
 
 const { resolveClusterTarget, ClusterBindingMismatchError } = await import("./kubectl-context");
 
-describe("resolveClusterTarget (chant #1100)", () => {
+describe("resolveClusterTarget (chant #1100, #1488)", () => {
   beforeEach(() => {
     execMock.mockReset();
   });
@@ -34,9 +34,7 @@ describe("resolveClusterTarget (chant #1100)", () => {
     warnSpy.mockRestore();
   });
 
-  test("bound and ambient context matches: returns the bound context", async () => {
-    execMock.mockResolvedValue({ stdout: "prod-eks\n", stderr: "" });
-
+  test("bound: returns the bound context without ever probing the ambient one (#1488)", async () => {
     const target = await resolveClusterTarget(
       { k8s: { profiles: { prod: { context: "prod-eks" } } } },
       "prod",
@@ -44,11 +42,14 @@ describe("resolveClusterTarget (chant #1100)", () => {
     );
 
     expect(target).toEqual({ context: "prod-eks", source: "bound" });
-    expect(execMock).toHaveBeenCalledWith(expect.stringContaining("current-context"));
+    expect(execMock).not.toHaveBeenCalled();
   });
 
-  test("bound and ambient context cannot be determined: proceeds with the bound context anyway", async () => {
-    execMock.mockRejectedValue(new Error("no kubeconfig"));
+  test("bound while a different context is ambient: the binding wins, no refusal (#1488)", async () => {
+    // Ambient says staging-eks; the declared binding must be used regardless.
+    // Before #1488 this threw ClusterBindingMismatchError, which turned a
+    // healthy estate grey the moment any other project switched the context.
+    execMock.mockResolvedValue({ stdout: "staging-eks\n", stderr: "" });
 
     const target = await resolveClusterTarget(
       { k8s: { profiles: { prod: { context: "prod-eks" } } } },
@@ -59,23 +60,14 @@ describe("resolveClusterTarget (chant #1100)", () => {
     expect(target).toEqual({ context: "prod-eks", source: "bound" });
   });
 
-  test("bound and ambient context mismatches: refuses loudly, naming env/expected/ambient", async () => {
-    execMock.mockResolvedValue({ stdout: "staging-eks\n", stderr: "" });
-
-    const err: unknown = await resolveClusterTarget(
-      { k8s: { profiles: { prod: { context: "prod-eks" } } } },
-      "prod",
-      "k8s",
-    ).catch((e: unknown) => e);
-
-    expect(err).toBeInstanceOf(ClusterBindingMismatchError);
-    const mismatch = err as InstanceType<typeof ClusterBindingMismatchError>;
-    expect(mismatch.environment).toBe("prod");
-    expect(mismatch.expectedContext).toBe("prod-eks");
-    expect(mismatch.ambientContext).toBe("staging-eks");
-    expect(mismatch.message).toContain('environment "prod"');
-    expect(mismatch.message).toContain('"prod-eks"');
-    expect(mismatch.message).toContain('"staging-eks"');
+  test("ClusterBindingMismatchError still constructs and names all three parts (catchers rely on it)", () => {
+    const err = new ClusterBindingMismatchError("prod", "prod-eks", "staging-eks");
+    expect(err.environment).toBe("prod");
+    expect(err.expectedContext).toBe("prod-eks");
+    expect(err.ambientContext).toBe("staging-eks");
+    expect(err.message).toContain('environment "prod"');
+    expect(err.message).toContain('"prod-eks"');
+    expect(err.message).toContain('"staging-eks"');
   });
 
   test("bound for a different environment than the one requested: treated as unbound for this environment", async () => {