@intentius/chant-lexicon-prometheus 0.106.4 → 0.108.0

package/src/op/activities/silence.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, test } from "vitest";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { withOpRunContext } from "@intentius/chant/op";
+import { alertmanagerSilence, alertmanagerUnsilence, apiMatchers, recordPath } from "./silence";
+
+/** An Alertmanager API stand-in: creates silences, expires them once, then answers "already expired". */
+function fakeAlertmanager() {
+  const created: Array<{ id: string; body: Record<string, unknown> }> = [];
+  const expired = new Set<string>();
+  const calls: string[] = [];
+  let n = 0;
+  const f = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = String(input);
+    calls.push(`${init?.method ?? "GET"} ${url}`);
+    if (init?.method === "POST" && url.endsWith("/api/v2/silences")) {
+      const id = `s-${++n}`;
+      created.push({ id, body: JSON.parse(String(init.body)) });
+      return Response.json({ silenceID: id });
+    }
+    const m = /\/api\/v2\/silence\/(.+)$/.exec(url);
+    if (init?.method === "DELETE" && m) {
+      const id = decodeURIComponent(m[1]);
+      if (!created.some((c) => c.id === id)) return new Response("silence not found", { status: 404 });
+      if (expired.has(id)) return new Response(`silence ${id} already expired`, { status: 500 });
+      expired.add(id);
+      return new Response(null, { status: 200 });
+    }
+    return new Response("no", { status: 400 });
+  }) as typeof fetch;
+  return { f, created, expired, calls };
+}
+
+const NOW = () => new Date("2026-10-06T12:00:00.000Z");
+
+describe("Alertmanager matchers", () => {
+  test("matcher strings and label sets as API matchers", () => {
+    expect(apiMatchers(['alertname="SloBurn"', 'severity=~"page|ticket"', 'env!="dev"'])).toEqual([
+      { name: "alertname", value: "SloBurn", isRegex: false, isEqual: true },
+      { name: "severity", value: "page|ticket", isRegex: true, isEqual: true },
+      { name: "env", value: "dev", isRegex: false, isEqual: false },
+    ]);
+    expect(apiMatchers({ slo: "checkout" })).toEqual([{ name: "slo", value: "checkout", isRegex: false, isEqual: true }]);
+    expect(() => apiMatchers(["not a matcher"])).toThrow(/matcher/);
+    expect(() => apiMatchers([])).toThrow(/at least one/);
+  });
+
+  test("a record name cannot leave the record directory", () => {
+    expect(() => recordPath("../x")).toThrow(/record/);
+  });
+});
+
+describe("alertmanagerSilence and alertmanagerUnsilence", () => {
+  test("silence, record the id, then expire it from the record", async () => {
+    const am = fakeAlertmanager();
+    const recordDir = mkdtempSync(join(tmpdir(), "chant-silence-"));
+    const r = await withOpRunContext({ op: "deploy", runId: "run-1", passedGates: [] }, () =>
+      alertmanagerSilence({ url: "http://am:9093/", matchers: { slo: "checkout" }, duration: "30m", recordDir, record: "deploy", _fetch: am.f, _now: NOW }),
+    );
+    expect(r).toMatchObject({ silenceId: "s-1", url: "http://am:9093", startsAt: "2026-10-06T12:00:00.000Z", endsAt: "2026-10-06T12:30:00.000Z" });
+    expect(am.created[0].body).toMatchObject({ createdBy: "chant op deploy", comment: "chant run deploy (run-1)", matchers: [{ name: "slo", value: "checkout" }] });
+    const recorded = JSON.parse(readFileSync(r.record, "utf8"));
+    expect(recorded.silences).toEqual([{ silenceId: "s-1", url: "http://am:9093", endsAt: "2026-10-06T12:30:00.000Z", run: "run-1" }]);
+
+    const u = await alertmanagerUnsilence({ recordDir, record: "deploy", _fetch: am.f });
+    expect(u.expired).toEqual(["s-1"]);
+    expect(am.calls).toContain("DELETE http://am:9093/api/v2/silence/s-1");
+    expect(JSON.parse(readFileSync(r.record, "utf8")).silences).toEqual([]);
+  });
+
+  test("expiring twice, or a silence Alertmanager does not know, is done, not an error", async () => {
+    const am = fakeAlertmanager();
+    const recordDir = mkdtempSync(join(tmpdir(), "chant-silence-"));
+    await alertmanagerSilence({ url: "http://am:9093", matchers: ['alertname="X"'], duration: "1h", recordDir, _fetch: am.f });
+    await alertmanagerUnsilence({ url: "http://am:9093", silenceId: "s-1", recordDir, _fetch: am.f });
+    await expect(alertmanagerUnsilence({ url: "http://am:9093", silenceId: "s-1", recordDir, _fetch: am.f })).resolves.toMatchObject({ expired: ["s-1"] });
+    await expect(alertmanagerUnsilence({ url: "http://am:9093", silenceId: "nope", recordDir, _fetch: am.f })).resolves.toMatchObject({ expired: ["nope"] });
+  });
+
+  test("with nothing recorded, unsilence does nothing and writes no record", async () => {
+    const am = fakeAlertmanager();
+    const recordDir = mkdtempSync(join(tmpdir(), "chant-silence-"));
+    await expect(alertmanagerUnsilence({ recordDir, _fetch: am.f })).resolves.toEqual({ expired: [], failed: [] });
+    expect(am.calls).toEqual([]);
+    expect(existsSync(join(recordDir, "silence.json"))).toBe(false);
+  });
+
+  test("a silence that cannot be expired stays recorded and fails the step", async () => {
+    const am = fakeAlertmanager();
+    const recordDir = mkdtempSync(join(tmpdir(), "chant-silence-"));
+    await alertmanagerSilence({ url: "http://am:9093", matchers: { a: "1" }, duration: "1h", recordDir, _fetch: am.f });
+    const down = (async () => {
+      throw new TypeError("fetch failed");
+    }) as unknown as typeof fetch;
+    await expect(alertmanagerUnsilence({ recordDir, _fetch: down })).rejects.toThrow(/could not expire 1 silence/);
+    expect(JSON.parse(readFileSync(join(recordDir, "silence.json"), "utf8")).silences).toHaveLength(1);
+  });
+
+  test("a bad duration or an API error fails before anything is recorded", async () => {
+    const recordDir = mkdtempSync(join(tmpdir(), "chant-silence-"));
+    await expect(alertmanagerSilence({ matchers: { a: "1" }, duration: "soon", recordDir })).rejects.toThrow(/not a Prometheus duration/);
+    const refuse = (async () => new Response("bad matchers", { status: 400 })) as unknown as typeof fetch;
+    await expect(alertmanagerSilence({ matchers: { a: "1" }, duration: "5m", recordDir, _fetch: refuse })).rejects.toThrow(/HTTP 400/);
+    expect(existsSync(join(recordDir, "silence.json"))).toBe(false);
+  });
+});

