@intentius/chant 0.70.1 → 0.71.1

package/src/lifecycle/affected.test.ts

@@ -138,6 +138,124 @@ describe("affectedStacks — baseDir (caller-supplied)", () => {
   });
 });
 
+// A second lexicon, so a stack that serializes through two of them can be shown
+// folding into one artifact.
+const fakeSerializer2: Serializer = {
+  name: "fake2",
+  rulePrefix: "FAKE2",
+  serialize: (entities) =>
+    JSON.stringify([...entities.keys()].sort().map((k) => ({ k, t: entities.get(k)!.entityType }))),
+};
+
+function otherWidget(type: string): string {
+  return `export const bar = { lexicon: "fake2", entityType: "${type}", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+function deployTimeParam(): string {
+  return `export const p = { lexicon: "fake", entityType: "Param", parameterType: "String", [Symbol.for("chant.declarable")]: true };\n`;
+}
+
+describe("affectedStacks — per-stack mode (#2420)", () => {
+  let root: string;
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "chant-affected-stacks-"));
+  });
+  afterEach(() => rmSync(root, { recursive: true, force: true }));
+
+  // A project root holding one source directory per stack, as ChantConfig.stacks
+  // describes it: { api: <infra.ts contents>, worker: ... }.
+  const project = (name: string, sources: Record<string, string>): string => {
+    const dir = join(root, name);
+    for (const [stack, content] of Object.entries(sources)) {
+      mkdirSync(join(dir, stack), { recursive: true });
+      writeFileSync(join(dir, stack, "infra.ts"), content);
+    }
+    return dir;
+  };
+
+  const stacks = [
+    { name: "api-stack", src: "api" },
+    { name: "worker-stack", src: "worker" },
+  ];
+
+  test("a stacks[] entry whose src is not there is refused by name at head", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget") });
+    await expect(
+      affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks }),
+    ).rejects.toThrow(/stack "worker-stack" declares src "worker", which does not exist/);
+  });
+
+  test("a stack added since base is changed, rather than refused for having no base source", async () => {
+    const base = project("base", { api: widget("Widget") });
+    const head = project("head", { api: widget("Widget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual(["worker-stack"]);
+  });
+
+  test("names the changed stack, not its lexicon — and leaves the untouched stack out", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual(["api-stack"]);
+    expect(r.changed).not.toContain("fake"); // the lexicon name is not an answer
+  });
+
+  test("a no-output-change refactor in the changed stack's own directory is NOT affected", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: "// a harmless refactor\n" + widget("Widget"), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.changed).toEqual([]);
+  });
+
+  test("a stack spanning two lexicons folds into one artifact keyed by the stack", async () => {
+    const both = (type: string) => widget("Widget") + otherWidget(type);
+    const base = project("base", { api: both("Topic"), worker: widget("Queue") });
+    // Only the second lexicon's partition moves; the stack is still what changed.
+    const head = project("head", { api: both("Bus"), worker: widget("Queue") });
+    const r = await affectedStacks({
+      projectPath: head,
+      baseDir: base,
+      serializers: [fakeSerializer, fakeSerializer2],
+      stacks,
+    });
+    expect(r.changed).toEqual(["api-stack"]);
+  });
+
+  test("a deploy-time Parameter is reported as indeterminate under the stack name", async () => {
+    const base = project("base", { api: deployTimeParam(), worker: widget("Queue") });
+    const head = project("head", { api: deployTimeParam(), worker: widget("Queue") });
+    const r = await affectedStacks({ projectPath: head, baseDir: base, serializers: [fakeSerializer], stacks });
+    expect(r.indeterminate).toEqual(["api-stack"]);
+  });
+
+  test("dependents stay empty — the stack-to-stack relation is not in the build", async () => {
+    const base = project("base", { api: widget("Widget"), worker: widget("Queue") });
+    const head = project("head", { api: widget("Gadget"), worker: widget("Queue") });
+    const r = await affectedStacks({
+      projectPath: head,
+      baseDir: base,
+      serializers: [fakeSerializer],
+      stacks,
+      includeDependents: true,
+    });
+    expect(r.changed).toEqual(["api-stack"]);
+    expect(r.dependents).toEqual([]);
+  });
+
+  test("an empty stacks list keeps the single-root, lexicon-keyed answer", async () => {
+    const base = project("base", { api: widget("Widget") });
+    const head = project("head", { api: widget("Gadget") });
+    const r = await affectedStacks({
+      projectPath: join(head, "api"),
+      baseDir: join(base, "api"),
+      serializers: [fakeSerializer],
+      stacks: [],
+    });
+    expect(r.changed).toEqual(["fake"]);
+  });
+});
+
 describe("affectedStacks — baseRef (git worktree)", () => {
   let repo: string;
   beforeEach(async () => {

package/src/lifecycle/affected.ts

@@ -15,8 +15,19 @@
  * be judged from a source diff — reported as **indeterminate**, not silently
  * included or excluded.
  *
- * This returns the set; it does not act. Fanning `lifecycle plan` / `ApplyOp`
- * over it is an Op the user composes.
+ * ## What "stack" means here depends on the project
+ *
+ * A project that declares `stacks` in `chant.config.ts` gets each declared
+ * stack's own source built, and the answer names stacks. A single-root project
+ * has no such partition to build, so its answer names lexicon partitions, which
+ * is the only granularity it has. The difference matters downstream: a
+ * component's deploy step names a stack, so only the first kind of answer can
+ * be joined to components (#2420).
+ *
+ * This returns the set; it does not act. `chant components fan-out`
+ * (../cli/handlers/fan-out.ts) is the command that acts on it, and fanning
+ * `lifecycle plan` / `ApplyOp` over it by hand is still an Op the user
+ * composes.
  */
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
@@ -140,10 +151,92 @@ async function withWorktree<T>(repoRoot: string, ref: string, fn: (dir: string)
   }
 }
 
+/** One independently-deployed stack, as `ChantConfig.stacks` declares it. */
+export interface StackSource {
+  /** The deployed stack name — what a component's deploy step names. */
+  name: string;
+  /** Source directory to build for this stack, relative to the project root. */
+  src: string;
+}
+
+/**
+ * Build each declared stack's own source directory and key the result by
+ * **stack name**.
+ *
+ * Without this, one build of the project root produces a map keyed by lexicon
+ * partition, so an aws-only estate of fifteen stacks answers "aws changed" no
+ * matter which one moved. That answer cannot be joined to anything: a
+ * component's deploy step names a stack, not a lexicon, so
+ * `componentsForUnits` (../components/fan-out.ts) would claim none of it and
+ * a fan-out derived from it would be empty. The two halves have to speak the
+ * same names for either to be worth having.
+ *
+ * A stack that serializes through more than one lexicon folds its partitions
+ * into one artifact, because the unit being deployed is the stack.
+ */
+async function stackArtifacts(
+  root: string,
+  serializers: Serializer[],
+  stacks: readonly StackSource[],
+  /**
+   * Whether a missing `src` is an error. True for the head side, where every
+   * declared stack must exist; false for the base side, where a stack added
+   * since then legitimately has no source yet and reads as an empty artifact,
+   * which is what makes it `changed`.
+   */
+  requireSrc: boolean,
+): Promise<{ artifacts: Map<string, string>; externalInput: string[] }> {
+  const artifacts = new Map<string, string>();
+  const externalInput: string[] = [];
+  for (const stack of stacks) {
+    const src = resolve(root, stack.src);
+    // `build()` on a directory that is not there returns empty outputs rather
+    // than throwing, so a typo in `src` would make both sides build nothing,
+    // match, and report the stack as unchanged forever. A silent answer of
+    // exactly that shape is what this whole path exists to prevent.
+    if (requireSrc && !existsSync(src)) {
+      throw new Error(
+        `stack "${stack.name}" declares src "${stack.src}", which does not exist under ${root}. ` +
+          `Fix chant.config.ts's stacks[] entry: a source directory that is not there builds to nothing, ` +
+          `and a stack that builds to nothing can never be reported as changed.`,
+      );
+    }
+    const built = await build(src, serializers);
+    artifacts.set(
+      stack.name,
+      [...built.outputs.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([lexicon, output]) => `${lexicon}\n${getPrimaryOutput(output as string)}`)
+        .join("\n"),
+    );
+    if (externalInputStacks(built.entities).length > 0) externalInput.push(stack.name);
+  }
+  return { artifacts, externalInput: externalInput.sort() };
+}
+
 export interface AffectedStacksOptions {
   /** Project source directory to scope (the head/working-tree build root). */
   projectPath: string;
   serializers: Serializer[];
+  /**
+   * The project's independently-deployed stacks (`ChantConfig.stacks`). With
+   * them, each stack's own source is built and the answer names stacks; without
+   * them, one build of `projectPath` answers by lexicon partition, which is the
+   * only granularity a single-root project has.
+   *
+   * `dependents` is always empty in this mode, and that is not an omission: the
+   * build holds cross-*lexicon* edges, and the relation between two deployed
+   * stacks is stated by a component's `dependsOn` and `stackOutput`, which
+   * `chant components fan-out` walks for itself. Inventing stack edges from
+   * lexicon ones would be a guess dressed as a graph.
+   *
+   * Each `src` resolves against `projectPath`, so in this mode `projectPath`
+   * has to be the project root that `ChantConfig.stacks` is written relative
+   * to. A `sourceDir` that narrows the build root does not apply here: the
+   * stacks already say which source belongs to which of them, which is the
+   * narrowing, and applying both would look for `<sourceDir>/<stack.src>`.
+   */
+  stacks?: readonly StackSource[];
   /** Base git ref to diff against (built in a throwaway worktree). */
   baseRef?: string;
   /** Head git ref. Defaults to the working tree (built in place — no worktree). */
@@ -175,28 +268,39 @@ export async function affectedStacks(opts: AffectedStacksOptions): Promise<Affec
   // Head: the in-place build of the working tree, unless an explicit headRef is
   // given (then a throwaway worktree — removed before the base worktree, so at
   // most one exists at a time).
+  const perStack = opts.stacks && opts.stacks.length > 0 ? opts.stacks : undefined;
+  // No cross-stack graph in per-stack mode, by construction: see `stacks` above.
+  const EMPTY_GRAPH: StackGraph = { nodes: [], edges: [], order: [], waves: [], cycles: [] };
+  /** One build root in, its artifact map and external-input set out, at whichever granularity applies. */
+  const readArtifacts = async (
+    root: string,
+    isHead: boolean,
+  ): Promise<{ artifacts: Map<string, string>; externalInput: string[]; graph: StackGraph }> => {
+    if (perStack) return { ...(await stackArtifacts(root, opts.serializers, perStack, isHead)), graph: EMPTY_GRAPH };
+    const built = await build(root, opts.serializers);
+    return {
+      artifacts: artifactMap(built.outputs),
+      externalInput: externalInputStacks(built.entities),
+      graph: built.manifest.stackGraph,
+    };
+  };
+
   const head = opts.headRef
-    ? await withWorktree(repoRoot, opts.headRef, (dir) => build(join(dir, relProject), opts.serializers))
-    : await build(projectPath, opts.serializers);
-  const headMap = artifactMap(head.outputs);
-  const externalInput = externalInputStacks(head.entities);
+    ? await withWorktree(repoRoot, opts.headRef, (dir) => readArtifacts(join(dir, relProject), true))
+    : await readArtifacts(projectPath, true);
 
   // Base: caller-supplied dir (cheapest), else a single worktree at baseRef.
   let baseMap: Map<string, string>;
   if (opts.baseDir) {
-    const baseBuild = await build(resolve(opts.baseDir), opts.serializers);
-    baseMap = artifactMap(baseBuild.outputs);
+    baseMap = (await readArtifacts(resolve(opts.baseDir), false)).artifacts;
   } else if (opts.baseRef) {
-    baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => {
-      const baseBuild = await build(join(dir, relProject), opts.serializers);
-      return artifactMap(baseBuild.outputs);
-    });
+    baseMap = await withWorktree(repoRoot, opts.baseRef, async (dir) => (await readArtifacts(join(dir, relProject), false)).artifacts);
   } else {
     throw new Error("affectedStacks requires either baseDir or baseRef");
   }
 
