@intentius/chant 0.56.0 → 0.58.0

package/src/op/composites/composites.test.ts

@@ -0,0 +1,366 @@
+/**
+ * Composite unit tests (#2120) — WatchOp, ReconcileOp, ApplyOp and the
+ * receipt-staleness watch, moved here with the composites themselves. The
+ * serialization half of this suite stays in
+ * a hosting lexicon's own composites suite: that one asserts on its
+ * serializer's output, which is the lexicon's business.
+ */
+
+import { describe, test, expect } from "vitest";
+import { WatchOp } from "./watch-op";
+import { ReconcileOp } from "./reconcile-op";
+import { ApplyOp } from "./apply-op";
+import { DECLARABLE_MARKER } from "../../declarable";
+import { EffectReceipt, receiptExpectation } from "../../effect-receipt";
+
+function getProps(entity: unknown): Record<string, unknown> {
+  return (entity as { props: Record<string, unknown> }).props;
+}
+
+function getEntityType(entity: unknown): string {
+  return (entity as Record<string, unknown>).entityType as string;
+}
+
+// ── WatchOp ──────────────────────────────────────────────────────────
+
+describe("WatchOp: shape", () => {
+  test("returns { op } — the cadence is on the op, not a second resource (#2120)", () => {
+    const result = WatchOp({ name: "prod-watch", env: "prod", schedule: "*/15 * * * *" });
+    expect(result.op).toBeDefined();
+    expect(Object.keys(result)).toEqual(["op"]);
+  });
+
+  test("op has entityType Chant::Op", () => {
+    const { op } = WatchOp({ name: "prod-watch", env: "prod", schedule: "*/15 * * * *" });
+    expect(getEntityType(op)).toBe("Chant::Op");
+  });
+
+  test("the op is Declarable", () => {
+    const { op } = WatchOp({ name: "prod-watch", env: "prod", schedule: "*/15 * * * *" });
+    expect((op as unknown as Record<symbol, unknown>)[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("op.schedule carries the cron with the only overlap policy there is", () => {
+    const { op } = WatchOp({ name: "prod-watch", env: "prod", schedule: "*/15 * * * *" });
+    expect(getProps(op).schedule).toEqual({ cron: "*/15 * * * *", overlap: "skip" });
+  });
+
+  test("no cron: a one-shot watch, no schedule on the op", () => {
+    const { op } = WatchOp({ name: "prod-watch", env: "prod" });
+    expect(getProps(op).schedule).toBeUndefined();
+  });
+
+  test("an invalid cron is refused at construction with cronSyntaxMessage's wording", () => {
+    expect(() => WatchOp({ name: "prod-watch", env: "prod", schedule: "every 15 minutes" })).toThrow(
+      /does not look like valid 5- or 6-field cron syntax/,
+    );
+  });
+});
+
+describe("WatchOp: configuration", () => {
+  test("op has Snapshot + Diff phases referencing the right activities", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "*/15 * * * *" });
+    const phases = (getProps(op).phases as Array<Record<string, unknown>>) ?? [];
+    expect(phases.map((p) => p.name)).toEqual(["Snapshot", "Diff"]);
+    const snapStep = (phases[0].steps as Array<Record<string, unknown>>)[0];
+    const diffStep = (phases[1].steps as Array<Record<string, unknown>>)[0];
+    expect(snapStep.fn).toBe("lifecycleSnapshot");
+    expect(diffStep.fn).toBe("lifecycleDiff");
+    expect(snapStep.args).toEqual({ env: "prod" });
+    expect(diffStep.args).toEqual({ env: "prod", live: true });
+    // Drift is surfaced as a run outcome via outcomeAttribute (#41)
+    expect(diffStep.outcomeAttribute).toEqual({ name: "Drift", from: "drifted" });
+  });
+
+  test("labels include Watch + Env", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "* * * * *" });
+    expect(getProps(op).labels).toEqual({ Watch: "true", Env: "prod" });
+  });
+
+  test("the configured cron reaches op.schedule verbatim", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "0 0 * * *" });
+    expect((getProps(op).schedule as Record<string, unknown>).cron).toBe("0 0 * * *");
+  });
+
+  test("live: false produces a digest-only diff step", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "* * * * *", live: false });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const diffStep = (phases[1].steps as Array<Record<string, unknown>>)[0];
+    expect(diffStep.args).toEqual({ env: "prod", live: false });
+  });
+});
+
+// ── ReconcileOp ──────────────────────────────────────────────────────
+
+describe("ReconcileOp: shape", () => {
+  test("one-shot (no cron) returns an op with no cadence", () => {
+    const result = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+    expect(result.op).toBeDefined();
+    expect(getProps(result.op).schedule).toBeUndefined();
+    expect(getEntityType(result.op)).toBe("Chant::Op");
+    expect((result.op as unknown as Record<symbol, unknown>)[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("with a cron the op carries the schedule and nothing else is returned", () => {
+    const result = ReconcileOp({ name: "prod-reconcile", env: "prod", schedule: "0 * * * *" });
+    expect(Object.keys(result)).toEqual(["op"]);
+    expect(getProps(result.op).schedule).toEqual({ cron: "0 * * * *", overlap: "skip" });
+  });
+});
+
+describe("ReconcileOp: configuration", () => {
+  test("phases are Snapshot → Plan → Reconcile with the right activities", () => {
+    const { op } = ReconcileOp({ name: "p", env: "prod" });
+    const phases = (getProps(op).phases as Array<Record<string, unknown>>) ?? [];
+    expect(phases.map((p) => p.name)).toEqual(["Snapshot", "Plan", "Reconcile"]);
+    const reconcileStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(reconcileStep.fn).toBe("reconcilePr");
+    expect(reconcileStep.args).toEqual({ env: "prod", mode: "pull-request", owned: false });
+  });
+
+  test("scope.owned + onDrift flow into the reconcilePr step", () => {
+    const { op } = ReconcileOp({ name: "p", env: "prod", onDrift: "issue", scope: { owned: true } });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const reconcileStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(reconcileStep.args).toEqual({ env: "prod", mode: "issue", owned: true });
+  });
+
+  test("labels include Reconcile + Env", () => {
+    const { op } = ReconcileOp({ name: "p", env: "prod" });
+    expect(getProps(op).labels).toEqual({ Reconcile: "true", Env: "prod" });
+  });
+
+  test("Plan phase surfaces Drift as a run outcome", () => {
+    const { op } = ReconcileOp({ name: "p", env: "prod" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const diffStep = (phases[1].steps as Array<Record<string, unknown>>)[0];
+    expect(diffStep.outcomeAttribute).toEqual({ name: "Drift", from: "drifted" });
+  });
+});
+
+// ── ApplyOp ──────────────────────────────────────────────────────────
+
+describe("ApplyOp: shape", () => {
+  test("returns an op (no schedule)", () => {
+    const result = ApplyOp({ name: "prod-apply", env: "prod" });
+    expect(result.op).toBeDefined();
+    expect(getEntityType(result.op)).toBe("Chant::Op");
+    expect((result.op as unknown as Record<symbol, unknown>)[DECLARABLE_MARKER]).toBe(true);
+  });
+
+  test("ungated apply: Build → Plan → Apply (no Approve phase)", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "kubectl" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Apply"]);
+    const applyStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(applyStep.fn).toBe("nativeApply");
+    expect(applyStep.args).toEqual({ target: "kubectl", env: "prod", output: "dist", deleteMode: "never" });
+  });
+});
+
+describe("ApplyOp: gating + deletes", () => {
+  test("delete: gated inserts an Approve gate phase before Apply", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", delete: "gated" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(gateStep.kind).toBe("gate");
+    expect(gateStep.signalName).toBe("approve-p");
+  });
+
+  test("explicit gate config is honored", () => {
+    const { op } = ApplyOp({
+      name: "p",
+      env: "prod",
+      gate: { signalName: "go", description: "ship it" },
+    });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(gateStep.signalName).toBe("go");
+    expect(gateStep.description).toBe("ship it");
+  });
+
+  test("deleteMode flows into the nativeApply step", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", delete: "owned-only" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases.find((p) => p.name === "Apply")!.steps as Array<Record<string, unknown>>)[0];
+    expect((applyStep.args as Record<string, unknown>).deleteMode).toBe("owned-only");
+  });
+
+  test("labels include Apply + Env", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod" });
+    expect(getProps(op).labels).toEqual({ Apply: "true", Env: "prod" });
+  });
+});
+
+describe("ApplyOp: compensation (#125, total-or-refused in #1449)", () => {
+  test("destructive apply on a target with a native rollback compensates by default", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "cloudformation", delete: "owned-only" });
+    const onFailure = getProps(op).onFailure as Array<Record<string, unknown>> | undefined;
+    expect(onFailure?.map((p) => p.name)).toEqual(["Rollback"]);
+    const step = (onFailure![0].steps as Array<Record<string, unknown>>)[0];
+    expect(step.fn).toBe("compensateApply");
+    expect(step.args).toEqual({ target: "cloudformation", env: "prod" });
+  });
+
+  test("destructive apply on a rollback-less target has no compensation by default", () => {
+    // Compensation is total: without a rollback path there is nothing the
+    // phase could run, so none is wired — rather than one that could only
+    // warn at rollback time.
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "kubectl", delete: "owned-only" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("additive apply has no compensation by default", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", delete: "never" });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("compensate: false disables rollback even when destructive", () => {
+    const { op } = ApplyOp({
+      name: "p",
+      env: "prod",
+      target: "cloudformation",
+      delete: "owned-only",
+      compensate: false,
+    });
+    expect(getProps(op).onFailure).toBeUndefined();
+  });
+
+  test("compensate.command supplies a rollback for targets without a native one", () => {
+    const { op } = ApplyOp({
+      name: "p",
+      env: "prod",
+      target: "kubectl",
+      compensate: { command: "kubectl rollout undo deployment/web" },
+    });
+    const onFailure = getProps(op).onFailure as Array<Record<string, unknown>>;
+    const step = (onFailure[0].steps as Array<Record<string, unknown>>)[0];
+    expect((step.args as Record<string, unknown>).command).toBe("kubectl rollout undo deployment/web");
+  });
+
+  test("compensate: true on cloudformation builds — the native rollbackStack is the path", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", target: "cloudformation", compensate: true });
+    const onFailure = getProps(op).onFailure as Array<Record<string, unknown>>;
+    const step = (onFailure[0].steps as Array<Record<string, unknown>>)[0];
+    expect(step.fn).toBe("compensateApply");
+    expect((step.args as Record<string, unknown>).command).toBeUndefined();
+  });
+
+  test("compensate: true is refused at build time for every rollback-less target (#1449)", () => {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly"] as const) {
+      expect(() => ApplyOp({ name: "p", env: "prod", target, compensate: true })).toThrow(
+        new RegExp(`ApplyOp "p": compensate is enabled, but target "${target}" has no automatic rollback`),
+      );
+    }
+  });
+
+  test("the refusal names the two ways out — compensate.command or compensate: false", () => {
+    const err = (() => {
+      try {
+        ApplyOp({ name: "web-apply", env: "prod", target: "fly", compensate: true });
+        return undefined;
+      } catch (e) {
+        return String(e);
+      }
+    })();
+    expect(err).toMatch(/compensate: \{ command/);
+    expect(err).toMatch(/compensate: false/);
+    expect(err).toMatch(/rollbackStack/);
+  });
+
+  test("an object without a command is refused the same way as true", () => {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly"] as const) {
+      expect(() => ApplyOp({ name: "p", env: "prod", target, compensate: {} })).toThrow(
+        /has no automatic rollback/,
+      );
+    }
+  });
+
+  test("a command lifts the refusal on every target", () => {
+    for (const target of ["kubectl", "kustomize", "arm", "gcp", "fly", "cloudformation"] as const) {
+      const { op } = ApplyOp({
+        name: "p",
+        env: "prod",
+        target,
+        compensate: { command: "echo rollback" },
+      });
+      const onFailure = getProps(op).onFailure as Array<Record<string, unknown>>;
+      const step = (onFailure[0].steps as Array<Record<string, unknown>>)[0];
+      expect((step.args as Record<string, unknown>).command).toBe("echo rollback");
+    }
+  });
+});
+
+// ── ApplyOp: gated effects (#1834) ───────────────────────────────────
+
+describe("ApplyOp: effects gated (#1834, #1703 decision 6)", () => {
+  test("effects: gated inserts the Approve gate phase before Apply, like delete: gated", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", effects: "gated" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(gateStep.kind).toBe("gate");
+    expect(gateStep.signalName).toBe("approve-p");
+    expect(gateStep.description).toBe("Approve apply to prod (delete mode: never, effects: gated)");
+  });
+
+  test("effects: gated does not change the delete mode riding into nativeApply", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", effects: "gated" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const applyStep = (phases.find((p) => p.name === "Apply")!.steps as Array<Record<string, unknown>>)[0];
+    expect((applyStep.args as Record<string, unknown>).deleteMode).toBe("never");
+  });
+
+  test("effects: gated composes with delete: gated in one Approve gate", () => {
+    const { op } = ApplyOp({ name: "p", env: "prod", delete: "gated", effects: "gated" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(gateStep.description).toBe("Approve apply to prod (delete mode: gated, effects: gated)");
+  });
+
+});
+
+// ── WatchOp: receipt staleness (#1834) ───────────────────────────────
+
+describe("WatchOp: receipt staleness (#1834)", () => {
+  const seeded = EffectReceipt("seeded", {
+    effect: "db-seed",
+    flavor: "hash",
+    inputs: { file: "seed.sql" },
+  });
+
+  test("without receipts the op is unchanged (no Receipts phase)", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "* * * * *" });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    expect(phases.map((p) => p.name)).toEqual(["Snapshot", "Diff"]);
+  });
+
+  test("receipts add a read-only Receipts phase carrying identity + expectation data", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "* * * * *", receipts: [seeded] });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    expect(phases.map((p) => p.name)).toEqual(["Snapshot", "Diff", "Receipts"]);
+    const step = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(step.fn).toBe("receiptStaleness");
+    expect(step.args).toEqual({
+      receipts: [
+        {
+          receipt: { name: "seeded", effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql" } },
+          expectation: receiptExpectation(seeded),
+        },
+      ],
+    });
+    // Staleness surfaces as a run outcome, like Drift.
+    expect(step.outcomeAttribute).toEqual({ name: "StaleReceipts", from: "stale" });
+  });
+
+  test("the Receipts phase runs nothing: its only step is the staleness read", () => {
+    const { op } = WatchOp({ name: "p", env: "prod", schedule: "* * * * *", receipts: [seeded] });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const steps = phases[2].steps as Array<Record<string, unknown>>;
+    expect(steps).toHaveLength(1);
+    expect(steps.map((s) => s.fn)).toEqual(["receiptStaleness"]);
+  });
+
+});

