@intentius/chant 0.46.0 → 0.50.0

package/src/op/effect-step.test.ts

@@ -0,0 +1,311 @@
+/**
+ * effect() step + receipt store seam + local-executor semantics (#1834, epic
+ * #1703). The contract under test:
+ *
+ * - the builder takes the typed EffectReceipt declaration only (no string
+ *   form — enforced at the type level and at runtime);
+ * - read-compare-run-write: a matching receipt skips the nested steps; a
+ *   mismatch runs them and writes the receipt ONLY on their success, last;
+ * - a nested-step failure leaves the receipt untouched (stale), so a rerun
+ *   re-proposes the effect;
+ * - `receiptStaleness` (WatchOp's phase) is read-only: it reports absent and
+ *   differing receipts as findings and never writes.
+ */
+import { describe, test, expect } from "vitest";
+import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION } from "../effect-receipt";
+import { INTRINSIC_MARKER, type Intrinsic } from "../intrinsic";
+import { effect, phase } from "./builders";
+import {
+  receiptActivities,
+  receiptCheckInput,
+  type ReceiptStore,
+  type EffectReceiptRef,
+} from "./receipt-store";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig, ActivityStep } from "./types";
+import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
+
+function fakeIntrinsic(json: unknown): Intrinsic {
+  return {
+    [INTRINSIC_MARKER]: true,
+    toJSON: () => json,
+  };
+}
+
+const seeded = EffectReceipt("seeded", {
+  effect: "db-seed",
+  flavor: "hash",
+  inputs: { file: "seed.sql", version: 3 },
+});
+
+const step = (fn: string, args?: Record<string, unknown>): ActivityStep => ({
+  kind: "activity",
+  fn,
+  ...(args ? { args } : {}),
+});
+
+// ── Builder ───────────────────────────────────────────────────────────────────
+
+describe("effect() builder", () => {
+  test("wraps nested steps with the receipt's identity data and stamps a static expectation", () => {
+    const s = effect(seeded, [step("shellCmd", { cmd: "npm run db:seed" })]);
+    expect(s.kind).toBe("effect");
+    expect(s.receipt).toEqual({
+      name: "seeded",
+      effect: "db-seed",
+      flavor: "hash",
+      inputs: { file: "seed.sql", version: 3 },
+    });
+    expect(s.expectation).toBe(receiptExpectation(seeded));
+    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.signalName))).toEqual(["shellCmd"]);
+  });
+
+  test("existence receipts always get the constant expectation, reference inputs or not", () => {
+    const r = EffectReceipt("booted", {
+      effect: "bootstrap",
+      flavor: "existence",
+      inputs: { endpoint: fakeIntrinsic({ __attrRef: { entity: "Db", attribute: "endpoint" } }) },
+    });
+    expect(effect(r, []).expectation).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  test("a hash receipt with reference inputs carries no synthesis-time expectation (resolves at run, #1703 decision 5)", () => {
+    const r = EffectReceipt("migrated", {
+      effect: "db-migrate",
+      flavor: "hash",
+      inputs: { endpoint: fakeIntrinsic({ __attrRef: { entity: "Db", attribute: "endpoint" } }) },
+    });
+    const s = effect(r, []);
+    expect(s.expectation).toBeUndefined();
+    expect("expectation" in s).toBe(false);
+  });
+
+  test("preserves authored order and nested gates", () => {
+    const s = effect(seeded, [
+      { kind: "gate", signalName: "approve-seed" },
+      step("shellCmd", { cmd: "seed" }),
+    ]);
+    expect(s.steps.map((n) => n.kind)).toEqual(["gate", "activity"]);
+  });
+
+  test("refuses anything that is not the typed receipt declaration", () => {
+    expect(() => effect({ name: "seeded" } as never, [])).toThrow(/no string form/);
+    // Type level: a string receipt name must not compile.
+    // @ts-expect-error — receipt is the EffectReceipt declaration, never a string
+    expect(() => effect("seeded", [])).toThrow(/no string form/);
+  });
+
+  test("effect steps do not nest", () => {
+    const inner = effect(seeded, []);
+    expect(() => effect(seeded, [inner as never])).toThrow(/do not nest/);
+  });
+});
+
+// ── Receipt store seam ────────────────────────────────────────────────────────
+
+function memStore(initial?: Record<string, string>): {
+  store: ReceiptStore;
+  values: Map<string, string>;
+  writes: Array<{ name: string; expectation: string }>;
+} {
+  const values = new Map(Object.entries(initial ?? {}));
+  const writes: Array<{ name: string; expectation: string }> = [];
+  const store: ReceiptStore = {
+    async read(r: EffectReceiptRef) {
+      return values.get(r.name);
+    },
+    async write(r: EffectReceiptRef, expectation: string) {
+      writes.push({ name: r.name, expectation });
+      values.set(r.name, expectation);
+    },
+  };
+  return { store, values, writes };
+}
+
+describe("receiptActivities (the injectable store seam)", () => {
+  const input = receiptCheckInput(seeded);
+  const expected = receiptExpectation(seeded);
+
+  test("receiptRead: absent receipt reads as current null, applied false", async () => {
+    const { store } = memStore();
+    const { receiptRead } = receiptActivities(store);
+    expect(await receiptRead(input)).toEqual({ current: null, expectation: expected, applied: false });
+  });
+
+  test("receiptRead: matching receipt reads as applied true", async () => {
+    const { store } = memStore({ seeded: expected });
+    const { receiptRead } = receiptActivities(store);
+    expect(await receiptRead(input)).toEqual({ current: expected, expectation: expected, applied: true });
+  });
+
+  test("receiptRead: refuses to invent an expectation for a reference-carrying hash receipt without a resolver", async () => {
+    const r = EffectReceipt("migrated", {
+      effect: "db-migrate",
+      flavor: "hash",
+      inputs: { endpoint: fakeIntrinsic("placeholder") },
+    });
+    const { store } = memStore();
+    const { receiptRead } = receiptActivities(store);
+    await expect(receiptRead(receiptCheckInput(r))).rejects.toThrow(/resolveExpectation/);
+  });
+
+  test("receiptWrite stores the expectation", async () => {
+    const { store, writes, values } = memStore();
+    const { receiptWrite } = receiptActivities(store);
+    await receiptWrite({ receipt: input.receipt, expectation: expected });
+    expect(writes).toEqual([{ name: "seeded", expectation: expected }]);
+    expect(values.get("seeded")).toBe(expected);
+  });
+
+  test("receiptStaleness reports absent and differing receipts as findings, and never writes", async () => {
+    const fresh = EffectReceipt("fresh", { effect: "e1", flavor: "hash", inputs: { v: 1 } });
+    const differs = EffectReceipt("differs", { effect: "e2", flavor: "hash", inputs: { v: 2 } });
+    const absent = EffectReceipt("absent", { effect: "e3", flavor: "existence" });
+    const { store, writes } = memStore({
+      fresh: receiptExpectation(fresh),
+      differs: "sha256:stale",
+    });
+    const { receiptStaleness } = receiptActivities(store);
+    const result = await receiptStaleness({
+      receipts: [fresh, differs, absent].map(receiptCheckInput),
+    });
+    expect(result.stale).toBe(true);
+    expect(result.findings).toEqual([
+      { receipt: "differs", effect: "e2", kind: "differs", expected: receiptExpectation(differs), current: "sha256:stale" },
+      { receipt: "absent", effect: "e3", kind: "absent", expected: EXISTENCE_EXPECTATION },
+    ]);
+    expect(writes).toEqual([]);
+  });
+
+  test("receiptStaleness with everything fresh reports stale false", async () => {
+    const { store } = memStore({ seeded: expected });
+    const { receiptStaleness } = receiptActivities(store);
+    expect(await receiptStaleness({ receipts: [input] })).toEqual({ stale: false, findings: [] });
+  });
+});
+
+// ── Local executor: read-compare-run-write ────────────────────────────────────
+
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+};
+
+function activityMap(
+  store: ReceiptStore,
+  extra: Record<string, ActivityFn>,
+): Map<string, ActivityFn> {
+  const map = new Map<string, ActivityFn>();
+  for (const [name, fn] of Object.entries(receiptActivities(store))) {
+    map.set(name, fn as unknown as ActivityFn);
+  }
+  for (const [name, fn] of Object.entries(extra)) map.set(name, fn);
+  return map;
+}
+
+function seedOp(): OpConfig {
+  return {
+    name: "seed-op",
+    overview: "",
+    phases: [phase("Seed", [effect(seeded, [step("runSeed")])])],
+  };
+}
+
+describe("runOpLocally — effect steps", () => {
+  test("matching receipt skips the nested steps and writes nothing", async () => {
+    const { store, writes } = memStore({ seeded: receiptExpectation(seeded) });
+    const ran: string[] = [];
+    const activities = activityMap(store, { runSeed: async () => void ran.push("runSeed") });
+    const result = await runOpLocally(seedOp(), activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(ran).toEqual([]);
+    expect(writes).toEqual([]);
+    // The read records the effect as already applied; the nested step is skipped.
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["runSeed", "skipped"],
+    ]);
+    expect(result.records[0].outcome).toEqual({ name: "EffectApplied", value: true });
+  });
+
+  test("mismatch runs the nested steps, then writes the receipt once, last", async () => {
+    const { store, writes } = memStore();
+    const order: string[] = [];
+    const activities = activityMap(
+      { read: store.read, write: async (r, e) => { order.push("write"); await store.write(r, e); } },
+      { runSeed: async () => void order.push("runSeed") },
+    );
+    const result = await runOpLocally(seedOp(), activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(order).toEqual(["runSeed", "write"]);
+    expect(writes).toEqual([{ name: "seeded", expectation: receiptExpectation(seeded) }]);
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["runSeed", "ok"],
+      ["receiptWrite", "ok"],
+    ]);
+  });
+
+  test("a nested failure leaves the receipt untouched, and a rerun re-proposes the effect", async () => {
+    const { store, writes, values } = memStore();
+    let healthy = false;
+    const activities = activityMap(store, {
+      runSeed: async () => {
+        if (!healthy) throw new Error("seed blew up");
+      },
+    });
+
+    await expect(runOpLocally(seedOp(), activities, PROFILES)).rejects.toThrow(OpRunFailure);
+    expect(writes).toEqual([]);
+    expect(values.has("seeded")).toBe(false);
+
+    // The receipt is stale, so the next run runs the effect again — and only
+    // then writes.
+    healthy = true;
+    const rerun = await runOpLocally(seedOp(), activities, PROFILES);
+    expect(rerun.ok).toBe(true);
+    expect(writes).toEqual([{ name: "seeded", expectation: receiptExpectation(seeded) }]);
+  });
+
+  test("the failed run records the write as skipped, not run", async () => {
+    const { store } = memStore();
+    const activities = activityMap(store, {
+      runSeed: async () => {
+        throw new Error("boom");
+      },
+    });
+    const failure = await runOpLocally(seedOp(), activities, PROFILES).catch((e: OpRunFailure) => e);
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect((failure as OpRunFailure).result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["runSeed", "fail"],
+      ["receiptWrite", "skipped"],
+    ]);
+  });
+
+  test("a gate nested in an effect step is rejected up front, like any other gate", () => {
+    const config: OpConfig = {
+      name: "gated",
+      overview: "",
+      phases: [
+        phase("Seed", [effect(seeded, [{ kind: "gate", signalName: "approve-seed" }, step("runSeed")])]),
+      ],
+    };
+    expect(findGate(config)?.signalName).toBe("approve-seed");
+    const { store } = memStore();
+    return expect(
+      runOpLocally(config, activityMap(store, { runSeed: async () => {} }), PROFILES),
+    ).rejects.toThrow(LocalGateUnsupportedError);
+  });
+
+  test("an effect step in a parallel phase is refused — read-compare-run-write is ordered", async () => {
+    const config: OpConfig = {
+      name: "par",
+      overview: "",
+      phases: [phase("P", [effect(seeded, [step("runSeed")])], { parallel: true })],
+    };
+    const { store } = memStore();
+    await expect(
+      runOpLocally(config, activityMap(store, { runSeed: async () => {} }), PROFILES),
+    ).rejects.toThrow(/parallel phase/);
+  });
+});

