@intentius/chant 0.49.0 → 0.51.0

package/src/op/builders-exports.test.ts

@@ -50,7 +50,23 @@ describe("op builders are all reachable (#1715)", () => {
       "spriteApplyServices", "spriteTaskCreate", "spriteTaskRefresh",
       "spriteTaskRelease", "spritesUp", "spritesDown",
     ]);
-    const expected = Object.keys(builders).filter((n) => !FLY_SURFACE.has(n));
+    // chant #1288 Stage 2 — these are the temporal lexicon's OWN activities
+    // (build.ts, shell.ts, wait.ts, ...), so its barrel re-exports a fully
+    // typed twin from its own `./op/builders` instead of core's untyped
+    // original — same name, same import path, deliberately not sourced from
+    // `@intentius/chant/op` any more. See `lexicons/temporal/src/index.ts`
+    // and `lexicons/temporal/src/op/builders.ts`.
+    const TEMPORAL_TYPED_SURFACE = new Set([
+      "build", "shell", "waitForStack", "lifecycleSnapshot", "teardown", "envTeardown", "httpCheck", "policyGate",
+    ]);
+    // chant #1288 Stage 2 — an internal helper (`takeProfile`'s sibling) for
+    // the lexicon-owned typed step-builder wrappers to reuse, not an
+    // Op-authoring primitive itself; nothing authors an Op with it directly,
+    // so it has no place in the Op-authoring barrel.
+    const INTERNAL_HELPERS = new Set(["takeProfileAndId"]);
+    const expected = Object.keys(builders).filter(
+      (n) => !FLY_SURFACE.has(n) && !TEMPORAL_TYPED_SURFACE.has(n) && !INTERNAL_HELPERS.has(n),
+    );
     const missing = expected.filter((name) => !reExported.has(name));
     expect(
       missing,

package/src/op/builders.ts

@@ -2,6 +2,18 @@ import { OpResource } from "./resource";
 import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
 import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
 import { receiptCheckInput } from "./receipt-store";
+import { makeOutProxy, type StepOutputRef } from "./step-output-ref";
+
+/** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
+export interface NamedActivityStep extends ActivityStep {
+  /**
+   * `step.out.someField` builds a {@link StepOutputRef} into this step's
+   * declared return value, for use in a later step's `args`. Throws on
+   * access if this step has no `id` (pass one via `activity()`'s third
+   * argument) — there is nothing for a reference to name otherwise.
+   */
+  readonly out: Record<string, StepOutputRef>;
+}
 
 // ── Core builders ─────────────────────────────────────────────────────────────
 
