@intentius/chant 0.124.13 → 0.124.15

package/dist/op/activities/change-set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../../src/op/activities/change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,EAIL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAO1B,MAAM,WAAW,oBAAoB;IACnC,8GAA8G;IAC9G,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,mGAAmG;AACnG,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAMlG;AAED,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;CACrB;AAMD,2GAA2G;AAC3G,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,0BAA0B,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAOjI;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,+GAA+G;IAC/G,OAAO,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC5B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAWjG"}
+{"version":3,"file":"change-set.d.ts","sourceRoot":"","sources":["../../../src/op/activities/change-set.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAO1B,MAAM,WAAW,oBAAoB;IACnC,8GAA8G;IAC9G,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AAED,mGAAmG;AACnG,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAMlG;AAED,MAAM,WAAW,0BAA0B;IACzC,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;CACrB;AAMD,2GAA2G;AAC3G,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,0BAA0B,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAOjI;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAajG"}

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

@@ -0,0 +1,67 @@
+/**
+ * Op activities for the change-set document (#3181).
+ *
+ * A combined run over several members plans each one in its own step, joins
+ * the parts with {@link composeChangeSet}, and binds its gate to the
+ * document's digest:
+ *
+ * ```ts
+ * phase("Plan", [
+ *   terraformPlan({ root: "estate", id: "estate" }),          // a choudoufu member
+ *   lifecyclePlanChangeSet({ member: "delivery", env: "prod", cwd: "delivery", id: "delivery" }),
+ *   readChangeSetPart({ member: "warden", planner: "warden", file: "warden.plan.json", id: "warden" }),
+ *   composeChangeSet({ parts: [estate.out.changeSet, delivery.out.part, warden.out.part], id: "change-set" }),
+ * ]),
+ * phase("Approve", [gate("approve-run", { plan: stepOutput("change-set", "digest") })]),
+ * ```
+ *
+ * Each activity here only reads: a plan, a file, or the parts it is handed.
+ */
+import { exec } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+import { composeChangeSet as compose, lifecyclePlanPart, readChangeSetPartFile, reconcilePlanPart, } from "../../change-set.js";
+import { CHANT_VERSION } from "../../cli/version.js";
+const execAsync = promisify(exec);
+/** Join members' parts into one change-set document. Fails when two parts name the same member. */
+export async function composeChangeSet(args) {
+    const parts = args.parts ?? [];
+    const missing = parts.findIndex((p) => !p || typeof p !== "object" || !p.member);
+    if (missing !== -1)
+        throw new Error(`composeChangeSet: parts[${missing}] is not a change-set part; did the step that plans it run?`);
+    const document = compose(parts, { chant: CHANT_VERSION });
+    return { document, digest: document.digest, summary: document.summary };
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** `chant lifecycle plan <env> --json` in a chant member's directory, as that member's change-set part. */
+export async function lifecyclePlanChangeSet(args, signal) {
+    const { stdout } = await execAsync(`chant lifecycle plan ${shellQuote(args.env)}${args.owned ? " --owned" : ""} --json`, {
+        cwd: args.cwd ? resolve(args.cwd) : process.cwd(),
+        signal,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    return { part: lifecyclePlanPart({ member: args.member, plan: JSON.parse(stdout) }) };
+}
+/**
+ * A plan another step or job wrote to a file, as a member's part. A warden
+ * plan is the reconcile `ChangeSet` (`@intentius/chant/reconcile`), or an
+ * array of them, one per cycle and org. A sql plan is already a part
+ * (`@intentius/chant-lexicon-sql/change-set`), renamed to `member` here.
+ */
+export async function readChangeSetPart(args) {
+    const plan = JSON.parse(readFileSync(resolve(args.file), "utf-8"));
+    const lexicon = args.lexicon !== undefined ? { lexicon: args.lexicon } : {};
+    switch (args.planner) {
+        case "chant":
+            return { part: lifecyclePlanPart({ member: args.member, plan: plan, ...lexicon }) };
+        case "warden":
+            return { part: reconcilePlanPart({ member: args.member, plan: plan, ...lexicon }) };
+        case "sql":
+            return { part: readChangeSetPartFile(plan, "sql", args.member, args.lexicon) };
+        default:
+            throw new Error(`readChangeSetPart: no adapter for planner ${String(args.planner)}; terraform-family plans come from terraformPlan's changeSet`);
+    }
+}

package/dist/op/activities/converge.js

@@ -0,0 +1,492 @@
+/**
+ * `convergeTick` — the activity a `ConvergeOp`-generated Op's Converge
+ * phase runs (../../composites/converge-op.ts). One call is one tick:
+ * observe (shell to `chant lifecycle plan`/`chant components status`, the
+ * same CLI surface `reconcilePr`/`lifecycleDiff` already shell to — see
+ * ./reconcile.ts, ./lifecycle.ts) -> classify (the pure rule table
+ * evaluator, core's `evaluatePredicate`, then this
+ * activity's own runtime backstop re-classifying each dispatch target's verb
+ * class before it runs — see `verbClassAllowedToDispatch` below) -> dispatch
+ * within budget (`chant run <op>`, the existing local runner — a gated
+ * dispatched Op ends `gated` with its pending fact on the ledger, exit code 3,
+ * which this tick turns into a `"gated"` outcome) -> record (one line to the
+ * converge ledger, `../../lifecycle/converge-ledger`).
+ *
+ * Deliberately monolithic, matching `reconcilePr`'s shape (one activity that
+ * derives the change set, regenerates, and opens the PR) rather than
+ * `ApplyOp`'s Build/Plan/Approve/Apply phase split — a converge tick's
+ * "classify against a rule table, then dispatch" step can't be decomposed
+ * into separate declared steps, because *which* rules fire is a runtime fact
+ * discovered only once live symptoms are read, while an Op's phase structure
+ * is fully static at build time. Splitting `Observe` into its own phase (the
+ * composite still does, for the per-phase visibility WatchOp/ApplyOp/
+ * ReconcileOp all get) and threading its result into this activity's `args` via a
+ * step-output reference (#1290) rather than a search-attribute round-trip is
+ * the seam this module *does* use the new dataflow for.
+ *
+ * `unknown` never remediates: whatever a rule's own predicate says, a tick
+ * whose derived symptom is `status: "unknown"` forces every fired `run`
+ * action to `report` instead — the honesty requirement is enforced here, at
+ * the one place a bad rule table can't route around it, not only trusted to
+ * rule authors.
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { evaluatePredicate, DEFAULT_FLAP_THRESHOLD, } from "../converge-rule.js";
+import { classifyOpVerbClass } from "../op-verb-class.js";
+import { discoverOps } from "../discover.js";
+import { deriveSymptoms, parseResourceObservation, CONVERGE_RESOURCE_ENV, } from "../../lifecycle/symptoms.js";
+import { appendConvergeRecord, readConvergeLedger, consecutiveRuleFires, componentVerdicts, sanitizeLedgerText, } from "../../lifecycle/converge-ledger.js";
+import { resolveApprovalUrl } from "../../lifecycle/gate-ledger.js";
+import { fetchLifecycle, pushLifecycleReport } from "../../lifecycle/git.js";
+const execAsync = promisify(exec);
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Cap a subprocess failure's raw output to one sanitized line — a ledger
+ * record (`converge-ledger.ts`'s `appendConvergeRecord`) is one line of JSON,
+ * and a multi-line/oversized `stderr` folded straight into `outcome.reason`
+ * would break that. Not a fix for the ledger-durability bug (#1936,
+ * `writeBlobToPath`'s corruption under concurrent writes — fixed at the root
+ * in a separate PR); this only keeps one dispatch failure's own message from
+ * corrupting the line it's written into.
+ *
+ * The rule now lives next to the record it protects (`sanitizeLedgerText`,
+ * #2027), since a component verdict's `detail` needs the same cap; this stays
+ * as the dispatch path's name for it.
+ */
+export const sanitizeOneLine = sanitizeLedgerText;
+/** Run `chant lifecycle plan <env> --live --json` and parse its `ChangeSet`. */
+async function observeChangeSet(env, signal) {
+    const { stdout } = await execAsync(`chant lifecycle plan ${shellQuote(env)} --live --json`, { signal });
+    return JSON.parse(stdout);
+}
+/** Run `chant components status <env> --live --json` and parse its rows. */
+async function observeStatusRows(env, signal) {
+    const { stdout } = await execAsync(`chant components status ${shellQuote(env)} --live --json`, { signal });
+    const parsed = JSON.parse(stdout);
+    return Array.isArray(parsed) ? parsed : parsed.rows;
+}
+/**
+ * `chant run <op>`'s exit code for a run that stopped at an unapproved gate
+ * (#2119 — `../../../../../packages/core/src/cli/handlers/run.ts`'s
+ * `GATED_EXIT_CODE`). The typed signal that replaced the old string match
+ * against `LocalGateUnsupportedError`'s message: since #2119 the executor
+ * records the pending fact itself and ends with `status: "gated"`, so a tick
+ * no longer has to reconstruct a gate from an error string, and no longer
+ * writes the pending fact on the executor's behalf.
+ */
+const GATED_EXIT_CODE = 3;
+/**
+ * The gate a gated `chant run` stopped at, read off its JSON result (#2119) —
+ * pure, unit-tested directly rather than only through `dispatchOp`'s
+ * subprocess plumbing. `undefined` when the output says nothing about a gate.
+ *
+ * Reads `gate.name`, matching a real `OpRunStatus`/`OpRunRecord`
+ * (`../runtime.ts`'s own `gate?: { name: string; since: string }`) — a gated
+ * run's record never carries a nested field literally named `gate`. Checking
+ * `gate.gate` instead (chant#2396) is `typeof undefined === "string"`, always
+ * false, so every gated dispatch fell through to the regex below, which also
+ * never matches a `--json` result: the phrase it looks for belongs to the
+ * human-readable render `--json` mode suppresses. The regex stays as the
+ * fallback for exactly that human-mode case, where the caller's output is
+ * prose rather than JSON.
+ */
+export function classifyDispatchFailure(raw) {
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("{"))
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed.status === "gated" && typeof parsed.gate?.name === "string") {
+                return { gateName: parsed.gate.name };
+            }
+        }
+        catch {
+            // Not this line's JSON — keep looking.
+        }
+    }
+    const match = /is gated on "([^"]+)"/.exec(raw);
+    return match ? { gateName: match[1] } : undefined;
+}
+/**
+ * Dispatch one matched `run` action via the existing local runner (`chant run
+ * <op> --json`). A gated target Op is gate-as-fact (#1485, closed by #2119):
+ * the target's own executor reads the gate ledger, records the pending fact,
+ * and exits {@link GATED_EXIT_CODE} — so this tick reads the gate off that
+ * result rather than parsing a refusal message, and records the `"gated"`
+ * outcome that names it. The pending fact itself is the executor's to write;
+ * duplicating it here is what "call the same executor code" rules out.
+ */
+async function dispatchOp(opName, signal, env) {
+    try {
+        await execAsync(`chant run ${shellQuote(opName)} --json`, { signal, ...(env ? { env: { ...process.env, ...env } } : {}) });
+        return { ok: true };
+    }
+    catch (err) {
+        const e = err;
+        const raw = e.stderr ?? e.message ?? String(err);
+        if (e.code === GATED_EXIT_CODE) {
+            const gate = classifyDispatchFailure(`${e.stdout ?? ""}\n${raw}`);
+            if (gate)
+                return { ok: false, error: sanitizeOneLine(raw), gateName: gate.gateName };
+        }
+        return { ok: false, error: sanitizeOneLine(raw) };
+    }
+}
+/**
+ * Verb class allowed to free-run for a given dial — the coarse first-pass
+ * gate: `"observe"` never dispatches anything (report only), `"reconcile"`
+ * and `"apply"` both allow *some* dispatch. Which verb classes each of those
+ * two actually permits is `OPS014`'s job at build time
+ * (`../../lint/post-synth/tmp014-converge-rule-refusals.ts`) and
+ * {@link verbClassAllowedToDispatch}'s job as this tick's own runtime
+ * backstop, below.
+ */
+function dialAllowsDispatch(dial) {
+    return dial === "reconcile" || dial === "apply";
+}
+/**
+ * Runtime backstop for issue #1484's Autonomy table (pre-merge review of
+ * #1954): `OPS014` already refuses, at build time, a rule table shaped to
+ * reach this point with a mutating dispatch outside `"apply"` or any
+ * destructive dispatch at all. This is the defense-in-depth check for a rule
+ * table that reached `convergeTick` without going through that build — the
+ * same "not authored through the checked path" concern
+ * `isWellFormedPredicate` already guards for a hand-assembled predicate (see
+ * `../../../../packages/core/src/op/converge-rule.ts`'s doc). Fail-closed:
+ * an unclassifiable target (`verbClass === undefined`, e.g. the target op
+ * couldn't be discovered/read) is never treated as safe to free-run — same
+ * fail-closed stance `classifyOpVerbClass` itself takes for an unrecognized
+ * activity `fn`.
+ */
+export function verbClassAllowedToDispatch(dial, verbClass) {
+    const effective = verbClass ?? "mutating";
+    if (effective === "read-only")
+        return true;
+    if (effective === "mutating")
+        return dial === "apply";
+    return false; // destructive: refused at runtime, unconditionally — see OPS014's doc on why the gate can never actually run.
+}
+/**
+ * Apply {@link verbClassAllowedToDispatch} to one planned "ran" outcome,
+ * downgrading it to "reported" (never silently dropped, never silently run)
+ * when the dial/verb-class pairing isn't one the tick may actually free-run.
+ * Pure — the impure part (discovering and classifying the target op) is
+ * {@link classifyDispatchTarget}, called by `convergeTick` before this.
+ */
+export function enforceVerbClassAtDispatch(outcome, dial, verbClass) {
+    if (outcome.action !== "ran")
+        return outcome;
+    if (verbClassAllowedToDispatch(dial, verbClass))
+        return outcome;
+    return {
+        ...outcome,
+        action: "reported",
+        reason: `runtime backstop: dial "${dial}" does not permit dispatching "${outcome.op}" ` +
+            `(${verbClass ?? "unclassifiable — treated as mutating, fail-closed"}) — OPS014 should already refuse ` +
+            `this at build; reporting instead of risking a silent authority escalation`,
+    };
+}
+/** Discover and classify a dispatch target's own verb class. Never throws: an op that can't be discovered/read classifies as `undefined` (fail-closed via {@link verbClassAllowedToDispatch}), not silently as `"read-only"`. */
+async function classifyDispatchTarget(opName) {
+    try {
+        const { ops } = await discoverOps();
+        const target = ops.get(opName);
+        return target ? classifyOpVerbClass(target.config) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function planConvergeTick(symptom, rules, priorRecords, dial, budget) {
+    const firedRuleIds = [];
+    const outcomes = [];
+    let dispatched = 0;
+    for (const rule of rules) {
+        if (!evaluatePredicate(rule.when, symptom))
+            continue;
+        firedRuleIds.push(rule.id);
+        const threshold = rule.flapThreshold ?? DEFAULT_FLAP_THRESHOLD;
+        const consecutive = consecutiveRuleFires(priorRecords, rule.id);
+        if (consecutive >= threshold) {
+            outcomes.push({
+                ruleId: rule.id,
+                action: "skipped-flap",
+                reason: `fired ${consecutive + 1} consecutive ticks without clearing (threshold ${threshold}) — escalated to report`,
+            });
+            continue;
+        }
+        const action = rule.then;
+        // `unknown` never remediates, regardless of what the rule says.
+        if (symptom.status === "unknown" && action.kind === "run") {
+            outcomes.push({
+                ruleId: rule.id,
+                action: "reported",
+                reason: `symptom is unknown (${symptom.unobservedReasons.join(", ") || "unobserved"}) — unknown never remediates`,
+            });
+            continue;
+        }
+        if (action.kind === "report") {
+            outcomes.push({ ruleId: rule.id, action: "reported", reason: action.reason });
+            continue;
+        }
+        // action.kind === "run"
+        if (!dialAllowsDispatch(dial)) {
+            outcomes.push({ ruleId: rule.id, action: "reported", reason: `dial "${dial}" does not permit dispatch — report only`, op: action.op });
+            continue;
+        }
+        if (dispatched >= budget) {
+            outcomes.push({ ruleId: rule.id, action: "skipped-budget", op: action.op });
+            continue;
+        }
+        dispatched++;
+        outcomes.push({ ruleId: rule.id, action: "ran", op: action.op });
+    }
+    return { firedRuleIds, outcomes };
+}
+function summarizeOutcomes(outcomes) {
+    return {
+        remediated: outcomes.filter((o) => o.action === "ran").length,
+        reported: outcomes.filter((o) => o.action === "reported").length,
+        skippedBudget: outcomes.filter((o) => o.action === "skipped-budget").length,
+        skippedFlap: outcomes.filter((o) => o.action === "skipped-flap").length,
+        gated: outcomes.filter((o) => o.action === "gated").length,
+    };
+}
+function renderLog(env, s, counts) {
+    return (`converge(${env}): drifted=${s.updateCount + s.deleteCount} remediated=${counts.remediated} ` +
+        `reported=${counts.reported} skipped-budget=${counts.skippedBudget} skipped-flap=${counts.skippedFlap} ` +
+        `gated=${counts.gated} unobserved=${s.unobservedCount} adopted=${s.adoptCount}`);
+}
+// ── Resources an observer step reports (#2778) ──────────────────────────────
+/**
+ * How many consecutive most-recent ticks of `op` fired `ruleId` for
+ * `resource`. A rule of a ConvergeOp with an observer step fires once per
+ * resource, so its flap damping is counted per resource: a rule that
+ * restarts `app` on one tick and `hud` on the next is not flapping.
+ */
+export function consecutiveResourceFires(records, op, ruleId, resource) {
+    let count = 0;
+    for (let i = records.length - 1; i >= 0; i--) {
+        if (records[i].op !== op)
+            continue;
+        if (!records[i].outcomes.some((o) => o.ruleId === ruleId && o.resource === resource))
+            break;
+        count++;
+    }
+    return count;
+}
+/**
+ * The pure planning core of a resource tick (#2778): every rule against every
+ * observed resource, in authored order within each resource. The rules of
+ * {@link planConvergeTick} hold per resource: `unknown` never remediates, a
+ * `report()` never dispatches, the dial decides whether a `run()` may, and
+ * `budget` bounds the dispatches across the whole tick.
+ */
+export function planResourceTick(env, resources, rules, priorRecords, op, dial, budget) {
+    const fired = new Set();
+    const outcomes = [];
+    let dispatched = 0;
+    for (const resource of resources) {
+        const symptom = { env, resource: resource.name, status: resource.status, detail: resource.detail ?? "" };
+        for (const rule of rules) {
+            if (!evaluatePredicate(rule.when, symptom))
+                continue;
+            fired.add(rule.id);
+            const base = { ruleId: rule.id, resource: resource.name };
+            const threshold = rule.flapThreshold ?? DEFAULT_FLAP_THRESHOLD;
+            const consecutive = consecutiveResourceFires(priorRecords, op, rule.id, resource.name);
+            if (consecutive >= threshold) {
+                outcomes.push({
+                    ...base,
+                    action: "skipped-flap",
+                    reason: `fired for ${resource.name} ${consecutive + 1} consecutive ticks without clearing (threshold ${threshold}) — escalated to report`,
+                });
+                continue;
+            }
+            const action = rule.then;
+            if (resource.status === "unknown" && action.kind === "run") {
+                outcomes.push({
+                    ...base,
+                    action: "reported",
+                    reason: `${resource.name} is unknown (${resource.detail || "unobserved"}) — unknown never remediates`,
+                });
+                continue;
+            }
+            if (action.kind === "report") {
+                outcomes.push({ ...base, action: "reported", reason: action.reason });
+                continue;
+            }
+            if (!dialAllowsDispatch(dial)) {
+                outcomes.push({ ...base, action: "reported", reason: `dial "${dial}" does not permit dispatch — report only`, op: action.op });
+                continue;
+            }
+            if (dispatched >= budget) {
+                outcomes.push({ ...base, action: "skipped-budget", op: action.op });
+                continue;
+            }
+            dispatched++;
+            outcomes.push({ ...base, action: "ran", op: action.op });
+        }
+    }
+    return { firedRuleIds: [...fired], outcomes };
+}
+function renderResourceLog(env, resources, counts) {
+    const n = (status) => resources.filter((r) => r.status === status).length;
+    return (`converge(${env}): resources=${resources.length} in-sync=${n("in-sync")} drifted=${n("drifted")} unknown=${n("unknown")} ` +
+        `remediated=${counts.remediated} reported=${counts.reported} skipped-budget=${counts.skippedBudget} ` +
+        `skipped-flap=${counts.skippedFlap} gated=${counts.gated}`);
+}
+/** Run the planned dispatches of a tick, in place: the verb-class backstop, then `chant run`, then what came of it. */
+async function dispatchPlanned(outcomes, args, signal) {
+    for (const outcome of outcomes) {
+        if (outcome.action !== "ran" || !outcome.op)
+            continue;
+        const verbClass = await classifyDispatchTarget(outcome.op);
+        const backstopped = enforceVerbClassAtDispatch(outcome, args.dial, verbClass);
+        outcome.action = backstopped.action;
+        outcome.reason = backstopped.reason;
+        if (outcome.action !== "ran")
+            continue;
+        // A rule fired for one resource (#2778) hands the dispatched Op its name.
+        const env = outcome.resource !== undefined ? { [CONVERGE_RESOURCE_ENV]: outcome.resource } : undefined;
+        const result = await dispatchOp(outcome.op, signal, env);
+        if (!result.ok && result.gateName) {
+            // Gate-as-fact (#1485, closed by #2119): a terminal, durable,
+            // non-blocking fact — not an ordinary dispatch failure the operator
+            // keeps retrying. The target's own executor already wrote the pending
+            // record to `_gates/<op>.jsonl`; this outcome is the tick's account of
+            // the same event. See ../../../../../packages/core/src/lifecycle/
+            // gate-ledger.ts for how it resolves (`chant approve`, or a merged PR).
+            outcome.action = "gated";
+            outcome.gateName = result.gateName;
+            // #2028: the pending fact carries its address when this tick is running
+            // somewhere that has one (a PR/MR job). Absent otherwise — never guessed.
+            const url = resolveApprovalUrl();
+            if (url)
+                outcome.url = url;
+            outcome.reason =
+                `dispatch of "${outcome.op}" hit gate "${result.gateName}" — recorded as a pending fact, not retried; ` +
+                    `resolve with \`chant approve ${outcome.op} ${result.gateName}\`${url ? ` or by merging ${url}` : " or a merged PR"}`;
+        }
+        else if (!result.ok) {
+            outcome.action = "reported";
+            outcome.reason = `dispatch of "${outcome.op}" failed: ${result.error}`;
+        }
+    }
+}
+/** Push the tick's ledger record, and say whether it reached the remote (chant#2337). */
+async function pushTick() {
+    return pushLifecycleReport();
+}
+/** A tick of a ConvergeOp with an observer step (#2778): the observation is already in `args.observed`. */
+async function resourceTick(args, signal) {
+    const { resources } = parseResourceObservation(args.observed);
+    const ledger = await readConvergeLedger(args.env);
+    const plan = planResourceTick(args.env, resources, args.rules, ledger.records, args.opName, args.dial, args.budget);
+    await dispatchPlanned(plan.outcomes, args, signal);
+    const counts = summarizeOutcomes(plan.outcomes);
+    const log = renderResourceLog(args.env, resources, counts);
+    const drifted = resources.filter((r) => r.status === "drifted").length;
+    const { record } = await appendConvergeRecord({
+        op: args.opName,
+        env: args.env,
+        timestamp: new Date().toISOString(),
+        firedRuleIds: plan.firedRuleIds,
+        outcomes: plan.outcomes,
+        resources: resources.map((r) => ({
+            name: r.name,
+            status: r.status,
+            ...(r.detail ? { detail: sanitizeLedgerText(r.detail) } : {}),
+        })),
+        summary: {
+            drifted,
+            remediated: counts.remediated,
+            reported: counts.reported,
+            skippedBudget: counts.skippedBudget,
+            skippedFlap: counts.skippedFlap,
+            gated: counts.gated,
+            unobserved: resources.filter((r) => r.status === "unknown").length,
+            adopted: 0,
+        },
+        log,
+    });
+    const push = await pushTick();
+    return {
+        id: record.id,
+        drifted: drifted > 0,
+        remediated: record.summary.remediated,
+        reported: record.summary.reported,
+        skippedBudget: record.summary.skippedBudget,
+        skippedFlap: record.summary.skippedFlap,
+        gated: record.summary.gated ?? 0,
+        unobserved: record.summary.unobserved,
+        adopted: 0,
+        log: record.log,
+        ...push,
+    };
+}
+export async function convergeTick(args, signal) {
+    await fetchLifecycle().catch(() => undefined);
+    if (args.observed !== undefined)
+        return resourceTick(args, signal);
+    const [cs, statusRows, ledger] = await Promise.all([
+        observeChangeSet(args.env, signal),
+        observeStatusRows(args.env, signal),
+        readConvergeLedger(args.env),
+    ]);
+    const symptom = deriveSymptoms(args.env, cs, statusRows);
+    const plan = planConvergeTick(symptom, args.rules, ledger.records, args.dial, args.budget);
+    // Execute: only "ran" outcomes cause a subprocess dispatch. Before that
+    // dispatch, the runtime backstop (Finding A, #1954 pre-merge review)
+    // re-classifies the target and downgrades to "reported" if this dial/verb
+    // class pairing was never supposed to reach dispatch — OPS014 (build time)
+    // is the primary defense; this is what catches a rule table that reached
+    // `convergeTick` without going through it.
+    await dispatchPlanned(plan.outcomes, args, signal);
+    const counts = summarizeOutcomes(plan.outcomes);
+    const log = renderLog(args.env, symptom, counts);
+    const timestamp = new Date().toISOString();
+    const { record } = await appendConvergeRecord({
+        op: args.opName,
+        env: args.env,
+        timestamp,
+        firedRuleIds: plan.firedRuleIds,
+        outcomes: plan.outcomes,
+        // #2027: the per-component verdicts this tick already observed, kept
+        // instead of discarded once `summary`'s counts were derived from them.
+        components: componentVerdicts(statusRows),
+        summary: {
+            drifted: symptom.updateCount + symptom.deleteCount,
+            remediated: counts.remediated,
+            reported: counts.reported,
+            skippedBudget: counts.skippedBudget,
+            skippedFlap: counts.skippedFlap,
+            gated: counts.gated,
+            unobserved: symptom.unobservedCount,
+            adopted: symptom.adoptCount,
+        },
+        log,
+    });
+    // chant#2337 — reported rather than swallowed, the way #2336 does it for the
+    // gate. A push that did not land leaves a correct local record nobody else
+    // can read, and the caller is the only one positioned to say so.
+    const { pushed, pushWarning } = await pushTick();
+    return {
+        id: record.id,
+        drifted: symptom.status === "drifted",
+        remediated: record.summary.remediated,
+        reported: record.summary.reported,
+        skippedBudget: record.summary.skippedBudget,
+        skippedFlap: record.summary.skippedFlap,
+        gated: record.summary.gated ?? 0,
+        unobserved: record.summary.unobserved,
+        adopted: record.summary.adopted,
+        log: record.log,
+        pushed,
+        ...(pushWarning !== undefined ? { pushWarning } : {}),
+    };
+}