package/src/op/generate-pipeline.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Tests for `generateOpsPipeline` (#927) — generate mode's Op counterpart to
+ * `../components/cli-support.ts`'s `generateComponentsPipeline`. Mirrors that
+ * module's own test style (`cli-support.test.ts`): a minimal mocked lexicon
+ * plugin satisfying `isLexiconPlugin`, real `discoverOps()` resolution
+ * against this repo's actual `*.op.ts` fixtures (`examples/alb-deploy.op.ts`
+ * — see `./discover.test.ts`) so Op-name validation exercises the real
+ * discovery path rather than a stub.
+ */
+
+import { describe, test, expect, vi } from "vitest";
+import { generateOpsPipeline } from "./generate-pipeline";
+import type { ScheduledOpSpec, OpPipelineResult } from "../lexicon";
+
+vi.mock("@intentius/chant-lexicon-gitlab", () => ({
+  gitlab: {
+    name: "gitlab",
+    serializer: { name: "gitlab", rulePrefix: "GL", serialize: () => "" },
+    generate: () => {},
+    validate: () => [],
+    coverage: () => ({ total: 0, covered: 0 }),
+    package: () => "gitlab",
+    generateOpPipeline: (ops: ScheduledOpSpec[]): OpPipelineResult => ({
+      files: ops.map((o) => ({ name: `${o.name}.yml`, yaml: `# ${o.name} @ ${o.schedule}` })),
+      jobs: ops.map((o) => ({ jobName: o.name, op: o.name, schedule: o.schedule, findingMode: o.findingMode ?? "report" })),
+    }),
+  },
+}));
+
+describe("generateOpsPipeline", () => {
+  test("errors when the target lexicon has no generateOpPipeline", async () => {
+    const result = await generateOpsPipeline([{ name: "alb-deploy", schedule: "0 6 * * *" }], "aws");
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/does not support Op generate mode/);
+  });
+
+  test("errors on an Op name that isn't discovered", async () => {
+    const result = await generateOpsPipeline(
+      [{ name: "definitely-not-a-real-op", schedule: "0 6 * * *" }],
+      "gitlab",
+    );
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/Unknown Op\(s\): definitely-not-a-real-op/);
+  });
+
+  test("validates every named Op and delegates to the lexicon plugin", async () => {
+    const specs: ScheduledOpSpec[] = [{ name: "alb-deploy", schedule: "0 6 * * *", findingMode: "issue" }];
+    const result = await generateOpsPipeline(specs, "gitlab");
+    expect(result.success).toBe(true);
+    expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
+    expect(result.jobs).toEqual([{ jobName: "alb-deploy", op: "alb-deploy", schedule: "0 6 * * *", findingMode: "issue" }]);
+  });
+});