package/src/op/activities/silence.ts

@@ -0,0 +1,175 @@
+/**
+ * Alertmanager silences as Op steps (#3369): silence the alerts a change is
+ * expected to set off, and expire the silence when the change is done or
+ * has failed.
+ *
+ * `alertmanagerSilence` creates a silence through `POST /api/v2/silences`
+ * and records its id in a file under the working directory
+ * (`.chant/alertmanager-silences/<record>.json`). Step-output references are
+ * not available in an Op's `onFailure` phases, so the record is how a final
+ * phase and an `onFailure` phase alike find the silence:
+ * `alertmanagerUnsilence({ record })` expires every silence the record
+ * holds through `DELETE /api/v2/silence/{id}`, and drops them from it. An
+ * already-expired or unknown silence counts as expired, so the step can
+ * run in both places.
+ *
+ * The Alertmanager is `url`, else `$ALERTMANAGER_URL`, else
+ * `http://localhost:9093`.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { currentOpRun } from "@intentius/chant/op";
+import { durationMs } from "../../duration";
+import { parseMatchers } from "../../matchers";
+
+export interface AlertmanagerSilenceArgs {
+  /** The Alertmanager's base URL. */
+  url?: string;
+  /**
+   * The alerts to silence: matcher strings (`alertname="X"`,
+   * `severity=~"page|ticket"`, or `{a="1", b="2"}`), or a label set matched
+   * by equality.
+   */
+  matchers: string[] | Record<string, string>;
+  /** How long the silence lasts, e.g. `30m`. Expiring it earlier is `alertmanagerUnsilence`'s job. */
+  duration: string;
+  comment?: string;
+  /** Default `chant`, with the Op's name when run in one. */
+  createdBy?: string;
+  /** The record the id is kept in. Default `silence`. */
+  record?: string;
+  /** Where records live, relative to the working directory. Default `.chant/alertmanager-silences`. */
+  recordDir?: string;
+  /** Replaces fetch. For tests. */
+  _fetch?: typeof fetch;
+  /** Replaces the clock. For tests. */
+  _now?: () => Date;
+}
+
+export interface AlertmanagerSilenceResult {
+  silenceId: string;
+  url: string;
+  startsAt: string;
+  endsAt: string;
+  /** The record file the id was written to. */
+  record: string;
+}
+
+export interface AlertmanagerUnsilenceArgs {
+  url?: string;
+  /** Expire this silence only, in place of the record's. */
+  silenceId?: string;
+  /** The record to expire. Default `silence`. */
+  record?: string;
+  recordDir?: string;
+  _fetch?: typeof fetch;
+}
+
+export interface AlertmanagerUnsilenceResult {
+  expired: string[];
+  /** Silences that could not be expired, kept in the record for the next try. */
+  failed: { silenceId: string; detail: string }[];
+}
+
+interface RecordedSilence {
+  silenceId: string;
+  url: string;
+  endsAt: string;
+  run?: string;
+}
+
+export function alertmanagerUrl(url?: string): string {
+  return (url ?? process.env.ALERTMANAGER_URL ?? "http://localhost:9093").replace(/\/+$/, "");
+}
+
+/** The API matchers for `matchers`. */
+export function apiMatchers(matchers: string[] | Record<string, string>): Array<{ name: string; value: string; isRegex: boolean; isEqual: boolean }> {
+  if (!Array.isArray(matchers)) {
+    return Object.entries(matchers).map(([name, value]) => ({ name, value, isRegex: false, isEqual: true }));
+  }
+  const out: Array<{ name: string; value: string; isRegex: boolean; isEqual: boolean }> = [];
+  for (const entry of matchers) {
+    const parsed = parseMatchers(entry);
+    if (!parsed.ok) throw new Error(`matcher ${JSON.stringify(entry)}: ${parsed.error}`);
+    for (const m of parsed.matchers) out.push({ name: m.name, value: m.value, isRegex: m.op.endsWith("~"), isEqual: !m.op.startsWith("!") });
+  }
+  if (out.length === 0) throw new Error("a silence needs at least one matcher");
+  return out;
+}
+
+export function recordPath(record = "silence", recordDir = ".chant/alertmanager-silences", cwd = process.cwd()): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(record)) throw new Error(`record ${JSON.stringify(record)}: use letters, digits, dot, dash and underscore`);
+  return join(resolve(cwd, recordDir), `${record}.json`);
+}
+
+function readRecord(path: string): RecordedSilence[] {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { silences?: RecordedSilence[] };
+    return Array.isArray(parsed.silences) ? parsed.silences : [];
+  } catch {
+    return [];
+  }
+}
+
+function writeRecord(path: string, silences: RecordedSilence[]): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify({ silences }, null, 2)}\n`);
+}
+
+/** Create a silence and record its id. */
+export async function alertmanagerSilence(args: AlertmanagerSilenceArgs): Promise<AlertmanagerSilenceResult> {
+  const f = args._fetch ?? fetch;
+  const url = alertmanagerUrl(args.url);
+  const ms = durationMs(args.duration);
+  if (!ms || ms <= 0) throw new Error(`duration ${JSON.stringify(args.duration)} is not a Prometheus duration such as 30m`);
+  const run = currentOpRun();
+  const now = (args._now ?? (() => new Date()))();
+  const startsAt = now.toISOString();
+  const endsAt = new Date(now.getTime() + ms).toISOString();
+  const body = {
+    matchers: apiMatchers(args.matchers),
+    startsAt,
+    endsAt,
+    createdBy: args.createdBy ?? (run ? `chant op ${run.op}` : "chant"),
+    comment: args.comment ?? (run ? `chant run ${run.op} (${run.runId})` : "chant"),
+  };
+  const res = await f(`${url}/api/v2/silences`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`POST ${url}/api/v2/silences: HTTP ${res.status}: ${text.slice(0, 300)}`);
+  const silenceId = (JSON.parse(text) as { silenceID?: string }).silenceID;
+  if (!silenceId) throw new Error(`POST ${url}/api/v2/silences answered without a silenceID: ${text.slice(0, 300)}`);
+  const path = recordPath(args.record, args.recordDir);
+  writeRecord(path, [...readRecord(path), { silenceId, url, endsAt, ...(run ? { run: run.runId } : {}) }]);
+  return { silenceId, url, startsAt, endsAt, record: path };
+}
+
+/** Expire the recorded silences (or `silenceId`), and drop the expired ones from the record. */
+export async function alertmanagerUnsilence(args: AlertmanagerUnsilenceArgs = {}): Promise<AlertmanagerUnsilenceResult> {
+  const f = args._fetch ?? fetch;
+  const path = recordPath(args.record, args.recordDir);
+  const recorded = readRecord(path);
+  const targets: RecordedSilence[] = args.silenceId
+    ? [recorded.find((s) => s.silenceId === args.silenceId) ?? { silenceId: args.silenceId, url: alertmanagerUrl(args.url), endsAt: "" }]
+    : recorded;
+  const expired: string[] = [];
+  const failed: AlertmanagerUnsilenceResult["failed"] = [];
+  for (const s of targets) {
+    const base = args.url ? alertmanagerUrl(args.url) : s.url;
+    try {
+      const res = await f(`${base}/api/v2/silence/${encodeURIComponent(s.silenceId)}`, { method: "DELETE" });
+      const text = await res.text().catch(() => "");
+      // Alertmanager answers 404 for an unknown silence and 500 "already expired" for an expired one: both are done.
+      if (res.ok || res.status === 404 || /expired/i.test(text)) expired.push(s.silenceId);
+      else failed.push({ silenceId: s.silenceId, detail: `HTTP ${res.status}: ${text.slice(0, 200)}` });
+    } catch (err) {
+      failed.push({ silenceId: s.silenceId, detail: (err as Error).message });
+    }
+  }
+  const done = new Set(expired);
+  if (recorded.length > 0) writeRecord(path, recorded.filter((s) => !done.has(s.silenceId)));
+  if (failed.length > 0) {
+    throw new Error(`could not expire ${failed.length} silence(s): ${failed.map((x) => `${x.silenceId} (${x.detail})`).join("; ")}`);
+  }
+  return { expired, failed };
+}

package/src/op/activity-contracts.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from "vitest";
+import {
+  ConvergeOp,
+  Op,
+  eq,
+  isActivityContract,
+  loadActivities,
+  loadActivityContracts,
+  phase,
+  report,
+  validateActivitySteps,
+  validateStepOutputRefs,
+  when,
+  type ActivityContract,
+  type ResourceSymptom,
+} from "@intentius/chant/op";
+import { load } from "js-yaml";
+import * as contracts from "./activity-contracts";
+import * as activities from "./activities";
+import {
+  alertmanagerSilence,
+  alertmanagerUnsilence,
+  amtoolCheckConfig,
+  amtoolRoutesTest,
+  promtoolCheckRules,
+  promtoolTestRules,
+  ruleAudit,
+  rulesLoadedObserve,
+} from "./builders";
+import { RuleAuditOp } from "./audit-op";
+import { Slo } from "../composites/slo";
+
+const CONTRACTS: Map<string, ActivityContract> = new Map(
+  Object.values(contracts).filter(isActivityContract).map((c) => [c.name, c]),
+);
+
+const op = (steps: unknown[]) => ({ name: "check", phases: [{ name: "Check", steps: steps as never[] }] });
+
+describe("prometheus activity contracts (#3369)", () => {
+  test("every exported activity has a contract with a return schema, and nothing else is exported", () => {
+    for (const [key, value] of Object.entries(contracts)) {
+      expect(isActivityContract(value), `${key} is not an ActivityContract`).toBe(true);
+      expect((value as ActivityContract).returns).toBeDefined();
+    }
+    const fns = Object.entries(activities).filter(([, v]) => typeof v === "function").map(([k]) => k).sort();
+    expect([...CONTRACTS.keys()].sort()).toEqual(fns);
+    expect(fns).toEqual([
+      "alertmanagerSilence",
+      "alertmanagerUnsilence",
+      "amtoolCheckConfig",
+      "amtoolRoutesTest",
+      "promtoolCheckRules",
+      "promtoolTestRules",
+      "ruleAudit",
+      "rulesLoadedObserve",
+    ]);
+  });
+
+  test("the builders' steps validate, and a misspelled key is an error", () => {
+    const steps = [
+      promtoolCheckRules({ rules: "dist/prometheus/rules.yml" }),
+      promtoolTestRules({ rules: "dist/prometheus/rules.yml", tests: ["tests/slo.test.yml"] }),
+      amtoolCheckConfig({ config: "dist/prometheus/alertmanager.yml" }),
+      amtoolRoutesTest({ config: "dist/prometheus/alertmanager.yml", labels: { severity: "page" }, expect: "oncall" }),
+      alertmanagerSilence({ matchers: ['alertname="SloBurn"'], duration: "30m", record: "deploy" }),
+      alertmanagerUnsilence({ record: "deploy" }),
+      ruleAudit({ mode: "issue", selectorBudget: 10 }),
+    ];
+    expect(validateActivitySteps(op(steps), CONTRACTS)).toEqual([]);
+    const issues = validateActivitySteps(op([{ kind: "activity", fn: "alertmanagerSilence", args: { matchers: {}, duraton: "5m" } }]), CONTRACTS);
+    expect(issues.some((i) => i.message.includes("duraton"))).toBe(true);
+  });
+
+  test("promtoolTestRules({ slos }) generates the tests at build time", () => {
+    const slo = Slo({ name: "checkout", objective: 0.99, window: "30d", sli: { good: 'sum(rate(req_total{code="200"}[{{window}}]))', total: "sum(rate(req_total[{{window}}]))" } });
+    const step = promtoolTestRules({ rules: "dist/prometheus/rules.yml", slos: [{ slo, good: 'req_total{code="200"}', bad: 'req_total{code="500"}' }] });
+    const docs = step.args?.testYaml as string[];
+    expect(docs.length).toBe(2);
+    expect((load(docs[0]) as { rule_files: string[] }).rule_files).toEqual(["rules.yml"]);
+    expect(step.args).not.toHaveProperty("slos");
+    expect(validateActivitySteps(op([step]), CONTRACTS)).toEqual([]);
+  });
+
+  test("ConvergeOp({ observe: rulesLoadedObserve }) passes OPS012 and OPS013", () => {
+    const { op: converge } = ConvergeOp({
+      name: "rules-loaded",
+      env: "local",
+      schedule: "*/5 * * * *",
+      observe: rulesLoadedObserve({ url: "http://localhost:9090", rules: "dist/prometheus/rules.yml" }),
+      rules: [when<ResourceSymptom>(eq("status", "drifted"), report("rule group not loaded or failing"), { id: "group-drift", why: "say so" })],
+    });
+    expect(validateActivitySteps(converge.props as never, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(converge.props as never, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(converge.props as never, new Map()).length).toBeGreaterThan(0);
+  });
+
+  test("a silence around a change: the final phase reads the id; onFailure expires through the record", () => {
+    const silence = alertmanagerSilence({ id: "silence", matchers: { slo: "checkout" }, duration: "30m", record: "deploy" });
+    const change = Op({
+      name: "deploy",
+      overview: "deploy with alerts silenced",
+      phases: [phase("Silence", [silence]), phase("Unsilence", [alertmanagerUnsilence({ silenceId: silence.out.silenceId, record: "deploy" })])],
+      onFailure: [phase("Unsilence", [alertmanagerUnsilence({ record: "deploy" })])],
+    });
+    expect(validateActivitySteps(change.props as never, CONTRACTS)).toEqual([]);
+    expect(validateStepOutputRefs(change.props as never, CONTRACTS)).toEqual([]);
+    expect(silence.profile).toBe("atMostOnce");
+  });
+
+  test("RuleAuditOp is one ruleAudit step, its findings the run's outcome", () => {
+    const { op: audit } = RuleAuditOp({ name: "rule-audit", url: "http://prom:9090", schedule: "0 * * * *", onFinding: "issue", pendingFor: "2h" });
+    const props = audit.props as unknown as { schedule?: unknown; phases: Array<{ steps: Array<Record<string, unknown>> }> };
+    expect(props.schedule).toEqual({ cron: "0 * * * *", overlap: "skip" });
+    expect(props.phases[0].steps[0]).toMatchObject({
+      fn: "ruleAudit",
+      args: { mode: "issue", url: "http://prom:9090", pendingFor: "2h" },
+      outcomeAttribute: { name: "Findings", from: "findings" },
+    });
+    expect(validateActivitySteps(props as never, CONTRACTS)).toEqual([]);
+  });
+
+  test("loadActivities and loadActivityContracts find them by the prometheus lexicon's name", async () => {
+    const acts = await loadActivities(["prometheus"]);
+    for (const fn of ["promtoolCheckRules", "rulesLoadedObserve", "alertmanagerSilence", "ruleAudit"]) expect(acts.has(fn), fn).toBe(true);
+    const loaded = await loadActivityContracts(["prometheus"]);
+    expect(loaded.get("rulesLoadedObserve")?.returns).toBeDefined();
+  });
+});
+
+// ── Compile-time only ────────────────────────────────────────────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error: duration is required.
+  alertmanagerSilence({ matchers: { a: "1" } });
+  // @ts-expect-error: labels are strings.
+  amtoolRoutesTest({ config: "a.yml", labels: { replicas: 3 }, expect: "x" });
+  // @ts-expect-error: mode is report or issue.
+  ruleAudit({ mode: "pull-request" });
+  // @ts-expect-error: the test seam is not an authoring option.
+  rulesLoadedObserve({ groups: ["g"], _fetch: fetch });
+}
+void _typeChecksOnly;

package/src/op/activity-contracts.ts

@@ -0,0 +1,96 @@
+/**
+ * Activity contracts for this lexicon's `op/activities` (#3369).
+ *
+ * Resolved by convention at
+ * `@intentius/chant-lexicon-prometheus/op/activity-contracts`:
+ * `loadActivityContracts` merges them into the map OPS012 checks each step's
+ * args against and OPS013 checks each step-output reference against. Every
+ * activity here has one; `rulesLoadedObserve`'s return schema is what lets a
+ * `ConvergeOp({ observe: rulesLoadedObserve(...) })` pass OPS013, and
+ * `alertmanagerSilence`'s is what a later step reads `.out.silenceId` from.
+ *
+ * Each `args` schema mirrors the `*Args` interface in `./activities/`,
+ * without the `_`-prefixed test seams, and is a `z.strictObject`, so a
+ * misspelled key fails the build.
+ */
+
+import { z } from "zod";
+import { activityContract } from "@intentius/chant/op";
+
+const oneOrMany = z.union([z.string(), z.array(z.string())]);
+const toolResult = z.object({ files: z.array(z.string()), ok: z.boolean(), output: z.string() });
+const resourceStatus = z.enum(["in-sync", "drifted", "unknown"]);
+
+export const promtoolCheckRulesContract = activityContract(
+  "promtoolCheckRules",
+  z.strictObject({ rules: oneOrMany, bin: z.string().optional() }),
+  toolResult,
+);
+
+export const promtoolTestRulesContract = activityContract(
+  "promtoolTestRules",
+  z.strictObject({ rules: z.string(), tests: oneOrMany.optional(), testYaml: oneOrMany.optional(), bin: z.string().optional() }),
+  toolResult.extend({ tests: z.number() }),
+);
+
+export const amtoolCheckConfigContract = activityContract(
+  "amtoolCheckConfig",
+  z.strictObject({ config: z.string(), bin: z.string().optional() }),
+  toolResult,
+);
+
+export const amtoolRoutesTestContract = activityContract(
+  "amtoolRoutesTest",
+  z.strictObject({ config: z.string(), labels: z.record(z.string(), z.string()), expect: oneOrMany, bin: z.string().optional() }),
+  z.object({ config: z.string(), labels: z.record(z.string(), z.string()), receivers: z.array(z.string()), ok: z.boolean() }),
+);
+
+const record = { record: z.string().optional(), recordDir: z.string().optional() };
+
+export const alertmanagerSilenceContract = activityContract(
+  "alertmanagerSilence",
+  z.strictObject({
+    url: z.string().optional(),
+    matchers: z.union([z.array(z.string()), z.record(z.string(), z.string())]),
+    duration: z.string(),
+    comment: z.string().optional(),
+    createdBy: z.string().optional(),
+    ...record,
+  }),
+  z.object({ silenceId: z.string(), url: z.string(), startsAt: z.string(), endsAt: z.string(), record: z.string() }),
+);
+
+export const alertmanagerUnsilenceContract = activityContract(
+  "alertmanagerUnsilence",
+  z.strictObject({ url: z.string().optional(), silenceId: z.string().optional(), ...record }),
+  z.object({ expired: z.array(z.string()), failed: z.array(z.object({ silenceId: z.string(), detail: z.string() })) }),
+);
+
+export const rulesLoadedObserveContract = activityContract(
+  "rulesLoadedObserve",
+  z.strictObject({ url: z.string().optional(), groups: z.array(z.string()).optional(), rules: oneOrMany.optional(), timeoutMs: z.number().optional() }),
+  z.object({ resources: z.array(z.object({ name: z.string(), status: resourceStatus, detail: z.string() })) }),
+);
+
+export const ruleAuditContract = activityContract(
+  "ruleAudit",
+  z.strictObject({
+    url: z.string().optional(),
+    pendingFor: z.string().optional(),
+    firingFor: z.string().optional(),
+    selectorBudget: z.number().optional(),
+    lookback: z.string().optional(),
+    mode: z.enum(["report", "issue"]).optional(),
+    issueTitle: z.string().optional(),
+  }),
+  z.object({
+    mode: z.enum(["report", "issue"]),
+    findings: z.array(
+      z.object({ kind: z.enum(["rule-error", "pending-too-long", "firing-too-long", "selector-no-series"]), subject: z.string(), detail: z.string() }),
+    ),
+    queried: z.number(),
+    unchecked: z.number(),
+    summary: z.string(),
+    issueUrl: z.string().optional(),
+  }),
+);

package/src/op/audit-op.ts

@@ -0,0 +1,54 @@
+/**
+ * `RuleAuditOp`: what a live Prometheus says about its rules, as an Op with
+ * an optional schedule (#3369). One `ruleAudit` step reports groups with
+ * health errors, alerts pending or firing past a threshold, and selectors
+ * no live target emits (one query per selector, within a budget).
+ * `onFinding` is `report` (the default) or `issue`, which keeps one open
+ * issue current.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = RuleAuditOp({ name: "rule-audit", url: "http://prometheus:9090", schedule: "0 * * * *" });
+ * ```
+ */
+
+import { Op, phase, type OpResource } from "@intentius/chant/op";
+import { ruleAudit } from "./builders";
+import type { RuleAuditMode } from "./activities/rule-audit";
+
+export interface RuleAuditOpConfig {
+  /** Op name (kebab-case). */
+  name: string;
+  /** Prometheus's base URL. Default `$PROMETHEUS_URL`, else `http://localhost:9090`. */
+  url?: string;
+  /** Cron expression; omit for one-shot `chant run`. */
+  schedule?: string;
+  /** @default "report" */
+  onFinding?: RuleAuditMode;
+  /** @default "1h" */
+  pendingFor?: string;
+  /** @default "24h" */
+  firingFor?: string;
+  /** @default 50 */
+  selectorBudget?: number;
+  /** @default "1h" */
+  lookback?: string;
+}
+
+export interface RuleAuditOpResources {
+  op: InstanceType<typeof OpResource>;
+}
+
+export function RuleAuditOp(config: RuleAuditOpConfig): RuleAuditOpResources {
+  const { name, schedule, onFinding, ...rest } = config;
+  const defined = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)) as Omit<RuleAuditOpConfig, "name" | "schedule" | "onFinding">;
+  const step = ruleAudit({ mode: onFinding ?? "report", ...defined });
+  const op = Op({
+    name,
+    overview: "Audit a live Prometheus: rule health, alerts pending or firing too long, and selectors nothing emits",
+    labels: { Audit: "true", Surface: "prometheus-rules" },
+    ...(schedule ? { schedule: { cron: schedule, overlap: "skip" as const } } : {}),
+    phases: [phase("Audit", [{ ...step, outcomeAttribute: { name: "Findings", from: "findings" } }])],
+  });
+  return { op };
+}

