@intentius/chant 0.124.12 → 0.124.14

package/dist/op/activities/apply.js

@@ -0,0 +1,582 @@
+/**
+ * `nativeApply` — push declared source to the cloud through the target's own
+ * mechanism. Authority stays with the platform; chant hosts no state file.
+ *
+ * ## Where the shell went (chant #1075, #1448, #1449)
+ *
+ * This used to build a shell command for every target — `kubectl apply -f`,
+ * `az deployment group create`, `aws cloudformation deploy`. Two things were
+ * wrong with that. The shell commands carried product knowledge that belongs to
+ * each product's lexicon, against the one-lexicon-per-product rule that already
+ * moved `kubectlApply`, `k3dUp`/`k3dDown` and `waitForArgoSync` out (chant
+ * #809). And each CLI's semantics diverged from what the docblocks promised —
+ * `kubectl apply`'s client-side merge gave the diff engine nothing to key on
+ * (#1075), and ARM Complete mode deleted resources chant never applied (#1448).
+ *
+ * So each branch moved to its product's lexicon: `kubectl`/`kustomize` are a
+ * server-side apply over the k8s lexicon's typed client (#1075, #1548), `arm`
+ * is the azure lexicon's per-resource `azApply` (#1448), `cloudformation`
+ * is the aws lexicon's `awsApply` — the CloudFormation Query API directly, no
+ * CLI in the path (#1449) — and `gcp`/`fly` are the gcp lexicon's
+ * per-resource `gcpApply` and the fly lexicon's `flyApply`, which never had a
+ * CLI in the path to begin with: gcp maps each CNRM kind to its REST API
+ * itself, and fly speaks the Machines API (flaps) directly, no flyctl.
+ * `grafana` joined later (#3011): the grafana lexicon's `grafanaApply`, which
+ * writes folders, library panels and dashboards over Grafana's HTTP API.
+ * `clickhouse` joined after it (#3208): the sql lexicon's `clickhouseApply`,
+ * which sends a ClickHouse server the CREATE and ALTER statements a build's
+ * classified changes need, over its HTTP interface. `postgres` joined after
+ * that (#3280): the sql lexicon's `postgresApply`, which sends a Postgres
+ * server the statements a build's classified changes need, grouped into
+ * transactions, with `CONCURRENTLY` statements outside them. `ruler` joined
+ * last (#3372): the prometheus lexicon's `rulerApply`, which posts rule groups
+ * to a Mimir, Cortex or Loki ruler and uploads a Mimir or Cortex Alertmanager
+ * config, inside the namespaces the project declares.
+ * **The dispatcher stayed here**, because "which
+ * mechanism applies this target" is not any one product's knowledge — and
+ * because the activity keeps its name, its arguments and its place in
+ * `ApplyOp`, so no existing Op changes shape.
+ *
+ * The lexicons are reached by dynamic import at call time, never by a static
+ * one: this package must not depend on them. A project applying a target
+ * already lists that lexicon in its config, so the module is there; when it is
+ * not, the failure names the package to install.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { normalizeApply } from "../../apply.js";
+import { importLexiconPackage } from "../../lexicon-module.js";
+const execAsync = promisify(exec);
+/**
+ * Render a kustomization directory to parsed documents (#1548): `kustomize
+ * build`, falling back to kubectl's vendored kustomize when the standalone
+ * binary is absent. The 64MiB buffer matches the k8s/helm lexicons' bound —
+ * a big overlay renders megabytes. YAML parsing is js-yaml's multi-doc
+ * loader, the same one the k8s applier uses on files.
+ */
+async function renderKustomization(dir) {
+    const quoted = `'${dir.replace(/'/g, "'\\''")}'`;
+    const run = (cmd) => execAsync(cmd, { maxBuffer: 64 * 1024 * 1024 });
+    let stdout;
+    try {
+        ({ stdout } = await run(`kustomize build ${quoted}`));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!/ENOENT|not found|command not found|127/.test(message))
+            throw err;
+        ({ stdout } = await run(`kubectl kustomize ${quoted}`));
+    }
+    const { loadAll } = await import("js-yaml");
+    const documents = [];
+    for (const doc of loadAll(stdout)) {
+        if (doc && typeof doc === "object" && !Array.isArray(doc))
+            documents.push(doc);
+    }
+    return documents;
+}
+/**
+ * Load the k8s lexicon's apply. A variable specifier, so `tsc` does not
+ * statically resolve a package this one deliberately does not depend on — the
+ * same mechanism core's activity registry uses to load a lexicon's activities.
+ */
+async function loadK8sApplier() {
+    const spec = "@intentius/chant-lexicon-k8s/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "kubectl" needs @intentius/chant-lexicon-k8s, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). Kubernetes applies moved out of the ` +
+            `op lexicon in chant #1075; install the k8s lexicon and list it in chant.config.ts.`);
+    }
+    if (typeof mod.applyManifest !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-k8s exports no applyManifest — it predates chant #1075");
+    }
+    return mod.applyManifest;
+}
+/**
+ * Load the azure lexicon's `azApply` (#1448). Same variable-specifier trick as
+ * {@link loadK8sApplier}, for the same reason.
+ */
+async function loadAzureApplier() {
+    const spec = "@intentius/chant-lexicon-azure/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "arm" needs @intentius/chant-lexicon-azure, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). ARM applies go through the azure ` +
+            `lexicon's per-resource applier since chant #1448; install the azure lexicon and list it ` +
+            `in chant.config.ts.`);
+    }
+    const { azApply, toApplyResult } = mod;
+    if (typeof azApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-azure exports no azApply — it predates chant #707");
+    }
+    if (typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-azure exports no toApplyResult — it predates chant #1449");
+    }
+    return async (args, signal) => toApplyResult(await azApply(args, signal));
+}
+/**
+ * Load the gcp lexicon's `gcpApply` (#1449). Same variable-specifier trick as
+ * {@link loadK8sApplier}, for the same reason.
+ */
+async function loadGcpApplier() {
+    const spec = "@intentius/chant-lexicon-gcp/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "gcp" needs @intentius/chant-lexicon-gcp, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). GCP applies go through the gcp ` +
+            `lexicon's native applier since chant #1449; install the gcp lexicon and list it ` +
+            `in chant.config.ts.`);
+    }
+    const { gcpApply, toApplyResult } = mod;
+    if (typeof gcpApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-gcp exports no gcpApply — it predates chant #706");
+    }
+    if (typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-gcp exports no toApplyResult — it predates chant #1449");
+    }
+    return async (args, signal) => toApplyResult(await gcpApply(args, signal));
+}
+/**
+ * Load the fly lexicon's `flyApply` (#1449). Same variable-specifier trick as
+ * {@link loadK8sApplier}, for the same reason.
+ */
+async function loadFlyApplier() {
+    const spec = "@intentius/chant-lexicon-fly/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "fly" needs @intentius/chant-lexicon-fly, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). Fly applies go through the fly ` +
+            `lexicon's native flaps applier since chant #1449; install the fly lexicon and list it ` +
+            `in chant.config.ts.`);
+    }
+    const { flyApply, toApplyResult } = mod;
+    if (typeof flyApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-fly exports no flyApply — it predates chant #739");
+    }
+    if (typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-fly exports no toApplyResult — it predates chant #1449");
+    }
+    return async (args, signal) => toApplyResult(await flyApply(args, signal));
+}
+/**
+ * Load the grafana lexicon's `grafanaApply` (#3011). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason. The activities subpath,
+ * not the package root or `op/builders`: those hold the typed step builder,
+ * while the activity itself (and its `toApplyResult`) lives here.
+ */
+async function loadGrafanaApplier() {
+    const spec = "@intentius/chant-lexicon-grafana/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "grafana" needs @intentius/chant-lexicon-grafana, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). Grafana applies go through the grafana ` +
+            `lexicon's API applier (chant #2948); install the grafana lexicon and list it in chant.config.ts.`);
+    }
+    const { grafanaApply, toApplyResult } = mod;
+    if (typeof grafanaApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-grafana exports no grafanaApply — it predates chant #2948");
+    }
+    if (typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-grafana exports no toApplyResult — it predates chant #2948");
+    }
+    return async (args, signal) => toApplyResult(await grafanaApply(args, signal));
+}
+/**
+ * Load the sql lexicon's `clickhouseApply` (#3208). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason.
+ */
+async function loadClickHouseApplier() {
+    const spec = "@intentius/chant-lexicon-sql/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "clickhouse" needs @intentius/chant-lexicon-sql, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). ClickHouse applies go through the sql ` +
+            `lexicon's applier (chant #3208); install the sql lexicon and list it in chant.config.ts.`);
+    }
+    const { clickhouseApply, toApplyResult } = mod;
+    if (typeof clickhouseApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-sql exports no clickhouseApply — it predates chant #3208");
+    }
+    if (typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-sql exports no toApplyResult — it predates chant #3208");
+    }
+    return async (args, signal) => toApplyResult(await clickhouseApply(args, signal));
+}
+/**
+ * Load the sql lexicon's `postgresApply` (#3280). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason.
+ */
+async function loadPostgresApplier() {
+    const spec = "@intentius/chant-lexicon-sql/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "postgres" needs @intentius/chant-lexicon-sql, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). Postgres applies go through the sql ` +
+            `lexicon's applier (chant #3280); install the sql lexicon and list it in chant.config.ts.`);
+    }
+    const { postgresApply, toApplyResult } = mod;
+    if (typeof postgresApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-sql exports no postgresApply — it predates chant #3280");
+    }
+    if (typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-sql exports no toApplyResult — it predates chant #3208");
+    }
+    return async (args, signal) => toApplyResult(await postgresApply(args, signal));
+}
+/**
+ * Load the prometheus lexicon's `rulerApply` (#3372). Same variable-specifier
+ * trick as {@link loadK8sApplier}, for the same reason.
+ */
+async function loadRulerApplier() {
+    const spec = "@intentius/chant-lexicon-prometheus/api/apply";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "ruler" needs @intentius/chant-lexicon-prometheus, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). Ruler applies go through the prometheus ` +
+            `lexicon's applier (chant #3372); install the prometheus lexicon and list it in chant.config.ts.`);
+    }
+    const { rulerApply, toApplyResult } = mod;
+    if (typeof rulerApply !== "function" || typeof toApplyResult !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-prometheus exports no rulerApply — it predates chant #3372");
+    }
+    return async (args, signal) => toApplyResult(await rulerApply(args, signal));
+}
+/** Load the prometheus lexicon's `rulerRollback` (#3372), the compensation twin of {@link loadRulerApplier}. */
+async function loadRulerRollback() {
+    const spec = "@intentius/chant-lexicon-prometheus/api/apply";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`rollback for target "ruler" needs @intentius/chant-lexicon-prometheus, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). Install the prometheus lexicon and list it in chant.config.ts.`);
+    }
+    if (typeof mod.rulerRollback !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-prometheus exports no rulerRollback — it predates chant #3372");
+    }
+    return mod.rulerRollback;
+}
+/**
+ * Load the aws lexicon's `awsApply` (#1449). Same variable-specifier trick as
+ * {@link loadK8sApplier}, for the same reason.
+ */
+async function loadAwsApplier() {
+    const spec = "@intentius/chant-lexicon-aws/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`apply target "cloudformation" needs @intentius/chant-lexicon-aws, which could not be loaded ` +
+            `(${err instanceof Error ? err.message : String(err)}). CloudFormation applies go through the ` +
+            `aws lexicon's native applier since chant #1449; install the aws lexicon and list it ` +
+            `in chant.config.ts.`);
+    }
+    if (typeof mod.awsApply !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-aws exports no awsApply — it predates chant #1446");
+    }
+    return mod.awsApply;
+}
+/**
+ * Load the aws lexicon's `rollbackStack` (#1449) — the compensation twin of
+ * {@link loadAwsApplier}.
+ */
+async function loadAwsRollback() {
+    const spec = "@intentius/chant-lexicon-aws/op/activities";
+    let mod;
+    try {
+        mod = (await importLexiconPackage(spec));
+    }
+    catch (err) {
+        throw new Error(`rollback for target "cloudformation" needs @intentius/chant-lexicon-aws, which could not be ` +
+            `loaded (${err instanceof Error ? err.message : String(err)}). CloudFormation rollback goes ` +
+            `through the aws lexicon's rollbackStack since chant #1449; install the aws lexicon and ` +
+            `list it in chant.config.ts.`);
+    }
+    if (typeof mod.rollbackStack !== "function") {
+        throw new Error("the installed @intentius/chant-lexicon-aws exports no rollbackStack — it predates chant #1449");
+    }
+    return mod.rollbackStack;
+}
+/**
+ * Sensible default build output per target. kubectl takes a directory (all
+ * manifests), so `dist`; kustomize's "output" is the kustomization DIRECTORY
+ * the render reads. The file targets take the file their lexicon's build
+ * conventionally emits: `template.json` for CloudFormation/ARM, `dist/gcp.yaml`
+ * (the CNRM manifest) for gcp, `dist/fly.json` (the serialized plan) for fly,
+ * `dist/grafana.json` (the index the grafana serializer writes, with the
+ * dashboard files beside it) for grafana, `dist/schema.json` (the sql
+ * lexicon's build output) for clickhouse and postgres, `dist/rules.yml` (the
+ * rule file, with `alertmanager.yml` beside it) for ruler. Pure — exported for
+ * testing.
+ */
+export function defaultOutput(target) {
+    switch (target) {
+        case "kubectl":
+        case "kustomize":
+            return "dist";
+        case "gcp":
+            return "dist/gcp.yaml";
+        case "fly":
+            return "dist/fly.json";
+        case "ruler":
+            return "dist/rules.yml";
+        case "grafana":
+            return "dist/grafana.json";
+        case "clickhouse":
+        case "postgres":
+            return "dist/schema.json";
+        default:
+            return "template.json";
+    }
+}
+/**
+ * Collapse a #1446 apply envelope onto the one result shape this activity
+ * returns, logging the counts (and warning on skips) as it goes. The envelope
+ * is normalized through core's `normalizeApply`, so the counts are the lengths
+ * of `NormalizedApply`'s three arrays — nothing re-derived, nothing invented.
+ */
+function collapseEnvelope(envelope, label) {
+    const n = normalizeApply(envelope);
+    console.log(`[${label}] applied ${n.applied.length} resource(s)` +
+        (n.pruned.length > 0 ? `; pruned ${n.pruned.length}` : ""));
+    // #1447: a resource the applier made no call for is reported, not dropped —
+    // otherwise a partial apply reads as a full one. The per-resource reasons
+    // ride the envelope; the count is what a later step reads.
+    if (n.notAttempted.length > 0) {
+        console.warn(`[${label}] NOT attempted: ${n.notAttempted.length} resource(s)`);
+        for (const skip of n.notAttempted) {
+            console.warn(`[${label}]   ${skip.kind}/${skip.name}: ${skip.reason}${skip.detail ? ` (${skip.detail})` : ""}`);
+        }
+    }
+    return {
+        applied: n.applied.length,
+        pruned: n.pruned.length,
+        notAttempted: n.notAttempted.length,
+    };
+}
+/**
+ * Apply declared source to the cloud via the target's native mechanism.
+ * Deletes (when enabled) ride that mechanism's own delete path — marker-scoped
+ * on `kubectl`, tag-scoped on `arm`, label-scoped on `gcp`, marker- and
+ * app-scoped on `fly`, label-scoped on `grafana`, comment-marker-scoped on
+ * `clickhouse` and `postgres`, and stack-scoped on
+ * `cloudformation`, where the deploy
+ * itself removes resources dropped from the template and `deleteMode` changes
+ * nothing: a resource CFN did not create is not in the stack. See
+ * {@link DeleteMode}.
+ *
+ * The appliers are injectable so this dispatcher can be tested without the
+ * product lexicons present; production resolves them through
+ * {@link loadK8sApplier} / {@link loadAzureApplier} / {@link loadAwsApplier} /
+ * {@link loadGcpApplier} / {@link loadFlyApplier} / {@link loadGrafanaApplier}.
+ */
+export async function nativeApply(args, signal, applier, azureApplier, renderer = renderKustomization, awsApplier, gcpApplier, flyApplier, grafanaApplier, clickhouseApplier, postgresApplier, rulerApplier) {
+    const output = args.output ?? defaultOutput(args.target);
+    const deleteMode = args.deleteMode ?? "never";
+    if (args.target === "kubectl" || args.target === "kustomize") {
+        const apply = applier ?? (await loadK8sApplier());
+        // kustomize (#1548): `output` is the kustomization DIRECTORY; render it
+        // and hand the documents to the SAME k8s applier inline — stamping, the
+        // marker-scoped prune, and the conflict semantics are identical.
+        const kustomized = args.target === "kustomize"
+            ? { documents: await renderer(output), manifest: `kustomize:${output}` }
+            : { manifest: output };
+        const result = await apply({
+            ...kustomized,
+            environment: args.env,
+            deleteMode,
+            ...(args.forceConflicts !== undefined ? { force: args.forceConflicts } : {}),
+        }, signal);
+        // The field manager is the operator's detail and stays on the log; the
+        // result is the count projection like every other target's. The k8s
+        // applier's contract has no skip path — a document it cannot classify
+        // throws — so NOT-ATTEMPTED is structurally zero here.
+        console.log(`applied ${result.applied.length} object(s) as field manager "${result.fieldManager}"` +
+            (result.pruned.length > 0 ? `; pruned ${result.pruned.length}` : ""));
+        return {
+            applied: result.applied.length,
+            pruned: result.pruned.length,
+            notAttempted: 0,
+        };
+    }
+    if (args.target === "arm") {
+        const apply = azureApplier ?? (await loadAzureApplier());
+        const envelope = await apply({
+            templatePath: output,
+            resourceGroup: args.env,
+            // The same variable azure's read path honours, so an ARM apply lands
+            // wherever `--live` is already looking (floci-az, or real Azure when
+            // unset).
+            ...(process.env.AZURE_ENDPOINT_URL ? { endpoint: process.env.AZURE_ENDPOINT_URL } : {}),
+            prune: deleteMode !== "never",
+        }, signal);
+        return collapseEnvelope(envelope, args.env);
+    }
+    if (args.target === "gcp") {
+        // gcp (#1449): the gcp lexicon's per-resource applier. Only the manifest
+        // path and the prune switch cross this seam — endpoint (`GCP_ENDPOINT_URL`)
+        // and project (`GOOGLE_CLOUD_PROJECT` / CNRM annotation) are gcpApply's own
+        // env resolution, and `env` is a log label here: GCP has no stack or
+        // resource-group equivalent for it to name.
+        const apply = gcpApplier ?? (await loadGcpApplier());
+        const envelope = await apply({ manifestPath: output, prune: deleteMode !== "never" }, signal);
+        // #1447's skips and the not-prunable kinds both ride the envelope as
+        // NOT-ATTEMPTED entries — one bucket, per-entry reasons, one count out.
+        return collapseEnvelope(envelope, args.env);
+    }
+    if (args.target === "fly") {
+        // fly (#1449): the fly lexicon's flaps applier. Only the plan path and the
+        // prune switch cross this seam — the endpoint (`FLY_FLAPS_BASE_URL`,
+        // mudflaps locally) and token (`FLY_API_TOKEN`) are flyApply's own env
+        // resolution, and `env` is a log label here: the app names live in the
+        // plan itself.
+        const apply = flyApplier ?? (await loadFlyApplier());
+        const envelope = await apply({ planPath: output, prune: deleteMode !== "never" }, signal);
+        // The six applied classes and five pruned classes are already flattened
+        // into the envelope by fly's own toApplyResult; here they are just counts.
+        return collapseEnvelope(envelope, args.env);
+    }
+    if (args.target === "grafana") {
+        // grafana (#3011): the grafana lexicon's API applier. Unlike gcp and fly,
+        // env is not just a label here: it selects `grafana.profiles.<env>`, the
+        // Grafana observe and export already read. The ownership marker comes from
+        // the project's chant.config.ts inside grafanaApply.
+        const apply = grafanaApplier ?? (await loadGrafanaApplier());
+        const envelope = await apply({ indexPath: output, environment: args.env, prune: deleteMode !== "never" }, signal);
+        // No binding or a refused token rides the envelope as NOT-ATTEMPTED for
+        // every resource, as do library panels and anything else prune could
+        // not consider.
+        return collapseEnvelope(envelope, args.env);
+    }
+    if (args.target === "clickhouse") {
+        // clickhouse (#3208): the sql lexicon's applier. env selects
+        // `sql.profiles.<env>`, the server observe and import read; the marker
+        // comes from the project's chant.config.ts inside clickhouseApply.
+        const apply = clickhouseApplier ?? (await loadClickHouseApplier());
+        const envelope = await apply({ buildPath: output, environment: args.env, prune: deleteMode !== "never" }, signal);
+        // A refused rebuild and a column drop an additive apply withholds ride the
+        // envelope as NOT-ATTEMPTED, so an Op can gate on them.
+        return collapseEnvelope(envelope, args.env);
+    }
+    if (args.target === "postgres") {
+        // postgres (#3280): the sql lexicon's applier. env selects
+        // `sql.profiles.<env>`; the marker and the lock and statement timeouts
+        // come from the project's chant.config.ts inside postgresApply.
+        const apply = postgresApplier ?? (await loadPostgresApplier());
+        const envelope = await apply({ buildPath: output, environment: args.env, prune: deleteMode !== "never" }, signal);
+        // A refused expand-and-contract change, a column drop an additive apply
+        // withholds, and the objects of a rolled-back transaction ride the
+        // envelope as NOT-ATTEMPTED, so an Op can gate on them.
+        return collapseEnvelope(envelope, args.env);
+    }
+    if (args.target === "ruler") {
+        // ruler (#3372): the prometheus lexicon's applier. env selects
+        // `prometheus.profiles.<env>`, whose ruler names the tenant and the
+        // namespaces the project owns. A delete stays inside those namespaces.
+        const apply = rulerApplier ?? (await loadRulerApplier());
+        const envelope = await apply({ buildPath: output, environment: args.env, prune: deleteMode !== "never" }, signal);
+        // A group with no declared namespace, a plain Prometheus or Alertmanager
+        // with no upload API, and a refused write ride the envelope as
+        // NOT-ATTEMPTED, so an Op can gate on them.
+        return collapseEnvelope(envelope, args.env);
+    }
+    // cloudformation (#1449): the aws lexicon's native applier. env is the stack
+    // name and output the template path; endpoint resolution (#1694) and
+    // capability derivation (#980) are awsApply's own, so nothing else is passed.
+    const apply = awsApplier ?? (await loadAwsApplier());
+    const result = await apply({ templatePath: output, stackName: args.env }, signal);
+    // The stack, its settled status and the action are the operator's detail and
+    // stay on the log. The result is the same count projection as every other
+    // target's, with the stack as the unit: one settled deploy, one applied.
+    console.log(`${result.action}: stack ${result.stackName} (${result.status})`);
+    return { applied: 1, pruned: 0, notAttempted: 0 };
+}
+/**
+ * Whether a target has a mapped native rollback for {@link compensateApply} to
+ * run without an explicit `compensate.command`. `cloudformation` is the only
+ * one today — the aws lexicon's `rollbackStack`. This is the totality
+ * predicate `ApplyOp` checks at build time (#1449): a target outside it with
+ * no command has nothing a compensation could run, so the op refuses to build
+ * with compensation on rather than warn at rollback time.
+ */
+export function hasNativeRollback(target) {
+    return target === "cloudformation" || target === "ruler";
+}
+/**
+ * Compensation step (saga rollback) for a partial apply failure. Runs the
+ * explicit `command` if given; otherwise `cloudformation` rolls back natively
+ * through the aws lexicon's `rollbackStack` (#1449 — CloudFormation
+ * `RollbackStack` over the Query API, no CLI in the path).
+ *
+ * Compensation is total for built ops: `ApplyOp` refuses at build time to wire
+ * this activity for a target with neither a native rollback
+ * ({@link hasNativeRollback}) nor an explicit `command`, so the no-rollback
+ * branch below is unreachable from an op it built. It stays as a throw, not a
+ * warn — a hand-assembled op that reaches it must fail loudly, because partial
+ * state should never look reverted when it isn't.
+ *
+ * `rollback` is injectable for tests; production resolves it through
+ * {@link loadAwsRollback}.
+ */
+export async function compensateApply(args, signal, rollback, rulerRollback) {
+    if (args.command) {
+        const { stdout, stderr } = await execAsync(args.command, { signal });
+        if (stdout)
+            console.log(stdout);
+        if (stderr)
+            console.error(stderr);
+        return { command: args.command };
+    }
+    if (args.target === "cloudformation") {
+        const roll = rollback ?? (await loadAwsRollback());
+        const result = await roll({ stackName: args.env }, signal);
+        return {
+            stackName: result.stackName,
+            rolledBack: result.rolledBack,
+            ...(result.status !== undefined ? { status: result.status } : {}),
+        };
+    }
+    if (args.target === "ruler") {
+        // ruler (#3372): re-apply the previous group set the last apply saved.
+        const roll = rulerRollback ?? (await loadRulerRollback());
+        const result = await roll({ buildPath: args.output ?? defaultOutput("ruler"), environment: args.env }, signal);
+        console.log(result.hadSnapshot
+            ? `[${args.env}] ruler rollback: restored ${result.restored} group(s), removed ${result.removed}` +
+                (result.alertmanagerRestored ? ", restored the Alertmanager config" : "")
+            : `[${args.env}] ruler rollback: no apply left a snapshot, nothing to restore`);
+        return { restored: result.restored, removed: result.removed };
+    }
+    // Defensive: unreachable from an ApplyOp, which refuses this combination at
+    // build time (#1449). Reaching it means the op was assembled without that
+    // check, and the honest outcome is a failure that says the state stands.
+    throw new Error(`no automatic rollback for target "${args.target}" — the partial apply to ${args.env} was NOT ` +
+        `reverted and cannot be. ApplyOp refuses compensate for this target at build time; either ` +
+        `supply compensate.command or use a target with a mapped rollback (cloudformation, ruler).`);
+}