package/src/op/composites/converge-op.test.ts

@@ -0,0 +1,168 @@
+import { describe, test, expect } from "vitest";
+import { runOpLocally } from "../local-executor";
+import type { ActivityFn, ActivityProfile } from "../activity-registry";
+import type { OpConfig } from "../types";
+import { eq, gt, run, report, when } from "../converge-rule";
+import type { ConvergeSymptom } from "../../lifecycle/symptoms";
+import { ConvergeOp } from "./converge-op";
+
+function props(op: unknown): OpConfig {
+  return (op as { props: OpConfig }).props;
+}
+
+function phaseNamed(op: unknown, name: string) {
+  const phase = props(op).phases.find((p) => p.name === name);
+  if (!phase) throw new Error(`no "${name}" phase`);
+  return phase;
+}
+
+const driftRule = when<ConvergeSymptom>(eq("status", "drifted"), run("fountain-apply"), {
+  id: "drift-apply",
+  why: "Re-apply converges drift back to declared source.",
+});
+
+describe("ConvergeOp composite (#1484)", () => {
+  test("builds an Observe -> Converge phase pair", () => {
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule] });
+    const config = props(op);
+    expect(config.phases.map((p) => p.name)).toEqual(["Observe", "Converge"]);
+  });
+
+  test("Observe phase snapshots then diffs, with a Drift outcome attribute", () => {
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule] });
+    const observe = phaseNamed(op, "Observe");
+    expect(observe.steps).toHaveLength(2);
+    expect((observe.steps[0] as { fn: string }).fn).toBe("lifecycleSnapshot");
+    const diff = observe.steps[1] as { fn: string; args: Record<string, unknown>; outcomeAttribute: unknown };
+    expect(diff.fn).toBe("lifecycleDiff");
+    expect(diff.args.env).toBe("staging");
+    expect(diff.outcomeAttribute).toEqual({ name: "Drift", from: "drifted" });
+  });
+
+  test("Converge phase calls convergeTick with the rule table, dial, and budget, threading the Observe diff via a step-output reference", () => {
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", dial: "apply", budget: 5, rules: [driftRule] });
+    const converge = phaseNamed(op, "Converge");
+    expect(converge.steps).toHaveLength(1);
+    const tick = converge.steps[0] as { fn: string; args: Record<string, unknown>; profile: string; outcomeAttribute: unknown };
+    expect(tick.fn).toBe("convergeTick");
+    expect(tick.profile).toBe("longInfra");
+    expect(tick.args.opName).toBe("staging-converge");
+    expect(tick.args.env).toBe("staging");
+    expect(tick.args.dial).toBe("apply");
+    expect(tick.args.budget).toBe(5);
+    expect(tick.args.rules).toEqual([driftRule]);
+    expect(tick.args.preflightDrift).toMatchObject({ kind: "step-output-ref", step: "diff", path: "drifted" });
+    expect(tick.outcomeAttribute).toEqual({ name: "Remediated", from: "remediated" });
+  });
+
+  test("defaults: dial observe, budget 3, live true", () => {
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule] });
+    const config = props(op);
+    expect(config.labels).toEqual({ Converge: "true", Env: "staging", Dial: "observe" });
+    const tick = phaseNamed(op, "Converge").steps[0] as { args: Record<string, unknown> };
+    expect(tick.args.dial).toBe("observe");
+    expect(tick.args.budget).toBe(3);
+    const diff = phaseNamed(op, "Observe").steps[1] as { args: Record<string, unknown> };
+    expect(diff.args.live).toBe(true);
+  });
+
+  test("no schedule -> no cadence on the op; a schedule -> op.schedule.cron (#2120)", () => {
+    const noSchedule = ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule] });
+    expect(props(noSchedule.op).schedule).toBeUndefined();
+
+    const scheduled = ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule], schedule: "*/10 * * * *" });
+    expect(props(scheduled.op).schedule?.cron).toBe("*/10 * * * *");
+  });
+
+  // Finding D (#1954 pre-merge review): issue #1484's acceptance criterion is
+  // "skip-and-report when a prior remediation is in flight ... never queue".
+  // `"skip"` is the overlap policy that drops a fire whose predecessor is
+  // still running, rather than buffering/queuing it.
+  test("a scheduled ConvergeOp sets an explicit \"skip\" overlap — never queue an in-flight tick", () => {
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule], schedule: "*/10 * * * *" });
+    expect(props(op).schedule?.overlap).toBe("skip");
+  });
+
+  test("an invalid cron is refused at construction, with cronSyntaxMessage's wording (#2120)", () => {
+    expect(() =>
+      ConvergeOp({ name: "staging-converge", env: "staging", rules: [driftRule], schedule: "every ten minutes" }),
+    ).toThrow(/does not look like valid 5- or 6-field cron syntax/);
+  });
+});
+
+describe("ConvergeOp composite — build-time refusals (#1484)", () => {
+  test("refuses an empty rule table", () => {
+    expect(() => ConvergeOp({ name: "x", env: "staging", rules: [] })).toThrow(/at least one rule/);
+  });
+
+  test("refuses duplicate rule ids", () => {
+    const dup = when<ConvergeSymptom>(eq("status", "reconciled"), report("noop"), { id: "drift-apply", why: "y" });
+    expect(() => ConvergeOp({ name: "x", env: "staging", rules: [driftRule, dup] })).toThrow(/duplicate rule id/);
+  });
+
+  test("refuses a negative or non-integer budget", () => {
+    expect(() => ConvergeOp({ name: "x", env: "staging", rules: [driftRule], budget: -1 })).toThrow(/budget must be/);
+    expect(() => ConvergeOp({ name: "x", env: "staging", rules: [driftRule], budget: 1.5 })).toThrow(/budget must be/);
+  });
+
+  test("refuses a rule assembled by hand with a blank why", () => {
+    const noWhy = { id: "r1", when: { kind: "field-comparison", field: "status", op: "eq", value: "drifted" }, then: { kind: "report", reason: "x" }, why: "" } as unknown as typeof driftRule;
+    expect(() => ConvergeOp({ name: "x", env: "staging", rules: [noWhy] })).toThrow(/carry its why/);
+  });
+
+  test("refuses a rule assembled by hand outside the evaluable subset", () => {
+    const bad = { id: "r1", when: { kind: "javascript-closure" }, then: { kind: "report", reason: "x" }, why: "y" } as unknown as typeof driftRule;
+    expect(() => ConvergeOp({ name: "x", env: "staging", rules: [bad] })).toThrow(/evaluable subset/);
+  });
+});
+
+describe("ConvergeOp — end-to-end local run (#1484)", () => {
+  const PROFILES: Record<string, ActivityProfile> = {
+    fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
+    longInfra: { timeout: "20m", retry: { maximumAttempts: 1 } },
+  };
+
+  test("chant run <converge-op>: observes, then ticks, resolving the step-output reference into the tick's args", async () => {
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", dial: "apply", budget: 2, rules: [driftRule] });
+    const config = props(op);
+
+    let receivedArgs: Record<string, unknown> | undefined;
+    const activities = new Map<string, ActivityFn>([
+      ["lifecycleSnapshot", (async () => undefined) as ActivityFn],
+      ["lifecycleDiff", (async () => ({ output: "DRIFTED (1)", exitCode: 0, drifted: true })) as ActivityFn],
+      [
+        "convergeTick",
+        (async (args) => {
+          receivedArgs = args;
+          return { drifted: true, remediated: 1, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0, log: "converge(staging): remediated=1" };
+        }) as ActivityFn,
+      ],
+    ]);
+
+    const result = await runOpLocally(config, activities, PROFILES);
+
+    expect(result.status).toBe("ok");
+    // The step-output reference resolved to the real value the Observe phase produced.
+    expect(receivedArgs?.preflightDrift).toBe(true);
+    expect(receivedArgs?.dial).toBe("apply");
+    expect(receivedArgs?.budget).toBe(2);
+    expect(receivedArgs?.opName).toBe("staging-converge");
+  });
+
+  test("a ConvergeOp with a gated dispatch target still runs locally itself — the tick's own phases carry no gate", async () => {
+    // ConvergeOp's own generated workflow never contains a gate step (dispatch
+    // to a gated Op happens inside convergeTick's own subprocess dispatch, not
+    // as a step in this Op's phases) — so the local runner never refuses it.
+    const { op } = ConvergeOp({ name: "staging-converge", env: "staging", dial: "apply", rules: [driftRule] });
+    const config = props(op);
+    expect(config.phases.every((p) => p.steps.every((s) => s.kind !== "gate"))).toBe(true);
+
+    const activities = new Map<string, ActivityFn>([
+      ["lifecycleSnapshot", (async () => undefined) as ActivityFn],
+      ["lifecycleDiff", (async () => ({ output: "", exitCode: 0, drifted: false })) as ActivityFn],
+      ["convergeTick", (async () => ({ drifted: false, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0, log: "" })) as ActivityFn],
+    ]);
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.status).toBe("ok");
+  });
+});