package/src/op/builders.ts

@@ -0,0 +1,82 @@
+/**
+ * Typed step builders for this lexicon's Op activities (#3369), following
+ * the helm and fly builders: each one's options ARE the activity's own
+ * `*Args` interface (minus its `_`-prefixed test seams), every field also
+ * takes a `StepOutputRef`, and `profile` and `id` go to the step.
+ *
+ * `promtoolCheckRules`, `promtoolTestRules` and `amtoolCheckConfig` share
+ * their names with the plain functions in `../tools.ts`, which the package
+ * root already exports, so those three builders are reached here, at
+ * `@intentius/chant-lexicon-prometheus/op/builders`. The root exports the
+ * rest.
+ */
+
+import { activity, takeProfileAndId, type ActivityStep, type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
+import type {
+  AmtoolCheckConfigArgs,
+  AmtoolRoutesTestArgs,
+  PromtoolCheckRulesArgs,
+  PromtoolTestRulesArgs,
+} from "./activities/promtool";
+import type { AlertmanagerSilenceArgs, AlertmanagerUnsilenceArgs } from "./activities/silence";
+import type { RulesLoadedObserveArgs } from "./activities/rules-loaded";
+import type { RuleAuditArgs } from "./activities/rule-audit";
+import { sloRuleTests, type SloTestInput } from "./slo-rule-tests";
+
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+type Authored<T> = Omit<T, `_${string}`>;
+
+function step<Args>(fn: string, defaultProfile: NonNullable<ActivityStep["profile"]>) {
+  return (args: WithStepRefs<Authored<Args>> & StepOpts): NamedActivityStep => {
+    const { args: rest, profile, id } = takeProfileAndId(args as Record<string, unknown>);
+    return activity(fn, rest, { profile: profile ?? defaultProfile, ...(id ? { id } : {}) });
+  };
+}
+
+/** `promtool check rules` over built rule files. Defaults to the `fastIdempotent` profile. */
+export const promtoolCheckRules = step<PromtoolCheckRulesArgs>("promtoolCheckRules", "fastIdempotent");
+
+/**
+ * `promtool test rules` over a built rule file. `slos` generates the tests
+ * from `Slo` declarations at build time (`sloRuleTests`): each burn-rate
+ * pair fires at its rate and not below it. Defaults to the `fastIdempotent`
+ * profile.
+ */
+export const promtoolTestRules = (
+  args: WithStepRefs<Authored<PromtoolTestRulesArgs>> & StepOpts & { slos?: SloTestInput[] },
+): NamedActivityStep => {
+  const { slos, ...rest } = args;
+  if (!slos || slos.length === 0) return step<PromtoolTestRulesArgs>("promtoolTestRules", "fastIdempotent")(rest);
+  const generated = sloRuleTests(slos);
+  const given = rest.testYaml === undefined ? [] : Array.isArray(rest.testYaml) ? rest.testYaml : [rest.testYaml];
+  return step<PromtoolTestRulesArgs>("promtoolTestRules", "fastIdempotent")({ ...rest, testYaml: [...(given as string[]), ...generated] });
+};
+
+/** `amtool check-config` over a built Alertmanager config. Defaults to the `fastIdempotent` profile. */
+export const amtoolCheckConfig = step<AmtoolCheckConfigArgs>("amtoolCheckConfig", "fastIdempotent");
+
+/** `amtool config routes test`: `labels` route to `expect`. Defaults to the `fastIdempotent` profile. */
+export const amtoolRoutesTest = step<AmtoolRoutesTestArgs>("amtoolRoutesTest", "fastIdempotent");
+
+/**
+ * Silence alerts through Alertmanager's API for `duration`, recording the
+ * silence id under `record` so `alertmanagerUnsilence` can expire it from
+ * a final phase or an `onFailure` phase. Defaults to the `atMostOnce`
+ * profile: a retry after a lost answer would create a second silence.
+ */
+export const alertmanagerSilence = step<AlertmanagerSilenceArgs>("alertmanagerSilence", "atMostOnce");
+
+/** Expire the silences `record` holds (or `silenceId`). Defaults to the `fastIdempotent` profile. */
+export const alertmanagerUnsilence = (args: WithStepRefs<Authored<AlertmanagerUnsilenceArgs>> & StepOpts = {}): NamedActivityStep =>
+  step<AlertmanagerUnsilenceArgs>("alertmanagerUnsilence", "fastIdempotent")(args);
+
+/**
+ * Observe declared rule groups for a `ConvergeOp({ observe })`: one resource
+ * per group, drifted when Prometheus has not loaded it or a rule in it has
+ * `health: "err"`. Defaults to the `fastIdempotent` profile.
+ */
+export const rulesLoadedObserve = step<RulesLoadedObserveArgs>("rulesLoadedObserve", "fastIdempotent");
+
+/** Audit a live Prometheus's rules, alerts and selectors (the step of `RuleAuditOp`). Defaults to the `fastIdempotent` profile. */
+export const ruleAudit = (args: WithStepRefs<Authored<RuleAuditArgs>> & StepOpts = {}): NamedActivityStep =>
+  step<RuleAuditArgs>("ruleAudit", "fastIdempotent")(args);