@intentius/chant 0.46.0 → 0.50.0

package/src/op/receipt-store.ts

@@ -0,0 +1,211 @@
+/**
+ * Receipt store seam (#1834, epic #1703) — how the `effect()` step and the
+ * receipt-reading Ops reach a materialized receipt without knowing which
+ * lexicon materializes it.
+ *
+ * The store is injectable: core defines the {@link ReceiptStore} interface and
+ * the activity contracts; the receipt row's lexicon implements the store over
+ * its own resource (#1835's aws row over `AWS::SSM::Parameter`) and exports
+ * the bound activities (`receiptRead`, `receiptWrite`, `receiptStaleness`)
+ * from its `op/activities` module via {@link receiptActivities}. The activity
+ * registry then resolves them by name, exactly like `ensureSecret`
+ * (#1829/#1830, provided by the k8s lexicon). Tests bind a mock store the
+ * same way.
+ *
+ * Write discipline (epic #1703 decision log, item 3): the `effect()` step is
+ * the SOLE writer of a receipt — on success of its nested steps, last. The
+ * store interface carries a `write`, but only the effect step's emitted
+ * read-compare-run-write (and its local-executor twin) reaches it.
+ * `receiptStaleness` — the WatchOp phase (#1834) — is read-only by
+ * construction: it never touches `write` and runs nothing.
+ *
+ * Expectation resolution follows the resolution split (decision 5): a fully
+ * static receipt's expectation is stamped at synthesis and rides the step
+ * data ({@link receiptCheckInput}); a hash-flavor receipt with reference
+ * inputs resolves at run, through the store lexicon's
+ * {@link ReceiptActivityOptions.resolveExpectation} hook — never by hashing
+ * placeholders.
+ */
+
+import {
+  EXISTENCE_EXPECTATION,
+  isEffectReceipt,
+  receiptExpectation,
+  referenceInputPaths,
+  type EffectReceiptDeclaration,
+  type EffectReceiptFlavor,
+} from "../effect-receipt";
+
+/**
+ * The serializable identity + declaration data of an effect receipt — what an
+ * `effect()` step and a `receiptStaleness` check carry through codegen. Built
+ * from the typed {@link EffectReceiptDeclaration} only ({@link receiptCheckInput});
+ * there is no string form. Reference inputs stay in placeholder form.
+ */
+export interface EffectReceiptRef {
+  /** The receipt's own name (the export-level identity of the witness). */
+  name: string;
+  /** The effect this receipt witnesses. */
+  effect: string;
+  /** How the receipt is compared: mere presence, or a digest of the inputs. */
+  flavor: EffectReceiptFlavor;
+  /** The effect's inputs as recorded at synthesis (references as placeholders). */
+  inputs: Record<string, unknown>;
+}
+
+/**
+ * The injectable seam over the materialized receipt (#1835 implements it for
+ * SSM; tests implement it with a map). `read` returns the receipt's current
+ * stored value, or `undefined` when the receipt is absent. `write` stores the
+ * expectation as the new value — called only by the effect step, on success,
+ * last.
+ */
+export interface ReceiptStore {
+  read(receipt: EffectReceiptRef): Promise<string | undefined>;
+  write(receipt: EffectReceiptRef, expectation: string): Promise<void>;
+}
+
+/** One receipt to check: its identity plus, when the receipt is fully static,
+ * the expectation stamped at synthesis. */
+export interface ReceiptCheckInput {
+  receipt: EffectReceiptRef;
+  /** Present when the expectation was computable at synthesis; absent when
+   * reference inputs resolve at run (decision 5). */
+  expectation?: string;
+}
+
+/**
+ * Snapshot a typed receipt declaration into check-input data: the
+ * {@link EffectReceiptRef} plus the synthesis-time expectation when the
+ * receipt is fully static. Used by the `effect()` builder and by WatchOp's
+ * staleness phase — the single place "static enough to hash now" is decided.
+ */
+export function receiptCheckInput(receipt: EffectReceiptDeclaration): ReceiptCheckInput {
+  if (!isEffectReceipt(receipt)) {
+    throw new Error(
+      "receiptCheckInput: expected an EffectReceipt declaration — import the exported const; there is no string form",
+    );
+  }
+  const ref: EffectReceiptRef = {
+    name: receipt.name,
+    effect: receipt.effect,
+    flavor: receipt.flavor,
+    inputs: receipt.inputs as Record<string, unknown>,
+  };
+  // An existence receipt's expectation is a constant, references or not; a
+  // hash receipt is static only when no reference inputs remain.
+  const isStatic = receipt.flavor === "existence" || referenceInputPaths(receipt).length === 0;
+  return isStatic ? { receipt: ref, expectation: receiptExpectation(receipt) } : { receipt: ref };
+}
+
+// ── Activity contracts ────────────────────────────────────────────────────────
+
+/** Args of the `receiptRead` activity, as the effect step's codegen emits them. */
+export interface ReceiptReadArgs extends ReceiptCheckInput {}
+
+/** Result of the `receiptRead` activity. `current` is `null` (not `undefined`)
+ * for an absent receipt so the value survives JSON transport. */
+export interface ReceiptReadResult {
+  /** The receipt's live stored value, or null when absent. */
+  current: string | null;
+  /** The resolved expectation the workflow compares and later writes. */
+  expectation: string;
+  /** Convenience: `current === expectation`. */
+  applied: boolean;
+}
+
+/** Args of the `receiptWrite` activity — the receipt and the resolved
+ * expectation returned by the preceding `receiptRead`. */
+export interface ReceiptWriteArgs {
+  receipt: EffectReceiptRef;
+  expectation: string;
+}
+
+/** Args of the read-only `receiptStaleness` activity (WatchOp). */
+export interface ReceiptStalenessArgs {
+  receipts: ReceiptCheckInput[];
+}
+
+/** One stale receipt, reported as a finding — never acted on. */
+export interface ReceiptStaleFinding {
+  /** The receipt's name. */
+  receipt: string;
+  /** The effect the receipt witnesses. */
+  effect: string;
+  /** `absent` — no receipt stored; `differs` — stored value is not the expectation. */
+  kind: "absent" | "differs";
+  /** The resolved expectation. */
+  expected: string;
+  /** The live stored value (present only for `differs`). */
+  current?: string;
+}
+
+/** Result of the `receiptStaleness` activity. */
+export interface ReceiptStalenessResult {
+  stale: boolean;
+  findings: ReceiptStaleFinding[];
+}
+
+/** Options for {@link receiptActivities}. */
+export interface ReceiptActivityOptions {
+  /**
+   * Resolve a reference-carrying receipt's expectation at run (decision 5) —
+   * the store lexicon's hook to deploy-time values, typically wrapping core's
+   * `resolveReceiptExpectation`. Without it, a check input that carries no
+   * synthesis-time expectation fails loudly rather than hashing placeholders.
+   */
+  resolveExpectation?: (receipt: EffectReceiptRef) => Promise<string> | string;
+}
+
+/** The three receipt activities, bound to one store. */
+export interface ReceiptActivities {
+  receiptRead: (args: ReceiptReadArgs, signal?: AbortSignal) => Promise<ReceiptReadResult>;
+  receiptWrite: (args: ReceiptWriteArgs, signal?: AbortSignal) => Promise<{ written: true; receipt: string }>;
+  receiptStaleness: (args: ReceiptStalenessArgs, signal?: AbortSignal) => Promise<ReceiptStalenessResult>;
+}
+
+/**
+ * Bind the receipt activities to a store. The store's lexicon calls this once
+ * and re-exports the result from its `op/activities` module; the activity
+ * registry picks the functions up by name for both executors.
+ */
+export function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOptions): ReceiptActivities {
+  const expectationOf = async (input: ReceiptCheckInput): Promise<string> => {
+    if (input.expectation !== undefined) return input.expectation;
+    if (input.receipt.flavor === "existence") return EXISTENCE_EXPECTATION;
+    if (opts?.resolveExpectation) return await opts.resolveExpectation(input.receipt);
+    throw new Error(
+      `receipt "${input.receipt.name}": no synthesis-time expectation and no resolveExpectation hook — ` +
+        `a hash-flavor receipt with reference inputs resolves at run (#1703 decision 5), ` +
+        `and hashing placeholders would be a wrong expectation`,
+    );
+  };
+
+  return {
+    async receiptRead(args: ReceiptReadArgs): Promise<ReceiptReadResult> {
+      const expectation = await expectationOf(args);
+      const current = await store.read(args.receipt);
+      return { current: current ?? null, expectation, applied: current === expectation };
+    },
+
+    async receiptWrite(args: ReceiptWriteArgs): Promise<{ written: true; receipt: string }> {
+      await store.write(args.receipt, args.expectation);
+      return { written: true, receipt: args.receipt.name };
+    },
+
+    // Read-only: reads and reports, runs nothing, never writes.
+    async receiptStaleness(args: ReceiptStalenessArgs): Promise<ReceiptStalenessResult> {
+      const findings: ReceiptStaleFinding[] = [];
+      for (const input of args.receipts) {
+        const expected = await expectationOf(input);
+        const current = await store.read(input.receipt);
+        if (current === undefined) {
+          findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "absent", expected });
+        } else if (current !== expected) {
+          findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "differs", expected, current });
+        }
+      }
+      return { stale: findings.length > 0, findings };
+    },
+  };
+}