package/dist/op/activities/build.js

@@ -0,0 +1,18 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/**
+ * Run an npm build script (`build` by default) in the given project directory.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function chantBuild(args, signal) {
+    const { stdout, stderr } = await execAsync(`npm run ${args.script ?? "build"}`, {
+        cwd: args.path,
+        env: { ...process.env, ...args.env },
+        signal,
+    });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+}

package/dist/op/activities/change-coverage.js

@@ -0,0 +1,40 @@
+/**
+ * changeCoverage — the forward coverage check (#2773) as an Op activity, for
+ * an Op that changes the checkout (#2748) to run on its own diff.
+ *
+ * Such an Op's leased steps work in a worktree of their own on
+ * `chant/work/[<member>/]<item>`. Given that worktree as `cwd`
+ * (`workLeaseOutput("worktree")`) and no `range`, the activity checks the
+ * commits the branch holds beyond the main worktree's HEAD, with the branch's
+ * item as the work item in hand, exactly as `chant workspace check --changes
+ * <base>..HEAD --work <item>` would. A `range` or `work` given replaces what
+ * the branch says.
+ *
+ * The step fails when the check's severity is `fail` and it has a finding,
+ * or when the check can't run; otherwise it returns the document's findings
+ * and summary for later steps. The workspace code loads on first call, so
+ * importing core's activities loads nothing under `workspace/` (#2525 rule 5).
+ */
+export async function changeCoverage(args = {}) {
+    const { checkChanges, workBranchChanges } = await import("../../workspace/changes.js");
+    const cwd = args.cwd ?? process.cwd();
+    const branch = args.range === undefined ? workBranchChanges(cwd) : undefined;
+    const range = args.range ?? branch?.range;
+    if (range === undefined)
+        throw new Error(`changeCoverage: ${cwd} is not on a chant/work/ branch, so give the range to check`);
+    const work = args.work ?? branch?.work;
+    const { doc } = await checkChanges({ cwd, range, ...(work !== undefined ? { work } : {}), ...(args.severity ? { severity: args.severity } : {}) });
+    if ("error" in doc)
+        throw new Error(`changeCoverage: ${doc.error.code}: ${doc.error.message}`);
+    const result = {
+        ok: doc.ok,
+        range: doc.range,
+        work: doc.work?.record ?? null,
+        severity: doc.severity,
+        findings: doc.findings.map(({ code, path, message, severity, records, triage }) => ({ code, path, message, severity, records, triage })),
+        summary: doc.summary,
+    };
+    if (!doc.ok)
+        throw new Error(`changeCoverage: ${doc.findings.length} change ${doc.findings.length === 1 ? "finding" : "findings"} at severity fail: ${doc.findings.map((f) => `${f.code} ${f.path}`).join(", ")}`);
+    return result;
+}