@intentius/chant 0.57.0 → 0.58.0

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

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

@@ -0,0 +1,78 @@
+/**
+ * PipelineAuditOp composite — the live include/component audit of GitLab
+ * pipelines as a chant Op with an optional schedule (#303).
+ *
+ * The gitlab post-synth checks (#297) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — a pinned component/include ref
+ * that no longer resolves, an archived or moved upstream project, or a new
+ * advisory covering a component/image in use. It sits at **observe** on the
+ * lifecycle dial, with a finding-mode (`report | issue | merge-request`) as the
+ * **reconcile** step — for GitLab the PR mode is a merge request.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; a `schedule` puts
+ * the cadence on the Op itself (#2120).
+ *
+ * @example
+ * ```typescript
+ * export const { op } = PipelineAuditOp({
+ *   name: "pipeline-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "merge-request",
+ * });
+ * ```
+ *
+ * @see #297 — the deterministic counterpart this freshens.
+ */
+
+import { Op, phase } from "../builders";
+import type { OpResource } from "../resource";
+import type { PipelineAuditMode } from "../activities/pipeline-audit";
+
+export interface PipelineAuditOpConfig {
+  /** Op name (kebab-case). Names the Op's output directory and is what `chant run` takes. */
+  name: string;
+  /** Cron expression. When set, it lands on the Op as `schedule`; omit for one-shot. */
+  schedule?: string;
+  /**
+   * Path to the emitted `.gitlab-ci.yml` to audit at run time.
+   * @default ".gitlab-ci.yml"
+   */
+  pipelineFile?: string;
+  /**
+   * What to produce on findings. Default: "report".
+   * @default "report"
+   */
+  onFinding?: PipelineAuditMode;
+}
+
+export interface PipelineAuditOpResources {
+  /** Op resource — the audit Op, emitted on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function PipelineAuditOp(config: PipelineAuditOpConfig): PipelineAuditOpResources {
+  const onFinding = config.onFinding ?? "report";
+
+  const op = Op({
+    name: config.name,
+    overview: "Resolve pipeline include/component/image references against live upstreams and report drift",
+    labels: {
+      Audit: "true",
+      Surface: "gitlab-pipeline",
+    },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [
+      phase("Audit", [
+        {
+          kind: "activity",
+          fn: "pipelineSupplyChainAudit",
+          args: { pipelineFile: config.pipelineFile ?? ".gitlab-ci.yml", mode: onFinding },
+          outcomeAttribute: { name: "Findings", from: "findings" },
+        },
+      ]),
+    ],
+  });
+
+  return { op };
+}

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

@@ -0,0 +1,51 @@
+import { describe, test, expect } from "vitest";
+import { ReconcileOp } from "./reconcile-op";
+
+/** Reach into the generated Op's phases → the reconcilePr step. */
+function reconcileStep(op: unknown): Record<string, unknown> {
+  const config = (op as { props: Record<string, unknown> }).props;
+  const phases = config.phases as Array<{ name: string; steps: Array<Record<string, unknown>> }>;
+  const reconcile = phases.find((p) => p.name === "Reconcile");
+  if (!reconcile) throw new Error("no Reconcile phase");
+  return reconcile.steps[0];
+}
+
+describe("ReconcileOp composite — PR/issue URL outcome (#8)", () => {
+  test("pull-request mode (default) exposes prUrl as the PR outcome attribute", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+    const step = reconcileStep(op);
+    expect(step.fn).toBe("reconcilePr");
+    expect((step.args as { mode: string }).mode).toBe("pull-request");
+    expect(step.outcomeAttribute).toEqual({ name: "PR", from: "prUrl" });
+  });
+
+  test("issue mode exposes issueUrl as the Issue outcome attribute", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "issue" });
+    const step = reconcileStep(op);
+    expect((step.args as { mode: string }).mode).toBe("issue");
+    expect(step.outcomeAttribute).toEqual({ name: "Issue", from: "issueUrl" });
+  });
+
+  test("report mode opens nothing, so carries no URL outcome", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "report" });
+    const step = reconcileStep(op);
+    expect((step.args as { mode: string }).mode).toBe("report");
+    expect(step.outcomeAttribute).toBeUndefined();
+  });
+});
+
+describe("ReconcileOp composite — cadence on the op (#2120)", () => {
+  function opProps(op: unknown): Record<string, unknown> {
+    return (op as { props: Record<string, unknown> }).props;
+  }
+
+  test("one-shot form carries no schedule", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+    expect(opProps(op).schedule).toBeUndefined();
+  });
+
+  test("a cron lands on the op as { cron, overlap: \"skip\" }", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", schedule: "0 * * * *" });
+    expect(opProps(op).schedule).toEqual({ cron: "0 * * * *", overlap: "skip" });
+  });
+});