-  return computeAffected(baseMap, headMap, head.manifest.stackGraph, {
+  return computeAffected(baseMap, head.artifacts, head.graph, {
     includeDependents: opts.includeDependents,
-    externalInput,
+    externalInput: head.externalInput,
   });
 }

package/src/meta/declared-imports.test.ts

@@ -0,0 +1,141 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { builtinModules } from "node:module";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * A package may only import, by name, what it declares.
+ *
+ * chant-v0.71.0 shipped `packages/core/src/op/activities/apply.ts` doing
+ * `await import("js-yaml")` while core's package.json declared no such
+ * dependency. Inside this repository it resolved anyway, hoisted out of the six
+ * lexicons that do declare it, so every test and every local build passed. A
+ * consumer installing `@intentius/chant` alone got an unresolvable import, and
+ * the three warden repositories all failed to bundle on the version bump.
+ *
+ * That is the shape worth gating: a missing dependency is invisible in a
+ * workspace and only fails downstream, which is the most expensive place to
+ * find it, after a release is already tagged and published. It is the same
+ * reasoning as the two guards next door — `peer-deps.test.ts` and
+ * `publish-metadata.test.ts` both exist because a packaging field nobody could
+ * see locally broke a publish or an install.
+ *
+ * Scope and precision. This walks the real import nodes with the TypeScript
+ * parser rather than matching text, so a specifier inside a comment, a
+ * code-generation template string, or this repository's own fold-import
+ * fixtures is not mistaken for an import. Only a literal specifier counts: a
+ * variable specifier is the codebase's established way of saying "a package
+ * this one deliberately does not depend on" (see `loadK8sApplier` in
+ * `op/activities/apply.ts`), and nothing statically resolves it.
+ */
+const CORE = fileURLToPath(new URL("../../", import.meta.url));
+
+/**
+ * A package core imports by name on purpose without declaring it, and why.
+ *
+ * An entry here is a promise that the import is guarded: reaching it without
+ * the package installed produces an actionable error rather than a crash.
+ * Anything else belongs in `dependencies`.
+ */
+const DELIBERATELY_UNDECLARED = new Map<string, string>([
+  [
+    "@cdktf/hcl2json",
+    "carries a ~1.8 MB wasm blob and is only needed by `chant carve`; " +
+      "`terraform/parse.ts` catches the failed import and prints the install line",
+  ],
+  [
+    "@intentius/chant-lexicon-gitlab",
+    "the only lexicon shipping migration rules today; `cli/commands/migrate.ts` " +
+      "catches the failed import and migrates with no extra rules. Core depending on " +
+      "a lexicon would invert the dependency direction the whole layering rests on",
+  ],
+]);
+
+/** Every `.ts` file that ships, excluding tests and the fixture trees. */
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((entry) => {
+    const path = join(dir, entry);
+    if (statSync(path).isDirectory()) {
+      return /__fixtures__|__tests__|[/\\]fixtures$/.test(path) ? [] : sourceFiles(path);
+    }
+    return /\.ts$/.test(entry) && !/\.test\.ts$/.test(entry) ? [path] : [];
+  });
+}
+
+/** The package name a specifier resolves to: `zod/v4` -> `zod`, `@a/b/c` -> `@a/b`. */
+function packageOf(specifier: string): string {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+/** Literal bare specifiers this file imports, from real import nodes only. */
+function importedPackages(file: string): Set<string> {
+  const source = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+  const out = new Set<string>();
+  const add = (node: ts.Expression | undefined): void => {
+    if (!node || !ts.isStringLiteral(node)) return;
+    const specifier = node.text;
+    if (specifier.startsWith(".") || specifier.startsWith("/") || specifier.startsWith("node:")) return;
+    const name = packageOf(specifier);
+    if (builtins.has(name)) return;
+    out.add(name);
+  };
+  const visit = (node: ts.Node): void => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) add(node.moduleSpecifier);
+    else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) add(node.argument.literal as ts.Expression);
+    else if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) add(node.arguments[0]);
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(source, visit);
+  return out;
+}
+
+const builtins = new Set(builtinModules);
+
+describe("@intentius/chant imports only what it declares", () => {
+  const pkg = JSON.parse(readFileSync(join(CORE, "package.json"), "utf8")) as {
+    name: string;
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+  };
+  const declared = new Set([
+    pkg.name,
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.peerDependencies ?? {}),
+    ...Object.keys(pkg.optionalDependencies ?? {}),
+  ]);
+
+  test("every literal bare import is declared, or deliberately not", () => {
+    const undeclared = new Map<string, string[]>();
+    for (const file of sourceFiles(join(CORE, "src"))) {
+      for (const name of importedPackages(file)) {
+        if (declared.has(name) || DELIBERATELY_UNDECLARED.has(name)) continue;
+        const where = undeclared.get(name) ?? [];
+        where.push(relative(CORE, file));
+        undeclared.set(name, where);
+      }
+    }
+
+    expect(
+      [...undeclared].map(([name, where]) => `${name} (${where.join(", ")})`),
+      "imported by name but absent from package.json. Add it to dependencies, " +
+        "or guard the import and record it in DELIBERATELY_UNDECLARED with the reason.",
+    ).toEqual([]);
+  });
+
+  test("js-yaml specifically, since that is the one that shipped broken", () => {
+    // chant-v0.71.0's regression, pinned by name so the fix cannot be reverted
+    // quietly: `renderKustomization` parses `kustomize build` output with it.
+    expect(declared.has("js-yaml")).toBe(true);
+  });
+
+  test("the deliberate exceptions are still imported, so the list cannot rot", () => {
+    const imported = new Set(sourceFiles(join(CORE, "src")).flatMap((f) => [...importedPackages(f)]));
+    for (const name of DELIBERATELY_UNDECLARED.keys()) {
+      expect(imported.has(name), `${name} is listed as deliberately undeclared but nothing imports it`).toBe(true);
+    }
+  });
+});