package/src/op/generate-pipeline.ts

@@ -0,0 +1,99 @@
+/**
+ * Generate mode's Op counterpart (#927): synthesize scheduled CI for
+ * stateless Ops — the cron-triggered sibling of `generateComponentsPipeline`
+ * (../components/cli-support.ts, #563/#688). A component pipeline triggers a
+ * deploy-time graph on `workflow_dispatch`; this triggers already-built Ops
+ * on a cron, each via `chant run <name>` on the local executor — the same
+ * one-shot invocation documented at docs/src/content/docs/guide/ops.mdx. Core
+ * owns only Op discovery, so a typo'd name fails fast before any CI is
+ * generated; the CI-specific synthesis is contributed by the target
+ * lexicon's `generateOpPipeline` (../lexicon.ts), exactly like
+ * `generateComponentPipeline`.
+ *
+ * There is no dependency graph between scheduled Ops the way there is
+ * between components — `Op.depends` orders phases within one run, not
+ * separately scheduled cron triggers — so this does not call
+ * `resolveComponentGraph`; each `ScheduledOpSpec` is generated independently.
+ */
+
+import { discoverOps } from "./discover";
+import {
+  isLexiconPlugin,
+  type LexiconPlugin,
+  type ComponentPipelineOptions,
+  type ScheduledOpSpec,
+  type OpPipelineFile,
+  type OpPipelineJob,
+} from "../lexicon";
+
+/**
+ * Load a lexicon's plugin (`@intentius/chant-lexicon-<name>`) to reach its
+ * `generateOpPipeline`. Tolerant: returns null when the package can't be
+ * resolved. Kept local (rather than imported from
+ * `../components/cli-support.ts`) so this module carries no dependency on
+ * `components/`.
+ */
+async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(`@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  for (const value of Object.values(mod)) {
+    if (isLexiconPlugin(value)) return value;
+  }
+  return null;
+}
+
+/** Result of generating scheduled CI for a set of Ops (generate mode's Op counterpart, #927). */
+export interface GenerateOpsPipelineResult {
+  success: boolean;
+  /** One generated CI file per scheduled Op, when `success` is true. */
+  files?: OpPipelineFile[];
+  /** Every generated job, for a machine-readable view. */
+  jobs?: OpPipelineJob[];
+  error?: string;
+}
+
+/**
+ * Synthesize scheduled CI for `ops` targeting `lexicon`: validate every named
+ * Op exists (`discoverOps`, under the git root — mirrors `chant run <name>`'s
+ * own resolution), then dispatch to the lexicon's `generateOpPipeline`. No
+ * deploy/audit logic is inlined into the generated YAML — the finding-mode
+ * behavior lives in the Op's own activity args, set by the composite that
+ * built it (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, …); this
+ * function only wires the cron trigger and the token/permission surface the
+ * declared `findingMode` needs.
+ */
+export async function generateOpsPipeline(
+  ops: ScheduledOpSpec[],
+  lexicon: string,
+  options?: ComponentPipelineOptions,
+  cwd?: string,
+): Promise<GenerateOpsPipelineResult> {
+  const plugin = await loadLexiconPlugin(lexicon);
+  if (!plugin?.generateOpPipeline) {
+    return {
+      success: false,
+      error: `Lexicon "${lexicon}" does not support Op generate mode (no generateOpPipeline). GitLab, GitHub, and Forgejo are supported today.`,
+    };
+  }
+
+  const discovered = await discoverOps({ cwd });
+  if (discovered.errors.length > 0) {
+    return { success: false, error: discovered.errors.join("\n") };
+  }
+
+  const unknown = ops.filter((spec) => !discovered.ops.has(spec.name));
+  if (unknown.length > 0) {
+    const known = [...discovered.ops.keys()].sort().join(", ");
+    return {
+      success: false,
+      error: `Unknown Op(s): ${unknown.map((s) => s.name).join(", ")}.${known ? ` Known Ops: ${known}` : " No Ops discovered."}`,
+    };
+  }
+
+  const { files, jobs } = plugin.generateOpPipeline(ops, options);
+  return { success: true, files, jobs };
+}

package/src/op/index.ts

@@ -1,5 +1,6 @@
-export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, teardown, envTeardown, k3dUp, k3dDown, flociUp, flociDown,
+export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady,
+         gitlabPipeline, lifecycleSnapshot, shell, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
+         k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,
@@ -13,11 +14,47 @@ export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-life
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
-export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+export { receiptActivities, receiptCheckInput } from "./receipt-store";
+export type {
+  ReceiptStore, EffectReceiptRef, ReceiptCheckInput, ReceiptActivities, ReceiptActivityOptions,
+  ReceiptReadArgs, ReceiptReadResult, ReceiptWriteArgs,
+  ReceiptStalenessArgs, ReceiptStalenessResult, ReceiptStaleFinding,
+} from "./receipt-store";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
+export { generateOpsPipeline } from "./generate-pipeline";
+export type { GenerateOpsPipelineResult } from "./generate-pipeline";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";
 export type { ActivityFn, ActivityProfile } from "./activity-registry";
 export { runOpLocally, parseDuration, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult } from "./local-executor";
 export { renderHuman, renderJson } from "./local-output";
+export {
+  activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES,
+  pathExistsInSchema,
+} from "./activity-contract";
+export type { ActivityContract, ActivityContractIssue } from "./activity-contract";
+export { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope, makeOutProxy } from "./step-output-ref";
+export type { StepOutputRef, WithStepRefs } from "./step-output-ref";
+export type { NamedActivityStep } from "./builders";
+export {
+  eq, neq, gt, gte, lt, lte, truthy, falsy, allOf, anyOf,
+  evaluatePredicate, isWellFormedPredicate, predicateReferencesField,
+  run, report,
+  when, duplicateRuleIds,
+  DEFAULT_FLAP_THRESHOLD,
+} from "./converge-rule";
+export type {
+  FieldComparisonOp, FieldTruthinessOp,
+  FieldComparisonPredicate, FieldTruthinessPredicate, AllOfPredicate, AnyOfPredicate, SymptomPredicate,
+  RunAction, ReportAction, RuleAction, ConvergeRule,
+} from "./converge-rule";
+export {
+  discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
+  DEFAULT_OPERATOR_INTERVAL_MS,
+} from "./operator";
+export type { OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions } from "./operator";
+export { classifyOpVerbClass, isGated } from "./op-verb-class";
+export type { OpVerbClass } from "./op-verb-class";
+export { takeProfileAndId } from "./builders";

package/src/op/local-executor.test.ts

@@ -8,6 +8,7 @@ import {
   LocalGateUnsupportedError,
   OpRunFailure,
 } from "./local-executor";
+import { stepOutput } from "./step-output-ref";
 
 // Fast profiles so retry/timeout tests run in milliseconds.
 const PROFILES: Record<string, ActivityProfile> = {
@@ -261,3 +262,94 @@ describe("runOpLocally — gate rejection", () => {
     expect(gated?.signalName).toBe("g");
   });
 });
+
+describe("runOpLocally — step-output references (#1290)", () => {
+  test("a later step receives the producer's resolved value, not the placeholder", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({ driftedStacks: ["a", "b"], count: 2 })],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "diff" },
+        { kind: "activity", fn: "consume", args: { stacks: stepOutput("diff", "driftedStacks") } },
+      ] }],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(received).toEqual([{ stacks: ["a", "b"] }]);
+    // The recorded step also shows the resolved value, not the raw ref object.
+    expect(result.records[1].args).toEqual({ stacks: ["a", "b"] });
+  });
+
+  test("a whole-value reference (no path) passes the entire producer result", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({ ok: true, detail: "x" })],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "p" },
+        { kind: "activity", fn: "consume", args: { result: stepOutput("p") } },
+      ] }],
+    });
+    await runOpLocally(config, activities, PROFILES);
+    expect(received).toEqual([{ result: { ok: true, detail: "x" } }]);
+  });
+
+  test("resolves a reference nested inside an object and an array", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({ name: "prod" })],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "p" },
+        {
+          kind: "activity",
+          fn: "consume",
+          args: { config: { tags: ["static", stepOutput("p", "name")] } },
+        },
+      ] }],
+    });
+    await runOpLocally(config, activities, PROFILES);
+    expect(received).toEqual([{ config: { tags: ["static", "prod"] } }]);
+  });
+
+  test("an unresolvable path resolves to undefined instead of throwing", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({})],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "p" },
+        { kind: "activity", fn: "consume", args: { v: stepOutput("p", "a.b") } },
+      ] }],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(received).toEqual([{ v: undefined }]);
+  });
+
+  test("e2e: chant run (non-temporal) end to end — producer object flows to consumer", async () => {
+    const activities = new Map<string, ActivityFn>([
+      ["lifecycleDiff", async () => ({ driftedStacks: ["stack-a"], drifted: true })],
+      ["applyStacks", async (args) => ({ applied: args.stacks })],
+    ]);
+    const config = op({
+      phases: [
+        { name: "Diff", steps: [{ kind: "activity", fn: "lifecycleDiff", id: "diff", args: { env: "prod" } }] },
+        { name: "Apply", steps: [{ kind: "activity", fn: "applyStacks", args: { stacks: stepOutput("diff", "driftedStacks") } }] },
+      ],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(result.records.every((r) => r.status === "ok")).toBe(true);
+    expect(result.records[1].args).toEqual({ stacks: ["stack-a"] });
+  });
+});