@@ -33,18 +45,44 @@ export function phase(
   return { name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
 }
 
-/** Reference a pre-built or custom activity by function name. */
+/**
+ * Reference a pre-built or custom activity by function name.
+ *
+ * The third argument is a profile string (unchanged) or, to name the step
+ * so a later step can reference its output (#1290), an options object:
+ * `activity("lifecycleDiff", { env: "prod" }, { id: "diff" })`. Named or
+ * not, the result carries `.out` — `diff.out.driftedStacks` builds a
+ * reference to this step's declared return value; see `stepOutput()` in
+ * `@intentius/chant/op` for the equivalent on a step authored as a plain
+ * object literal instead of via this builder.
+ */
 export function activity(
   fn: string,
   args?: Record<string, unknown>,
-  profile?: ActivityStep["profile"],
-): ActivityStep {
-  return {
+  opts?: ActivityStep["profile"] | { profile?: ActivityStep["profile"]; id?: string },
+): NamedActivityStep {
+  const profile = typeof opts === "string" ? opts : opts?.profile;
+  const id = typeof opts === "string" ? undefined : opts?.id;
+  const step = {
     kind: "activity",
     fn,
     ...(args && Object.keys(args).length > 0 ? { args } : {}),
     ...(profile ? { profile } : {}),
-  };
+    ...(id ? { id } : {}),
+  } as NamedActivityStep;
+  Object.defineProperty(step, "out", {
+    enumerable: false,
+    get(): Record<string, StepOutputRef> {
+      if (!step.id) {
+        throw new Error(
+          `activity(${JSON.stringify(fn)}, ...).out: this step has no id — pass one via ` +
+            `activity(fn, args, { id: "..." }) before referencing its output.`,
+        );
+      }
+      return makeOutProxy(step.id);
+    },
+  });
+  return step;
 }
 
 /** Insert a human gate — the workflow pauses until the named signal is received. */
@@ -136,6 +174,22 @@ function takeProfile(
   return { args, profile };
 }
 
+/**
+ * {@link takeProfile}'s sibling for the typed, lexicon-owned step-builder
+ * wrappers added in chant #1288 Stage 2 (e.g. `kubectlApply` in
+ * `@intentius/chant-lexicon-k8s`): also pulls `id` out of the opts bag so it
+ * routes to the step's `id` field (enabling `.out` — #1290) instead of
+ * leaking into the activity's args, the same way `profile` would without
+ * this split.
+ */
+export function takeProfileAndId(
+  opts: (Record<string, unknown> & { profile?: ActivityStep["profile"]; id?: string }) | undefined,
+): { args: Record<string, unknown>; profile?: ActivityStep["profile"]; id?: string } {
+  if (!opts) return { args: {} };
+  const { profile, id, ...args } = opts as { profile?: ActivityStep["profile"]; id?: string } & Record<string, unknown>;
+  return { args, profile, id };
+}
+
 /** Run an npm build script in the given project directory. `opts.script` selects the script (default `build`, e.g. `build:aws`); `opts.env` adds env vars. */
 export const build = (path: string, opts?: Record<string, unknown>): ActivityStep => {
   const { args, profile } = takeProfile(opts);

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

@@ -0,0 +1,179 @@
+import { describe, test, expect } from "vitest";
+import {
+  eq, neq, gt, gte, lt, lte, truthy, falsy, allOf, anyOf,
+  evaluatePredicate, isWellFormedPredicate, predicateReferencesField,
+  run, report, when, duplicateRuleIds,
+  DEFAULT_FLAP_THRESHOLD,
+} from "./converge-rule";
+
+interface TestSymptom {
+  status: string;
+  count: number;
+  flag: boolean;
+}
+
+const symptom: TestSymptom = { status: "drifted", count: 3, flag: true };
+
+describe("evaluatePredicate", () => {
+  test("eq matches / doesn't match", () => {
+    expect(evaluatePredicate(eq<TestSymptom>("status", "drifted"), symptom)).toBe(true);
+    expect(evaluatePredicate(eq<TestSymptom>("status", "reconciled"), symptom)).toBe(false);
+  });
+
+  test("neq", () => {
+    expect(evaluatePredicate(neq<TestSymptom>("status", "reconciled"), symptom)).toBe(true);
+    expect(evaluatePredicate(neq<TestSymptom>("status", "drifted"), symptom)).toBe(false);
+  });
+
+  test("numeric comparisons", () => {
+    expect(evaluatePredicate(gt<TestSymptom>("count", 2), symptom)).toBe(true);
+    expect(evaluatePredicate(gt<TestSymptom>("count", 3), symptom)).toBe(false);
+    expect(evaluatePredicate(gte<TestSymptom>("count", 3), symptom)).toBe(true);
+    expect(evaluatePredicate(lt<TestSymptom>("count", 4), symptom)).toBe(true);
+    expect(evaluatePredicate(lt<TestSymptom>("count", 3), symptom)).toBe(false);
+    expect(evaluatePredicate(lte<TestSymptom>("count", 3), symptom)).toBe(true);
+  });
+
+  test("numeric comparison against a non-number field never throws, just doesn't match", () => {
+    expect(evaluatePredicate(gt<TestSymptom>("status" as never, 1), symptom)).toBe(false);
+  });
+
+  test("truthy / falsy", () => {
+    expect(evaluatePredicate(truthy<TestSymptom>("flag"), symptom)).toBe(true);
+    expect(evaluatePredicate(falsy<TestSymptom>("flag"), symptom)).toBe(false);
+    expect(evaluatePredicate(truthy<TestSymptom>("count"), { ...symptom, count: 0 })).toBe(false);
+  });
+
+  test("allOf requires every predicate to match", () => {
+    expect(evaluatePredicate(allOf<TestSymptom>(eq("status", "drifted"), gt("count", 2)), symptom)).toBe(true);
+    expect(evaluatePredicate(allOf<TestSymptom>(eq("status", "drifted"), gt("count", 10)), symptom)).toBe(false);
+  });
+
+  test("anyOf requires at least one predicate to match", () => {
+    expect(evaluatePredicate(anyOf<TestSymptom>(eq("status", "reconciled"), gt("count", 2)), symptom)).toBe(true);
+    expect(evaluatePredicate(anyOf<TestSymptom>(eq("status", "reconciled"), gt("count", 10)), symptom)).toBe(false);
+  });
+
+  test("nested allOf/anyOf compose", () => {
+    const p = allOf<TestSymptom>(truthy("flag"), anyOf(eq("status", "reconciled"), gt("count", 1)));
+    expect(evaluatePredicate(p, symptom)).toBe(true);
+  });
+});
+
+describe("predicateReferencesField", () => {
+  test("a field comparison references its own field, not another", () => {
+    expect(predicateReferencesField(eq<TestSymptom>("status", "drifted"), "status")).toBe(true);
+    expect(predicateReferencesField(eq<TestSymptom>("status", "drifted"), "count")).toBe(false);
+  });
+
+  test("a field truthiness predicate references its own field", () => {
+    expect(predicateReferencesField(truthy<TestSymptom>("flag"), "flag")).toBe(true);
+    expect(predicateReferencesField(truthy<TestSymptom>("flag"), "status")).toBe(false);
+  });
+
+  test("allOf/anyOf reference a field if any nested predicate does", () => {
+    const p = allOf<TestSymptom>(eq("status", "drifted"), gt("count", 2));
+    expect(predicateReferencesField(p, "count")).toBe(true);
+    expect(predicateReferencesField(p, "flag")).toBe(false);
+  });
+
+  test("recurses through nested allOf/anyOf", () => {
+    const p = allOf<TestSymptom>(truthy("flag"), anyOf(eq("status", "reconciled"), gt("count", 1)));
+    expect(predicateReferencesField(p, "count")).toBe(true);
+    expect(predicateReferencesField(p, "status")).toBe(true);
+    expect(predicateReferencesField(p, "flag")).toBe(true);
+  });
+});
+
+describe("isWellFormedPredicate", () => {
+  test("accepts every builder's output", () => {
+    expect(isWellFormedPredicate(eq<TestSymptom>("status", "x"))).toBe(true);
+    expect(isWellFormedPredicate(neq<TestSymptom>("status", "x"))).toBe(true);
+    expect(isWellFormedPredicate(gt<TestSymptom>("count", 1))).toBe(true);
+    expect(isWellFormedPredicate(truthy<TestSymptom>("flag"))).toBe(true);
+    expect(isWellFormedPredicate(falsy<TestSymptom>("flag"))).toBe(true);
+    expect(isWellFormedPredicate(allOf<TestSymptom>(eq("status", "x"), truthy("flag")))).toBe(true);
+    expect(isWellFormedPredicate(anyOf<TestSymptom>(eq("status", "x")))).toBe(true);
+  });
+
+  test("rejects a malformed shape", () => {
+    expect(isWellFormedPredicate(null)).toBe(false);
+    expect(isWellFormedPredicate("eq(status, drifted)")).toBe(false);
+    expect(isWellFormedPredicate({ kind: "field-comparison", field: "status", op: "regex", value: "x" })).toBe(false);
+    expect(isWellFormedPredicate({ kind: "all-of", predicates: [{ kind: "bogus" }] })).toBe(false);
+    expect(isWellFormedPredicate(() => true)).toBe(false);
+  });
+
+  test("respects a field whitelist", () => {
+    const whitelist = new Set(["status"]);
+    expect(isWellFormedPredicate(eq<TestSymptom>("status", "x"), whitelist)).toBe(true);
+    expect(isWellFormedPredicate(eq<TestSymptom>("count", 1), whitelist)).toBe(false);
+  });
+});
+
+describe("run / report", () => {
+  test("run() builds a RunAction", () => {
+    expect(run("fountain-apply")).toEqual({ kind: "run", op: "fountain-apply" });
+  });
+  test("report() builds a ReportAction", () => {
+    expect(report("unowned resources present")).toEqual({ kind: "report", reason: "unowned resources present" });
+  });
+});
+
+describe("when()", () => {
+  test("builds a well-formed rule", () => {
+    const rule = when<TestSymptom>(eq("status", "drifted"), run("fountain-apply"), {
+      id: "drift-apply",
+      why: "Re-apply on drift.",
+    });
+    expect(rule).toEqual({
+      id: "drift-apply",
+      when: { kind: "field-comparison", field: "status", op: "eq", value: "drifted" },
+      then: { kind: "run", op: "fountain-apply" },
+      why: "Re-apply on drift.",
+    });
+  });
+
+  test("throws without an id", () => {
+    expect(() => when<TestSymptom>(eq("status", "drifted"), run("x"), { id: "", why: "because" })).toThrow(/non-empty `id`/);
+  });
+
+  test("throws without a why", () => {
+    expect(() => when<TestSymptom>(eq("status", "drifted"), run("x"), { id: "r1", why: "" })).toThrow(/carry its `why`/);
+  });
+
+  test("throws without a why (whitespace only)", () => {
+    expect(() => when<TestSymptom>(eq("status", "drifted"), run("x"), { id: "r1", why: "   " })).toThrow(/carry its `why`/);
+  });
+
+  test("throws on a non-positive-integer flapThreshold", () => {
+    expect(() => when<TestSymptom>(eq("status", "drifted"), run("x"), { id: "r1", why: "y", flapThreshold: 0 })).toThrow(/flapThreshold/);
+    expect(() => when<TestSymptom>(eq("status", "drifted"), run("x"), { id: "r1", why: "y", flapThreshold: 1.5 })).toThrow(/flapThreshold/);
+  });
+
+  test("flapThreshold defaults are left to the caller (DEFAULT_FLAP_THRESHOLD is exported for that)", () => {
+    expect(DEFAULT_FLAP_THRESHOLD).toBeGreaterThan(0);
+    const rule = when<TestSymptom>(eq("status", "drifted"), run("x"), { id: "r1", why: "y" });
+    expect(rule.flapThreshold).toBeUndefined();
+  });
+});
+
+describe("duplicateRuleIds", () => {
+  test("empty when every id is unique", () => {
+    const rules = [
+      when<TestSymptom>(eq("status", "a"), report("x"), { id: "r1", why: "y" }),
+      when<TestSymptom>(eq("status", "b"), report("x"), { id: "r2", why: "y" }),
+    ];
+    expect(duplicateRuleIds(rules)).toEqual([]);
+  });
+
+  test("reports every id used more than once, sorted", () => {
+    const rules = [
+      when<TestSymptom>(eq("status", "a"), report("x"), { id: "r2", why: "y" }),
+      when<TestSymptom>(eq("status", "b"), report("x"), { id: "r1", why: "y" }),
+      when<TestSymptom>(eq("status", "c"), report("x"), { id: "r1", why: "y" }),
+      when<TestSymptom>(eq("status", "d"), report("x"), { id: "r2", why: "y" }),
+    ];
+    expect(duplicateRuleIds(rules)).toEqual(["r1", "r2"]);
+  });
+});

package/src/op/converge-rule.ts

@@ -0,0 +1,311 @@
+/**
+ * Converge rules (#1484) — the typed, JSON-serializable predicate language a
+ * `ConvergeOp` rule table is built from.
+ *
+ * The issue's illustrative sketch writes a rule's condition as a JS arrow
+ * function (`s => s.status === "drifted"`). That reads well but can't
+ * actually ship: a rule is evaluated per-tick against live, freshly-observed
+ * data inside a Temporal activity, and an activity's arguments — including
+ * whatever a `ConvergeOp` composite bakes into its generated workflow — must
+ * be plain JSON (see `step-output-ref.ts`'s module doc on why a value
+ * crossing the workflow/activity boundary can't carry a closure). A rule
+ * "outside the evaluable subset" is one of the build-time refusals #1484
+ * names explicitly, which only makes sense if there IS an evaluable subset
+ * to be outside of — so rules here are data: a small comparison language
+ * over one typed symptom record, interpreted by {@link evaluatePredicate}
+ * (pure, no I/O, matching Accessible Ops factor I — "predictable from the
+ * text alone").
+ *
+ * `S` is the symptom record type a `ConvergeOp` instance evaluates against
+ * (`ConvergeSymptom`, ../lifecycle/symptoms.ts, for the real thing — kept
+ * generic here so the predicate language and its tests don't depend on the
+ * lifecycle package). Since a predicate's `field` is typed `keyof S`, a rule
+ * that names a field the symptom record doesn't have is refused by
+ * TypeScript itself at the author's call site — the "symptom field nothing
+ * produces" refusal, satisfied for free. {@link isWellFormedPredicate} is the
+ * runtime backstop for a rule assembled by hand (bypassing `when()`/the
+ * comparison builders) rather than authored through them, and is what a
+ * build-time check (TMP014) re-validates the serialized rule table against.
+ */
+
+// ── Predicates ───────────────────────────────────────────────────────────────
+
+/** Comparison operators over a single symptom field. */
+export type FieldComparisonOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte";
+
+/** Truthiness operators over a single symptom field — no `value` needed. */
+export type FieldTruthinessOp = "truthy" | "falsy";
+
+export interface FieldComparisonPredicate<S> {
+  kind: "field-comparison";
+  field: keyof S & string;
+  op: FieldComparisonOp;
+  value: string | number | boolean;
+}
+
+export interface FieldTruthinessPredicate<S> {
+  kind: "field-truthiness";
+  field: keyof S & string;
+  op: FieldTruthinessOp;
+}
+
+export interface AllOfPredicate<S> {
+  kind: "all-of";
+  predicates: SymptomPredicate<S>[];
+}
+
+export interface AnyOfPredicate<S> {
+  kind: "any-of";
+  predicates: SymptomPredicate<S>[];
+}
+
+/**
+ * A rule's `when` — the evaluable subset #1484 requires: field comparisons
+ * and truthiness checks over `S`, composed with `allOf`/`anyOf`. Every
+ * variant is plain JSON; there is deliberately no escape hatch to an
+ * arbitrary expression.
+ */
+export type SymptomPredicate<S> =
+  | FieldComparisonPredicate<S>
+  | FieldTruthinessPredicate<S>
+  | AllOfPredicate<S>
+  | AnyOfPredicate<S>;
+
+const FIELD_COMPARISON_OPS: ReadonlySet<string> = new Set(["eq", "neq", "gt", "gte", "lt", "lte"]);
+const FIELD_TRUTHINESS_OPS: ReadonlySet<string> = new Set(["truthy", "falsy"]);
+
+/**
+ * Structural validator for a value claiming to be a {@link SymptomPredicate}
+ * — the runtime backstop `TMP014` (lexicons/temporal's post-synth check)
+ * re-checks a serialized rule table against, since nothing forces a rule
+ * assembled by hand (rather than through the builders below) to match this
+ * shape. Recurses through `allOf`/`anyOf`; `fieldWhitelist`, when given,
+ * additionally refuses a field name the symptom record doesn't actually
+ * produce (defense in depth over TypeScript's `keyof S` check, which only
+ * applies at the author's original call site — not to a rule table replayed
+ * from JSON).
+ */
+export function isWellFormedPredicate(value: unknown, fieldWhitelist?: ReadonlySet<string>): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  switch (v.kind) {
+    case "field-comparison":
+      return (
+        typeof v.field === "string" &&
+        (!fieldWhitelist || fieldWhitelist.has(v.field)) &&
+        typeof v.op === "string" &&
+        FIELD_COMPARISON_OPS.has(v.op) &&
+        (typeof v.value === "string" || typeof v.value === "number" || typeof v.value === "boolean")
+      );
+    case "field-truthiness":
+      return (
+        typeof v.field === "string" &&
+        (!fieldWhitelist || fieldWhitelist.has(v.field)) &&
+        typeof v.op === "string" &&
+        FIELD_TRUTHINESS_OPS.has(v.op)
+      );
+    case "all-of":
+    case "any-of":
+      return Array.isArray(v.predicates) && v.predicates.every((p) => isWellFormedPredicate(p, fieldWhitelist));
+    default:
+      return false;
+  }
+}
+
+/** Evaluate a {@link SymptomPredicate} against a symptom record. Pure — no I/O, no ambient reads. */
+export function evaluatePredicate<S>(predicate: SymptomPredicate<S>, symptom: S): boolean {
+  switch (predicate.kind) {
+    case "field-comparison": {
+      const actual = symptom[predicate.field];
+      switch (predicate.op) {
+        case "eq":
+          return actual === predicate.value;
+        case "neq":
+          return actual !== predicate.value;
+        case "gt":
+          return typeof actual === "number" && typeof predicate.value === "number" && actual > predicate.value;
+        case "gte":
+          return typeof actual === "number" && typeof predicate.value === "number" && actual >= predicate.value;
+        case "lt":
+          return typeof actual === "number" && typeof predicate.value === "number" && actual < predicate.value;
+        case "lte":
+          return typeof actual === "number" && typeof predicate.value === "number" && actual <= predicate.value;
+      }
+      break;
+    }
+    case "field-truthiness": {
+      const actual = symptom[predicate.field];
+      return predicate.op === "truthy" ? !!actual : !actual;
+    }
+    case "all-of":
+      return predicate.predicates.every((p) => evaluatePredicate(p, symptom));
+    case "any-of":
+      return predicate.predicates.some((p) => evaluatePredicate(p, symptom));
+  }
+  // Unreachable for a well-formed predicate; a malformed one (bypassing the
+  // builders and isWellFormedPredicate) never matches rather than throwing
+  // mid-tick — the build-time check is what refuses it before this runs.
+  return false;
+}
+
+/**
+ * Does a predicate reference the given symptom field anywhere in it,
+ * recursing through `allOf`/`anyOf`? The build-time backstop for a claim
+ * about a *category* of rule (e.g. "a rule reading `adoptCount`") rather
+ * than a single comparison — `TMP014`'s adopt-safety check
+ * (../../../lexicons/temporal/src/lint/post-synth/tmp014-converge-rule-refusals.ts)
+ * uses this to refuse a rule that both reads `adoptCount` and dispatches a
+ * mutating op, rather than merely documenting that authors shouldn't write
+ * one.
+ */
+export function predicateReferencesField<S>(predicate: SymptomPredicate<S>, field: string): boolean {
+  switch (predicate.kind) {
+    case "field-comparison":
+    case "field-truthiness":
+      return predicate.field === field;
+    case "all-of":
+    case "any-of":
+      return predicate.predicates.some((p) => predicateReferencesField(p, field));
+  }
+}
+
+// ── Predicate builders ──────────────────────────────────────────────────────
+
+export function eq<S>(field: keyof S & string, value: string | number | boolean): FieldComparisonPredicate<S> {
+  return { kind: "field-comparison", field, op: "eq", value };
+}
+export function neq<S>(field: keyof S & string, value: string | number | boolean): FieldComparisonPredicate<S> {
+  return { kind: "field-comparison", field, op: "neq", value };
+}
+export function gt<S>(field: keyof S & string, value: number): FieldComparisonPredicate<S> {
+  return { kind: "field-comparison", field, op: "gt", value };
+}
+export function gte<S>(field: keyof S & string, value: number): FieldComparisonPredicate<S> {
+  return { kind: "field-comparison", field, op: "gte", value };
+}
+export function lt<S>(field: keyof S & string, value: number): FieldComparisonPredicate<S> {
+  return { kind: "field-comparison", field, op: "lt", value };
+}
+export function lte<S>(field: keyof S & string, value: number): FieldComparisonPredicate<S> {
+  return { kind: "field-comparison", field, op: "lte", value };
+}
+export function truthy<S>(field: keyof S & string): FieldTruthinessPredicate<S> {
+  return { kind: "field-truthiness", field, op: "truthy" };
+}
+export function falsy<S>(field: keyof S & string): FieldTruthinessPredicate<S> {
+  return { kind: "field-truthiness", field, op: "falsy" };
+}
+export function allOf<S>(...predicates: SymptomPredicate<S>[]): AllOfPredicate<S> {
+  return { kind: "all-of", predicates };
+}
+export function anyOf<S>(...predicates: SymptomPredicate<S>[]): AnyOfPredicate<S> {
+  return { kind: "any-of", predicates };
+}
+
+// ── Actions ──────────────────────────────────────────────────────────────────
+
+/**
+ * Dispatch a declared Op by name. `chant run <op>` — the existing local
+ * runner (../op's `runOpLocally` under the hood via the CLI) — takes no
+ * caller-supplied arguments today, so a dispatched Op reads whatever it
+ * needs from its own declared `env`/config rather than from this rule.
+ */
+export interface RunAction {
+  kind: "run";
+  op: string;
+}
+
+/**
+ * Report only — never a mutation. The log-and-ledger channel is the only one
+ * v1 implements (issue open question 5): reusing `ReconcileOp`'s
+ * `onDrift: "pull-request" | "issue" | "report"` channels is "obviously
+ * right" per the issue, but wiring `pull-request`/`issue` through requires
+ * the same reconcile plumbing `ReconcileOp` already owns — out of scope for
+ * the smallest honest `ConvergeOp`. A future `channel` field can extend this
+ * without a shape change.
+ */
+export interface ReportAction {
+  kind: "report";
+  reason: string;
+}
+
+export type RuleAction = RunAction | ReportAction;
+
+export function run(op: string): RunAction {
+  return { kind: "run", op };
+}
+
+export function report(reason: string): ReportAction {
+  return { kind: "report", reason };
+}
+
+// ── Rules ────────────────────────────────────────────────────────────────────
+
+/** A rule table's default flap-damping threshold (issue: "with a default"). */
+export const DEFAULT_FLAP_THRESHOLD = 3;
+
+/**
+ * One rule: a symptom predicate, the action to take when it matches, and its
+ * mandatory rationale. "Every rule carries its why" (Accessible Ops factor
+ * III) — `why` is a required field, not an optional one, and `when()` below
+ * throws at construction (build time — the same "throw in the factory" shape
+ * `ApplyOp`'s `compensate` refusal already uses) if it's missing or blank.
+ */
+export interface ConvergeRule<S> {
+  /** Stable identifier — used for flap-damping counters, so it must not change across a rule's lifetime just because the table was reordered. */
+  id: string;
+  when: SymptomPredicate<S>;
+  then: RuleAction;
+  /** Why this rule exists — refused at build if blank. */
+  why: string;
+  /** Consecutive ticks the symptom may fire before this rule escalates to report-and-stop. @default {@link DEFAULT_FLAP_THRESHOLD} */
+  flapThreshold?: number;
+}
+
+/**
+ * Declare one converge rule. Throws immediately (build time — this runs
+ * while `chant build` evaluates the authoring `*.op.ts` file, exactly like
+ * `ApplyOp`'s `compensate` refusal) when `id` or `why` is missing or blank,
+ * or `flapThreshold` isn't a positive integer.
+ *
+ * @example
+ * ```ts
+ * when(eq("status", "drifted"), run("fountain-apply"), {
+ *   id: "drift-apply",
+ *   why: "Live config drifted from declared source; re-apply converges it back.",
+ * })
+ * ```
+ */
+export function when<S>(
+  predicate: SymptomPredicate<S>,
+  action: RuleAction,
+  opts: { id: string; why: string; flapThreshold?: number },
+): ConvergeRule<S> {
+  if (!opts.id || opts.id.trim().length === 0) {
+    throw new Error("when(): a rule must have a non-empty `id` (used for flap-damping and diagnostics)");
+  }
+  if (!opts.why || opts.why.trim().length === 0) {
+    throw new Error(`when("${opts.id}"): a rule must carry its \`why\` — every rule's rationale is required, refused at build otherwise`);
+  }
+  if (opts.flapThreshold !== undefined && (!Number.isInteger(opts.flapThreshold) || opts.flapThreshold < 1)) {
+    throw new Error(`when("${opts.id}"): flapThreshold must be a positive integer`);
+  }
+  return {
+    id: opts.id,
+    when: predicate,
+    then: action,
+    why: opts.why,
+    ...(opts.flapThreshold !== undefined ? { flapThreshold: opts.flapThreshold } : {}),
+  };
+}
+
+/** Every rule id in a table must be unique — flap-damping counters and dispatch/report accounting are keyed by id. */
+export function duplicateRuleIds<S>(rules: ConvergeRule<S>[]): string[] {
+  const seen = new Set<string>();
+  const dupes = new Set<string>();
+  for (const r of rules) {
+    if (seen.has(r.id)) dupes.add(r.id);
+    seen.add(r.id);
+  }
+  return [...dupes].sort();
+}

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" }]);
+  });
+});