package/src/op/activities/activity-contracts.ts

@@ -37,9 +37,25 @@ export const lifecycleDiffContract = activityContract(
   z.object({ output: z.string(), exitCode: z.number(), drifted: z.boolean() }),
 );
 
+/**
+ * The escape hatch (#2413). `returns` is what `shellCmd` captured and used to
+ * throw away: the trimmed stdout, the trimmed stderr, and the exit code —
+ * which only ever differs from `0` when the step named that code in `okExit`,
+ * since anything else still rejects.
+ *
+ * Running a command chant does not model in order to discard what it produced
+ * is the odd case, not the normal one, so the value a later step reads through
+ * `sh.out.stdout` is the point of the step rather than an extra.
+ */
 export const shellCmdContract = activityContract(
   "shellCmd",
-  z.strictObject({ cmd: z.string(), env: z.record(z.string(), z.string()).optional(), cwd: z.string().optional() }),
+  z.strictObject({
+    cmd: z.string(),
+    env: z.record(z.string(), z.string()).optional(),
+    cwd: z.string().optional(),
+    okExit: z.array(z.number()).optional(),
+  }),
+  z.object({ stdout: z.string(), stderr: z.string(), exitCode: z.number() }),
 );
 
 export const httpCheckContract = activityContract(

package/src/op/activities/index.ts

@@ -14,7 +14,7 @@ export type { WaitForStackArgs } from "./wait";
 // provides gitlabPipeline. The gitlabPipeline step builder stays in core.
 
 export { shellCmd } from "./shell";
-export type { ShellCmdArgs } from "./shell";
+export type { ShellCmdArgs, ShellCmdResult } from "./shell";
 
 export { httpCheck, statusOk } from "./http-check";
 export type { HttpCheckArgs, HttpFetch } from "./http-check";

package/src/op/activities/shell.test.ts

@@ -0,0 +1,156 @@
+/**
+ * The escape hatch's safety properties (#2411, #2412) and what it publishes
+ * (#2413, #2414).
+ *
+ * `shellCmd` runs a command chant did not write and cannot model, which is
+ * what makes these different from every other activity: nothing here can know
+ * whether repeating the command is safe, how much it will say, or what a
+ * non-zero exit means.
+ */
+
+import { describe, test, expect } from "vitest";
+import { z } from "zod";
+import { shellCmd } from "./shell";
+import { shellCmdContract } from "./activity-contracts";
+import { shell } from "../builders";
+import { phase } from "../builders";
+import { collectStepOutputRefs, stepOutput, validateStepOutputRefs } from "../step-output-ref";
+import { ACTIVITY_PROFILES } from "../activity-profiles";
+import { runOpLocally } from "../local-executor";
+import { memoryGateLedgerPort } from "../gate";
+import type { ActivityFn } from "../activity-registry";
+import type { ShellCmdArgs, ShellCmdResult } from "./shell";
+
+describe("the at-most-once default (#2411)", () => {
+  test("shell() asks for a profile that does not retry", () => {
+    const step = shell("echo hi");
+    expect(step.profile).toBe("atMostOnce");
+    expect(ACTIVITY_PROFILES.atMostOnce.retry.maximumAttempts).toBe(1);
+  });
+
+  test("an author who knows the command is safe to repeat can still say so", () => {
+    // The direction that matters: retrying is opt-in, because it is the claim
+    // that needs evidence about the command.
+    expect(shell("echo hi", { profile: "fastIdempotent" }).profile).toBe("fastIdempotent");
+    expect(ACTIVITY_PROFILES.fastIdempotent.retry.maximumAttempts).toBeGreaterThan(1);
+  });
+
+  test("the profile allows a long command, since a shell step is often a build", () => {
+    expect(ACTIVITY_PROFILES.atMostOnce.timeout).toBe("20m");
+  });
+});
+
+describe("the stdout ceiling (#2412)", () => {
+  test("a command producing well over 1 MiB completes instead of rejecting", async () => {
+    // Node's default maxBuffer is 1 MiB and this activity was the only exec
+    // site leaving it unset. 4 MiB is comfortably past the old ceiling and
+    // far short of the new one.
+    const bytes = 4 * 1024 * 1024;
+    const out = await shellCmd({ cmd: `node -e "process.stdout.write('x'.repeat(${bytes}))"` });
+    expect(out.stdout.length).toBe(bytes);
+  });
+
+  test("stdout is returned trimmed, as before", async () => {
+    expect((await shellCmd({ cmd: "echo hello" })).stdout).toBe("hello");
+  });
+
+  test("cwd and env reach the command", async () => {
+    const out = await shellCmd({ cmd: "pwd && echo $CHANT_SHELL_TEST", cwd: "/tmp", env: { CHANT_SHELL_TEST: "set" } });
+    expect(out.stdout).toContain("set");
+  });
+});
+
+describe("what a shell step publishes (#2413)", () => {
+  test("the contract declares a return schema, so a later step may reference it", () => {
+    const returns = shellCmdContract.returns as z.ZodTypeAny | undefined;
+    expect(returns).toBeDefined();
+    expect(returns!.parse({ stdout: "a", stderr: "b", exitCode: 0 })).toEqual({ stdout: "a", stderr: "b", exitCode: 0 });
+  });
+
+  test("a step reading a shell step's stdout passes OPS013", () => {
+    const host = shell("echo db.internal", { id: "host" });
+    const smoke = shell("./smoke.sh", { env: { HOST: host.out.stdout } });
+    const issues = validateStepOutputRefs(
+      { name: "deploy", phases: [phase("Go", [host, smoke])] },
+      new Map([["shellCmd", shellCmdContract]]),
+    );
+    expect(issues).toEqual([]);
+  });
+
+  test("a path the shell result does not declare is still flagged", () => {
+    const host = shell("echo db.internal", { id: "host" });
+    const smoke = shell("./smoke.sh", { env: { HOST: stepOutput(host, "stdoutt") } });
+    const issues = validateStepOutputRefs(
+      { name: "deploy", phases: [phase("Go", [host, smoke])] },
+      new Map([["shellCmd", shellCmdContract]]),
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('output path "stdoutt"');
+  });
+
+  test("stderr survives the call instead of being printed and dropped", async () => {
+    const out = await shellCmd({ cmd: `node -e "process.stderr.write('warned')"` });
+    expect(out).toMatchObject({ stdout: "", stderr: "warned", exitCode: 0 });
+  });
+
+  test("a non-zero exit still rejects, and the code is in the message", async () => {
+    await expect(shellCmd({ cmd: "exit 3" })).rejects.toThrow(/exited 3 \(expected 0\)/);
+  });
+
+  test("a code the author named resolves, carrying output and the code", async () => {
+    // `diff` exits 1 to report a difference. Nothing about that is a failure,
+    // and before this the whole step was one.
+    const out = await shellCmd({ cmd: `node -e "process.stdout.write('changed'); process.exit(1)"`, okExit: [0, 1] });
+    expect(out).toEqual({ stdout: "changed", stderr: "", exitCode: 1 });
+  });
+
+  test("a code the author did not name still rejects", async () => {
+    await expect(shellCmd({ cmd: "exit 2", okExit: [0, 1] })).rejects.toThrow(/exited 2 \(expected 0, 1\)/);
+  });
+
+  test("a signal kill rejects even when its code is named", async () => {
+    // A timeout or Ctrl-C is not an exit status the author said anything
+    // about, so `okExit` must not swallow it.
+    const ac = new AbortController();
+    const running = shellCmd({ cmd: "sleep 5", okExit: [0, 1, 143] }, ac.signal);
+    ac.abort();
+    await expect(running).rejects.toThrow();
+  });
+});
+
+describe("a reference reaching the command (#2414)", () => {
+  test("a reference in env typechecks, which is the whole gap", () => {
+    const host = shell("echo db.internal", { id: "host" });
+    // No `as` cast: before #2414 `WithStepRefs` was shallow, so a reference
+    // inside `env`'s Record<string, string> was a type error even though the
+    // executor resolved it and the lint rule accepted it.
+    const smoke = shell("./smoke.sh", { env: { HOST: host.out.stdout, MODE: "ci" } });
+    expect(collectStepOutputRefs(smoke.args)).toEqual([
+      expect.objectContaining({ step: "host", path: "stdout" }),
+    ]);
+    expect((smoke.args as { env: Record<string, string> }).env.MODE).toBe("ci");
+  });
+
+  test("the executor carries it into the next command's environment, end to end", async () => {
+    const host = shell("echo db.internal", { id: "host" });
+    const smoke = shell("echo reached $HOST", { env: { HOST: host.out.stdout }, id: "smoke" });
+
+    const seen: ShellCmdResult[] = [];
+    const spy: ActivityFn = async (args, signal) => {
+      const out = await shellCmd(args as unknown as ShellCmdArgs, signal);
+      seen.push(out);
+      return out;
+    };
+
+    const result = await runOpLocally(
+      { name: "deploy", overview: "", phases: [phase("Go", [host, smoke])] },
+      new Map([["shellCmd", spy]]),
+      ACTIVITY_PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort() },
+    );
+
+    expect(result.status).toBe("ok");
+    expect(seen.map((s) => s.stdout)).toEqual(["db.internal", "reached db.internal"]);
+  });
+});