@intentius/chant 0.57.0 → 0.59.0

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

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

@@ -0,0 +1,214 @@
+/**
+ * ConvergeOp composite (#1484, epic #1487 feature 1) — the executable
+ * runbook. Observe, classify against a typed rule table, dispatch to
+ * declared ops within a per-tick budget, record, rest. Peer to `WatchOp` /
+ * `ReconcileOp` / `ApplyOp` — same `{ op }` shape, with the cadence on the
+ * Op itself (#2120).
+ *
+ * Phases: `Observe` (snapshot + a quick live diff, exactly `WatchOp`'s own
+ * shape, for the `Drift` outcome and per-phase visibility) ->
+ * `Converge` (one `convergeTick` activity call —
+ * ../activities/converge.ts — that does classify + dispatch + record;
+ * see that module's doc for why this can't be split into further static
+ * phases). `Observe`'s drift signal threads into `Converge`'s args via a
+ * step-output reference (#1290), not a search-attribute round-trip.
+ *
+ * @example
+ * ```typescript
+ * import { ConvergeOp, eq, gt, run, report, when } from "@intentius/chant/op";
+ * import type { ConvergeSymptom } from "@intentius/chant/lifecycle/symptoms";
+ *
+ * export const { op } = ConvergeOp({
+ *   name: "fountain-converge",
+ *   env: "staging",
+ *   dial: "apply",
+ *   schedule: "*\/10 * * * *",
+ *   rules: [
+ *     when<ConvergeSymptom>(eq("status", "drifted"), run("fountain-apply"), {
+ *       id: "drift-apply",
+ *       why: "Live config drifted from declared source; re-apply converges it back.",
+ *     }),
+ *     when<ConvergeSymptom>(gt("adoptCount", 0), report("unowned resources present"), {
+ *       id: "adopt-report",
+ *       why: "An unowned resource is reported for a human to review — never auto-claimed.",
+ *     }),
+ *     when<ConvergeSymptom>(eq("status", "unknown"), report("environment could not be fully observed"), {
+ *       id: "unknown-report",
+ *       why: "unknown never remediates — a partial read is a hole to report, not a guess to act on.",
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @see #1484, #1487
+ */
+
+import { Op, phase, activity } from "../builders";
+import type { OpResource } from "../resource";
+import { isWellFormedPredicate, duplicateRuleIds, type ConvergeRule } from "../converge-rule";
+import type { ConvergeSymptom } from "../../lifecycle/symptoms";
+import { CONVERGE_SYMPTOM_FIELDS } from "../../lifecycle/symptoms";
+
+/**
+ * Authority level for this ConvergeOp's environment — issue #1484's own
+ * Autonomy table (dial × verb class):
+ *
+ * | verb class  | observe     | reconcile        | apply                 |
+ * |-------------|-------------|------------------|------------------------|
+ * | read-only   | free-run    | free-run         | free-run               |
+ * | mutating    | report only | open PR          | run, gated per op      |
+ * | destructive | refused     | refused          | always gated           |
+ *
+ * `ConvergeOp` adds no authority an environment did not already grant.
+ * Default `"observe"` — not autonomous by default (issue: "a ConvergeOp in
+ * an observe environment is a report generator").
+ *
+ * **v1 implements a conservative subset of this table**, not the whole
+ * thing (pre-merge review of #1954 caught the gap between what the code did
+ * and what this table says — this doc now matches the issue, and the code
+ * matches this doc):
+ *
+ * | verb class  | observe     | reconcile                          | apply                              |
+ * |-------------|-------------|-------------------------------------|--------------------------------------|
+ * | read-only   | free-run    | free-run                            | free-run                             |
+ * | mutating    | report only | **refused at build (OPS014)**       | run                                   |
+ * | destructive | refused     | refused                              | **refused at build (OPS014), v1**   |
+ *
+ * - **`reconcile` × mutating is "open PR" in the issue's table — not yet
+ *   implemented.** Building that channel (reusing `ReconcileOp`'s
+ *   `onDrift: "pull-request" | "issue" | "report"`) is out of v1 scope — see
+ *   `../converge-rule.ts`'s `ReportAction` doc and epic #1487's
+ *   onDrift-channel open question. Until it exists, a rule that would
+ *   dispatch a mutating op under `reconcile` is refused at build
+ *   (`OPS014`), not silently escalated to "run directly" the way `apply`
+ *   would. A runtime backstop in `convergeTick`
+ *   (`../activities/converge.ts`) re-checks the same thing at dispatch
+ *   time, for a rule table that reached the tick without going through that
+ *   build.
+ * - **`apply` × destructive is refused outright in v1, gate or not.** The
+ *   issue's table says "always gated", but the dispatch executor can't
+ *   honor a gate: `dispatchOp` shells `chant run <op>`, and a gated run ends
+ *   pending approval (#2119) rather than continuing — so
+ *   "destructive + apply + gated" reads as a path to dispatch but was a
+ *   dead cell: it could never actually succeed. `OPS014` refuses the rule
+ *   instead of shipping a path guaranteed to fail every time it's exercised.
+ *   Gated dispatch that waits for the approval is #1485's design to own.
+ */
+export type ConvergeDial = "observe" | "reconcile" | "apply";
+
+export interface ConvergeOpConfig {
+  /** Op name (kebab-case). Names the Op's output directory and is what `chant run` takes. */
+  name: string;
+  /** Environment to converge (e.g. "staging"). */
+  env: string;
+  /** @default "observe" */
+  dial?: ConvergeDial;
+  /** Max number of `run` dispatches per tick — the issue's "the worst tick is bounded" (Accessible Ops factor VI). Rules matched beyond the budget are recorded, not run. @default 3 */
+  budget?: number;
+  /** The rule table — build with `when()`/`eq()`/`run()`/`report()` from `@intentius/chant/op`. Non-empty; every rule id must be unique. */
+  rules: ConvergeRule<ConvergeSymptom>[];
+  /**
+   * Cron expression. When set, it lands on the Op as `schedule` — the cadence
+   * `chant operator` ticks this Op on and the CI generators render; omit for
+   * one-shot `chant run` on the local executor, also the test story (issue:
+   * "one-shot runnable locally for a single tick").
+   */
+  schedule?: string;
+  /** Run `chant lifecycle diff --live` in the Observe phase (queries live state). @default true */
+  live?: boolean;
+}
+
+export interface ConvergeOpResources {
+  /** Op resource — the observe-then-converge Op. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function ConvergeOp(config: ConvergeOpConfig): ConvergeOpResources {
+  const dial = config.dial ?? "observe";
+  const budget = config.budget ?? 3;
+  const live = config.live ?? true;
+
+  // ── Build-time refusals (#1484) ─────────────────────────────────────────
+  // Thrown here, at Op-construction time — the same "refuse in the factory,
+  // named, before anything runs" shape ApplyOp's `compensate` check already
+  // uses. Cross-Op refusals that need the *whole* discovered graph (an
+  // unknown op referenced by `run()`, a mutating/destructive dispatch target
+  // whose own verb class the dial disallows) can't be checked here — a
+  // sibling `*.op.ts` file's Op may not exist yet at the moment this factory
+  // runs — and are instead OPS014's job
+  // (../../lint/rules/op/ops014-converge-rule-refusals.ts), which runs after
+  // the whole project is resolved.
+
+  if (config.rules.length === 0) {
+    throw new Error(`ConvergeOp "${config.name}": at least one rule is required — an empty table has nothing to converge.`);
+  }
+  const dupes = duplicateRuleIds(config.rules);
+  if (dupes.length > 0) {
+    throw new Error(
+      `ConvergeOp "${config.name}": duplicate rule id(s) [${dupes.join(", ")}] — flap-damping counters are keyed by id, so ids must be unique.`,
+    );
+  }
+  if (!Number.isInteger(budget) || budget < 0) {
+    throw new Error(`ConvergeOp "${config.name}": budget must be a non-negative integer, got ${budget}`);
+  }
+  for (const rule of config.rules) {
+    if (!rule.why || rule.why.trim().length === 0) {
+      // Belt-and-suspenders: when() already refuses this, but a rule table
+      // assembled by hand (bypassing when()) reaches here too.
+      throw new Error(`ConvergeOp "${config.name}", rule "${rule.id}": every rule must carry its why — refused at build.`);
+    }
+    if (!isWellFormedPredicate(rule.when, CONVERGE_SYMPTOM_FIELDS)) {
+      throw new Error(
+        `ConvergeOp "${config.name}", rule "${rule.id}": predicate is outside the evaluable subset — build it from ` +
+          `eq/neq/gt/gte/lt/lte/truthy/falsy/allOf/anyOf over a field ConvergeSymptom actually produces.`,
+      );
+    }
+  }
+
+  const snapshotStep = activity("lifecycleSnapshot", { env: config.env }, { id: "snapshot" });
+  const diffStep = activity("lifecycleDiff", { env: config.env, live }, { id: "diff", profile: "fastIdempotent" });
+  diffStep.outcomeAttribute = { name: "Drift", from: "drifted" };
+
+  // convergeTick's args are the rule table itself — too shaped (recursive
+  // predicates, a discriminated action union) for a hand-mirrored zod
+  // contract to earn its keep, the same "deliberately partial" call
+  // activity-contracts.ts already makes for kubectlApply/helmInstall's
+  // multi-field args. OPS012 skips an uncontracted `fn`, not flags it — see
+  // that module's doc. The `preflightDrift` step-output reference below is
+  // still fully validated: OPS013's producer-side checks only need
+  // `lifecycleDiff`'s own contract, which is registered.
+  const tickStep = activity(
+    "convergeTick",
+    {
+      opName: config.name,
+      env: config.env,
+      dial,
+      budget,
+      rules: config.rules,
+      preflightDrift: diffStep.out.drifted,
+    },
+    "longInfra",
+  );
+  tickStep.outcomeAttribute = { name: "Remediated", from: "remediated" };
+
+  const op = Op({
+    name: config.name,
+    overview: `Converge the ${config.env} environment toward its declaration (dial: ${dial})`,
+    labels: {
+      Converge: "true",
+      Env: config.env,
+      Dial: dial,
+    },
+    // Overlap (#1484 acceptance criterion: "skip-and-report when a prior
+    // remediation is in flight ... never queue"). `"skip"` is the only value
+    // `OpSchedule` has, and it means exactly that: a fire arriving while the
+    // previous tick still runs is dropped rather than queued or run
+    // alongside. There is no per-tick "in flight" ledger record for the
+    // skipped fire to produce — nothing ran, so nothing observed, classified,
+    // or dispatched.
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [phase("Observe", [snapshotStep, diffStep]), phase("Converge", [tickStep])],
+  });
+
+  return { op };
+}

package/src/op/composites/index.ts

@@ -0,0 +1,26 @@
+/**
+ * The Op composites (#2120) — the named verbs an operator authors instead of
+ * hand-writing phases: watch, reconcile, apply, converge, and the three audit
+ * runners.
+ *
+ * They lived in a hosting lexicon while a cadence meant a scheduler resource;
+ * now that the cadence is `OpConfig.schedule` they are runtime-neutral, each
+ * returns `{ op }`, and nothing here imports a hosting lexicon. A project that
+ * wants a real scheduler resource pairs one with the Op by hand (the pattern
+ * `lexicons/cedar/src/dogwood/replay-op.ts` documents).
+ */
+
+export { WatchOp } from "./watch-op";
+export type { WatchOpConfig, WatchOpResources } from "./watch-op";
+export { ReconcileOp } from "./reconcile-op";
+export type { ReconcileOpConfig, ReconcileOpResources } from "./reconcile-op";
+export { ApplyOp } from "./apply-op";
+export type { ApplyOpConfig, ApplyOpResources } from "./apply-op";
+export { ConvergeOp } from "./converge-op";
+export type { ConvergeOpConfig, ConvergeOpResources, ConvergeDial } from "./converge-op";
+export { WorkflowAuditOp } from "./workflow-audit-op";
+export type { WorkflowAuditOpConfig, WorkflowAuditOpResources } from "./workflow-audit-op";
+export { PipelineAuditOp } from "./pipeline-audit-op";
+export type { PipelineAuditOpConfig, PipelineAuditOpResources } from "./pipeline-audit-op";
+export { LexiconUpgradeOp, IN_SCOPE_LEXICONS } from "./lexicon-upgrade-op";
+export type { LexiconUpgradeOpConfig, LexiconUpgradeOpResources } from "./lexicon-upgrade-op";

package/src/op/composites/lexicon-upgrade-op.test.ts

@@ -0,0 +1,68 @@
+import { describe, test, expect } from "vitest";
+import { LexiconUpgradeOp, IN_SCOPE_LEXICONS } from "./lexicon-upgrade-op";
+
+describe("LexiconUpgradeOp composite (#527)", () => {
+  test("one-shot form: op only, no cadence", () => {
+    const { op } = LexiconUpgradeOp({ lexicon: "aws" });
+    expect(op).toBeDefined();
+    expect((op as unknown as { props: { schedule?: unknown } }).props.schedule).toBeUndefined();
+  });
+
+  test("default name is <lexicon>-upgrade", () => {
+    const { op } = LexiconUpgradeOp({ lexicon: "k8s" });
+    const cfg = (op as unknown as { props: { name: string } }).props;
+    expect(cfg.name).toBe("k8s-upgrade");
+  });
+
+  test("dispatches through the lexiconUpgrade activity with the lexicon + mode", () => {
+    const { op } = LexiconUpgradeOp({ lexicon: "gitlab", onFinding: "pull-request" });
+    const config = (op as unknown as { props: Record<string, unknown> }).props;
+    const phases = config.phases as Array<{ steps: Array<Record<string, unknown>> }>;
+    const step = phases[0].steps[0];
+    expect(step.fn).toBe("lexiconUpgrade");
+    expect((step.args as { lexicon: string }).lexicon).toBe("gitlab");
+    expect((step.args as { mode: string }).mode).toBe("pull-request");
+  });
+
+  test("report is the default finding mode", () => {
+    const { op } = LexiconUpgradeOp({ lexicon: "azure" });
+    const config = (op as unknown as { props: Record<string, unknown> }).props;
+    const phases = config.phases as Array<{ steps: Array<{ args: { mode: string } }> }>;
+    expect(phases[0].steps[0].args.mode).toBe("report");
+  });
+
+  test("scheduled form: the weekly cron rides on the op (#2120)", () => {
+    const { op } = LexiconUpgradeOp({
+      lexicon: "k8s",
+      schedule: "0 6 * * 1",
+      onFinding: "pull-request",
+    });
+    const config = (op as unknown as { props: Record<string, unknown> }).props;
+    expect(config.name).toBe("k8s-upgrade");
+    expect(config.schedule).toEqual({ cron: "0 6 * * 1", overlap: "skip" });
+  });
+
+  test("surfaces HasUpgrade as a run outcome attribute", () => {
+    const { op } = LexiconUpgradeOp({ lexicon: "docker" });
+    const config = (op as unknown as { props: Record<string, unknown> }).props;
+    const phases = config.phases as Array<{ steps: Array<{ outcomeAttribute?: { name: string; from: string } }> }>;
+    expect(phases[0].steps[0].outcomeAttribute).toEqual({ name: "HasUpgrade", from: "hasUpgrade" });
+  });
+
+  test("in-scope set is exactly the 9 lexicons (helm/forgejo excluded)", () => {
+    // cedar joined with #1650: it pins `CEDAR_WASM_VERSION`, a dependency
+    // rather than a downloaded spec, but the pinned-constant machinery the Op
+    // drives is identical. helm/forgejo still have no upstream at all.
+    expect([...IN_SCOPE_LEXICONS].sort()).toEqual(
+      ["aws", "azure", "cedar", "docker", "fly", "gcp", "github", "gitlab", "k8s"].sort(),
+    );
+    expect(IN_SCOPE_LEXICONS).not.toContain("helm");
+    expect(IN_SCOPE_LEXICONS).not.toContain("forgejo");
+  });
+
+  test("rejects out-of-scope lexicons at construction", () => {
+    for (const l of ["helm", "forgejo"]) {
+      expect(() => LexiconUpgradeOp({ lexicon: l as never })).toThrow(/not in scope/);
+    }
+  });
+});

package/src/op/composites/lexicon-upgrade-op.ts

@@ -0,0 +1,134 @@
+/**
+ * LexiconUpgradeOp composite — the runner that dogfoods chant to keep each
+ * in-scope lexicon current with its upstream spec (#527, epic #523).
+ *
+ * The shared tooling (#524) does the regen + surface-diff; the pinned (#525)
+ * and rolling (#526) pipelines do the detection. This Op wires them into an
+ * audit-style operational layer, modeled on `WorkflowAuditOp` / `PipelineAuditOp`:
+ * phases detect → run the right check for the lexicon → surface-diff → finding.
+ *
+ * It runs one-shot on the **local Op executor** via `chant run` — nothing
+ * durable is required for an upgrade check (the scheduled CI runner is the
+ * trigger). A `schedule` may still be supplied for continuous re-check; it
+ * lands on the Op itself (#2120).
+ *
+ * Lexicon classification (which check the activity dispatches to):
+ *   PINNED  {k8s, gcp, docker, gitlab} → checkPinnedUpgrade
+ *   ROLLING {aws, azure, github}       → checkRollingUpgrade
+ * helm / forgejo are excluded — no upstream spec.
+ *
+ * Finding-modes mirror ReconcileOp: `report` (default, no external services)
+ * | `issue` | `pull-request`. For the epic goal, `pull-request` opens/updates a
+ * long-lived branch per lexicon.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor, report only
+ * export const { op } = LexiconUpgradeOp({ lexicon: "aws" });
+ *
+ * // weekly, opening a PR when an upgrade is ready
+ * export const { op } = LexiconUpgradeOp({
+ *   lexicon: "k8s",
+ *   schedule: "0 6 * * 1",
+ *   onFinding: "pull-request",
+ * });
+ * ```
+ *
+ * @see #524 — shared regen-validate + surface-diff tooling.
+ * @see #525 — pinned-version bump pipeline.
+ * @see #526 — rolling-spec drift pipeline.
+ */
+
+import { Op, phase } from "../builders";
+import type { OpResource } from "../resource";
+import type { LexiconUpgradeMode, SupportedLexicon } from "../activities/lexicon-upgrade";
+
+/** The in-scope lexicons. helm / forgejo are excluded (no upstream spec). */
+export const IN_SCOPE_LEXICONS: readonly SupportedLexicon[] = [
+  "k8s",
+  "gcp",
+  "docker",
+  "gitlab",
+  "aws",
+  "azure",
+  "github",
+  "fly",
+  "cedar",
+] as const;
+
+export interface LexiconUpgradeOpConfig {
+  /** Which in-scope lexicon to check. */
+  lexicon: SupportedLexicon;
+  /**
+   * Op name (kebab-case). Names the Op's output directory and is what `chant
+   * run` takes. Defaults to `<lexicon>-upgrade`.
+   */
+  name?: string;
+  /**
+   * Cron expression. When set, it lands on the Op as `schedule` for
+   * continuous re-check; omit for one-shot `chant run` on the local executor.
+   */
+  schedule?: string;
+  /**
+   * Absolute path to the lexicon root, forwarded to the activity. Defaults to
+   * `<cwd>/lexicons/<lexicon>` at run time.
+   */
+  lexiconDir?: string;
+  /**
+   * What to produce on findings. Default: "report".
+   * @default "report"
+   */
+  onFinding?: LexiconUpgradeMode;
+}
+
+export interface LexiconUpgradeOpResources {
+  /** Op resource — the upgrade Op, emitted on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+}
+
+/**
+ * Build a LexiconUpgradeOp for one lexicon. Rejects out-of-scope lexicons at
+ * construction time so a typo never silently produces a no-op Op.
+ */
+export function LexiconUpgradeOp(config: LexiconUpgradeOpConfig): LexiconUpgradeOpResources {
+  if (!IN_SCOPE_LEXICONS.includes(config.lexicon)) {
+    throw new Error(
+      `LexiconUpgradeOp: "${config.lexicon}" is not in scope. ` +
+        `In-scope lexicons: ${IN_SCOPE_LEXICONS.join(", ")} ` +
+        `(helm, forgejo have no upstream spec).`,
+    );
+  }
+
+  const name = config.name ?? `${config.lexicon}-upgrade`;
+  const onFinding = config.onFinding ?? "report";
+
+  const op = Op({
+    name,
+    overview:
+      "Detect a newer upstream spec for the lexicon, regen + validate, and surface the API-surface delta",
+    labels: {
+      Upgrade: "true",
+      Lexicon: config.lexicon,
+    },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [
+      phase("Upgrade", [
+        {
+          kind: "activity",
+          fn: "lexiconUpgrade",
+          args: {
+            lexicon: config.lexicon,
+            ...(config.lexiconDir ? { lexiconDir: config.lexiconDir } : {}),
+            mode: onFinding,
+          },
+          // Surface whether a PR-worthy upgrade was found as the run's
+          // `HasUpgrade` outcome on the run ledger, so a reader can pick out
+          // the lexicons with an upgrade ready.
+          outcomeAttribute: { name: "HasUpgrade", from: "hasUpgrade" },
+        },
+      ]),
+    ],
+  });
+
+  return { op };
+}

package/src/op/composites/pipeline-audit-op.test.ts

@@ -0,0 +1,25 @@
+import { describe, test, expect } from "vitest";
+import { PipelineAuditOp } from "./pipeline-audit-op";
+
+function opProps(op: unknown): Record<string, unknown> {
+  return (op as { props: Record<string, unknown> }).props;
+}
+
+describe("PipelineAuditOp composite (#303)", () => {
+  test("one-shot form: op only, no cadence", () => {
+    const { op } = PipelineAuditOp({ name: "pipeline-audit" });
+    expect(op).toBeDefined();
+    expect(opProps(op).schedule).toBeUndefined();
+  });
+
+  test("scheduled form: the cron rides on the op, with the merge-request finding mode (#2120)", () => {
+    const { op } = PipelineAuditOp({
+      name: "pipeline-audit",
+      schedule: "0 6 * * *",
+      onFinding: "merge-request",
+    });
+    expect(opProps(op).schedule).toEqual({ cron: "0 6 * * *", overlap: "skip" });
+    const step = (opProps(op).phases as Array<{ steps: Array<{ args: { mode: string } }> }>)[0].steps[0];
+    expect(step.args.mode).toBe("merge-request");
+  });
+});