package/src/op/step-output-ref.test.ts

@@ -0,0 +1,334 @@
+/**
+ * Step-output reference tests (chant #1290).
+ *
+ * Mirrors activity-contract.test.ts's shape: a small lifecycleDiff-shaped
+ * contract so the test doesn't need a real lexicon.
+ */
+
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { activity, phase, effect } from "./builders";
+import type { OpConfig } from "./types";
+import { activityContract, type ActivityContract } from "./activity-contract";
+import { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs } from "./step-output-ref";
+import { EffectReceipt } from "../effect-receipt";
+
+const lifecycleDiffContract = activityContract(
+  "lifecycleDiff",
+  z.strictObject({ env: z.string(), live: z.boolean().optional() }),
+  z.object({ output: z.string(), exitCode: z.number(), drifted: z.boolean(), driftedStacks: z.array(z.string()) }),
+);
+
+const applyStacksContract = activityContract("applyStacks", z.strictObject({ stacks: z.array(z.string()) }));
+
+// A producer with no `returns` schema — every arg is fine, nothing to
+// validate a reference into its output against.
+const noReturnContract = activityContract("shellCmd", z.strictObject({ cmd: z.string() }));
+
+function opWith(config: Partial<OpConfig> & Pick<OpConfig, "phases">): Pick<OpConfig, "name" | "phases" | "onFailure"> {
+  return { name: "test-op", ...config };
+}
+
+// ── stepOutput() / isStepOutputRef() ────────────────────────────────────────
+
+describe("stepOutput()", () => {
+  it("brands its result so isStepOutputRef recognizes it", () => {
+    const ref = stepOutput("diff", "driftedStacks");
+    expect(isStepOutputRef(ref)).toBe(true);
+    expect(ref.step).toBe("diff");
+    expect(ref.path).toBe("driftedStacks");
+  });
+
+  it("omitting path references the whole return value", () => {
+    const ref = stepOutput("diff");
+    expect(ref.path).toBeUndefined();
+  });
+
+  it("accepts a step object with an id, not just a bare string", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    expect(stepOutput(diff, "driftedStacks")).toEqual(stepOutput("diff", "driftedStacks"));
+  });
+
+  it("throws when the step has no id", () => {
+    expect(() => stepOutput({}, "x")).toThrow(/no `id`/);
+  });
+
+  it("isStepOutputRef rejects a plain object with the same shape", () => {
+    expect(isStepOutputRef({ step: "diff", path: "x" })).toBe(false);
+    expect(isStepOutputRef(null)).toBe(false);
+    expect(isStepOutputRef(undefined)).toBe(false);
+  });
+
+  it("throws when coerced to a primitive — references only, no expressions", () => {
+    const ref = stepOutput("diff", "count");
+    expect(() => `${ref}`).toThrow(/coerced to a primitive/);
+    expect(() => Number(ref)).toThrow(/coerced to a primitive/);
+    expect(() => String(ref)).toThrow(/coerced to a primitive/);
+  });
+});
+
+// ── activity()'s `.out` proxy ───────────────────────────────────────────────
+
+describe("activity().out", () => {
+  it("diff.out.field builds a reference to this step's declared output", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const ref = diff.out.driftedStacks;
+    expect(isStepOutputRef(ref)).toBe(true);
+    expect(ref.step).toBe("diff");
+    expect(ref.path).toBe("driftedStacks");
+  });
+
+  it("diff.out itself (unaccessed) references the whole return value", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    expect(isStepOutputRef(diff.out)).toBe(true);
+    expect(diff.out.path).toBeUndefined();
+    expect(diff.out.step).toBe("diff");
+  });
+
+  it("throws when the step has no id", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" });
+    expect(() => diff.out).toThrow(/has no id/);
+  });
+
+  it("out is non-enumerable — doesn't leak into the step's own JSON shape", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    expect(Object.keys(diff)).not.toContain("out");
+    expect(JSON.stringify(diff)).not.toContain("out");
+  });
+
+  it("string third arg is still a profile, unchanged (backward compatible)", () => {
+    const step = activity("kubectlApply", { manifest: "k8s.yaml" }, "longInfra");
+    expect(step.profile).toBe("longInfra");
+    expect(step.id).toBeUndefined();
+  });
+});
+
+// ── collectStepOutputRefs() ─────────────────────────────────────────────────
+
+describe("collectStepOutputRefs()", () => {
+  it("finds a ref nested inside an object and an array", () => {
+    const ref1 = stepOutput("diff", "a");
+    const ref2 = stepOutput("diff", "b");
+    const found = collectStepOutputRefs({ config: { stacks: [ref1, "literal", ref2] } });
+    expect(found).toEqual([ref1, ref2]);
+  });
+
+  it("returns nothing for plain args", () => {
+    expect(collectStepOutputRefs({ env: "prod", n: 1, list: [1, 2] })).toEqual([]);
+  });
+});
+
+// ── validateStepOutputRefs() ─────────────────────────────────────────────────
+
+describe("validateStepOutputRefs() — passing Ops", () => {
+  it("a same-phase-later-step reference against a valid path passes", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: diff.out.driftedStacks });
+    const config = opWith({ phases: [phase("Reconcile", [diff, apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("a reference from a later phase passes", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: diff.out.driftedStacks });
+    const config = opWith({ phases: [phase("Diff", [diff]), phase("Apply", [apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("a whole-value reference (no path) passes even without checking the producer's return shape", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: stepOutput("diff") });
+    const config = opWith({ phases: [phase("P", [diff, apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("no refs anywhere — no issues", () => {
+    const config = opWith({ phases: [phase("P", [activity("lifecycleDiff", { env: "prod" })])] });
+    expect(validateStepOutputRefs(config, new Map())).toEqual([]);
+  });
+});
+
+describe("validateStepOutputRefs() — the four failure classes from #1290", () => {
+  it("flags a reference to an unknown producer step id", () => {
+    const apply = activity("applyStacks", { stacks: stepOutput("nope", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [apply])] });
+    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
+    expect(issues.some((i) => i.message.includes('unknown step id "nope"'))).toBe(true);
+  });
+
+  it("flags a path that doesn't exist on the producer's declared return schema", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: stepOutput("diff", "notAField") });
+    const config = opWith({ phases: [phase("P", [diff, apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes('path "notAField"') && i.message.includes("does not exist"))).toBe(true);
+  });
+
+  it("flags a reference to a later step", () => {
+    const apply = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const config = opWith({ phases: [phase("Apply", [apply]), phase("Diff", [diff])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("later phase"))).toBe(true);
+  });
+
+  it("flags a reference into a contract-less producer", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff, apply])] });
+    // No contract registered for lifecycleDiff at all.
+    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
+    expect(issues.some((i) => i.message.includes("no registered activity contract"))).toBe(true);
+  });
+});
+
+describe("validateStepOutputRefs() — structural coverage", () => {
+  it("flags a self-reference", () => {
+    const step = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    step.args = { env: "prod", x: stepOutput("diff", "drifted") };
+    const config = opWith({ phases: [phase("P", [step])] });
+    const issues = validateStepOutputRefs(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.some((i) => i.message.includes("does not run before this step"))).toBe(true);
+  });
+
+  it("flags a reference to a step in the same parallel phase", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff, apply], { parallel: true })] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("same parallel phase"))).toBe(true);
+  });
+
+  it("flags a duplicate step id", () => {
+    const diff1 = activity("lifecycleDiff", { env: "a" }, { id: "diff" });
+    const diff2 = activity("lifecycleDiff", { env: "b" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff1, diff2, apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("used by more than one step"))).toBe(true);
+  });
+
+  it("flags a producer contract with no returns schema", () => {
+    const cmd = activity("shellCmd", { cmd: "true" }, { id: "cmd" });
+    const apply = activity("applyStacks", { stacks: stepOutput("cmd", "x") });
+    const config = opWith({ phases: [phase("P", [cmd, apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["shellCmd", noReturnContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("declares no return schema"))).toBe(true);
+  });
+
+  it("flags a reference authored inside onFailure", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const rollback = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff])], onFailure: [phase("Rollback", [rollback])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("onFailure compensation"))).toBe(true);
+  });
+
+  it("flags a reference authored inside an effect step's nested steps", () => {
+    const receipt = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql", version: 3 } });
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const effectStep = effect(receipt, [nested]);
+    const config = opWith({ phases: [phase("P", [diff, effectStep])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("nested inside an effect step"))).toBe(true);
+  });
+
+  it("reports every issue across multiple refs, not just the first", () => {
+    const apply1 = activity("applyStacks", { stacks: stepOutput("nope1", "x") });
+    const apply2 = activity("applyStacks", { stacks: stepOutput("nope2", "x") });
+    const config = opWith({ phases: [phase("P", [apply1, apply2])] });
+    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
+    expect(issues.some((i) => i.message.includes("nope1"))).toBe(true);
+    expect(issues.some((i) => i.message.includes("nope2"))).toBe(true);
+  });
+});
+
+// ── validateStepOutputRefs() — cross-contract primitive-type check (#1950-3) ──
+
+describe("validateStepOutputRefs() — cross-contract type compatibility", () => {
+  const takeCountContract = activityContract("takeCount", z.strictObject({ count: z.number() }));
+
+  it("flags a string-returning path fed into a number-typed arg", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const consume = activity("takeCount", { count: stepOutput("diff", "output") });
+    const config = opWith({ phases: [phase("P", [diff, consume])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["takeCount", takeCountContract],
+    ]);
+    const issues = validateStepOutputRefs(config, contracts);
+    expect(issues.some((i) => i.message.includes("type mismatch") && i.message.includes("string") && i.message.includes("number"))).toBe(true);
+  });
+
+  it("a matching type (array of strings into array of strings) passes", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff, apply])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["applyStacks", applyStacksContract],
+    ]);
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("bails silently when the consumer has no registered contract", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const consume = activity("takeCount", { count: stepOutput("diff", "output") });
+    const config = opWith({ phases: [phase("P", [diff, consume])] });
+    // No contract registered for "takeCount" — nothing to compare the consumer's arg type against.
+    const issues = validateStepOutputRefs(config, new Map([["lifecycleDiff", lifecycleDiffContract]]));
+    expect(issues.some((i) => i.message.includes("type mismatch"))).toBe(false);
+  });
+
+  it("bails silently on a whole-value reference (no path)", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const consume = activity("takeCount", { count: stepOutput("diff") });
+    const config = opWith({ phases: [phase("P", [diff, consume])] });
+    const contracts = new Map<string, ActivityContract>([
+      ["lifecycleDiff", lifecycleDiffContract],
+      ["takeCount", takeCountContract],
+    ]);
+    expect(validateStepOutputRefs(config, contracts).some((i) => i.message.includes("type mismatch"))).toBe(false);
+  });
+});