@intentius/chant 0.46.0 → 0.50.0

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