@intentius/chant 0.124.12 → 0.124.14

package/dist/op/local-output.js

@@ -0,0 +1,140 @@
+/**
+ * Renderers for local Op execution. Both consume the same `OpRunResult`:
+ * `renderHuman` is the default (logs to stderr), `renderJson` prints the
+ * machine-readable record array to stdout and nothing else.
+ */
+import { approveCommand } from "./gate.js";
+import { LIFECYCLE_LOCAL_NOTE, isLifecycleLocalNote } from "../lifecycle/local-note.js";
+const stderr = (line) => process.stderr.write(line + "\n");
+const stdout = (line) => process.stdout.write(line + "\n");
+function formatArgs(args) {
+    return Object.entries(args)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+        .join(", ");
+}
+function formatDuration(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+/**
+ * Render a run result as human-readable progress. Defaults to stderr so stdout
+ * stays clean for piping (the `--json` renderer owns stdout).
+ */
+export function renderHuman(result, write = stderr, sealed = false) {
+    let currentPhase;
+    for (const record of result.records) {
+        if (record.phase !== currentPhase) {
+            currentPhase = record.phase;
+            write(`[phase] ${currentPhase}`);
+        }
+        const mark = record.status === "ok" ? "✓" : record.status === "fail" ? "✗" : "•";
+        const call = `${record.fn}(${formatArgs(record.args ?? {})})`;
+        if (record.status === "skipped") {
+            write(`  ${mark} ${call}   skipped`);
+        }
+        else {
+            write(`  ${mark} ${call}   ${formatDuration(record.durationMs)}`);
+        }
+        if (record.outcome) {
+            write(`    [outcome] ${record.outcome.name}=${String(record.outcome.value)}`);
+        }
+        if (record.approval) {
+            write(`    [approved] ${record.approval.resolvedBy} at ${record.approval.timestamp}` +
+                (record.approval.url ? ` (${record.approval.url})` : ""));
+        }
+        if (record.refusal) {
+            write(`    [refused] ${record.refusal}`);
+        }
+        if (record.point) {
+            write(`    [waiting] decision point ${record.point.point}: ${record.point.id} is ${record.point.state}`);
+        }
+        if (record.error) {
+            write(`    ${record.error}`);
+        }
+    }
+    // The work lease (#2748): which item the run held, and how it ended.
+    const work = result.workLease;
+    if (work?.item) {
+        const end = work.lost
+            ? `lost (${work.lost})`
+            : work.released
+                ? `released ${work.outcome}`
+                : "not released; it runs out on its own";
+        write(`[work] ${work.item} held by ${work.holder}${work.branch ? ` on ${work.branch}` : ""}: ${end}${work.kept ? `; the attempt is kept at ${work.kept}` : ""}`);
+    }
+    else if (work?.refusal) {
+        write(`[work] nothing claimed: ${work.refusal}`);
+    }
+    const total = `${(result.totalMs / 1000).toFixed(1)}s`;
+    if (result.status === "ok") {
+        write(`Op "${result.op}" completed in ${total}`);
+        return;
+    }
+    if (result.status === "waiting" && result.point) {
+        // An open decision point (#2749): a fact like a gate. A person answers the
+        // question, through hud or at a shell, and the next run reads the answer.
+        const { point } = result;
+        write(`Op "${result.op}" is waiting on decision point "${point.point}" after ${total}`);
+        write(`  question: ${point.id} (${point.state}) at ${point.path}`);
+        if (point.subject)
+            write(`  subject : ${point.subject}`);
+        write(`  answer  : ${pointAnswerCommand(point.id)}`);
+        return;
+    }
+    if (result.status === "fail" || !result.gate) {
+        write(`Op "${result.op}" failed after ${total}`);
+        return;
+    }
+    // Gated (#2119): a standing fact and the one command that clears it. No
+    // hint at another runtime — the run ended here on purpose, and the next one
+    // re-reads the ledger.
+    const { gate } = result;
+    write(`Op "${result.op}" is gated on "${gate.gate}" after ${total}`);
+    if (gate.description)
+        write(`  ${gate.description}`);
+    // #2300: the plan the approval will be bound to. Printed before the
+    // command, because it is what the command approves.
+    if (gate.planDigest)
+        write(`  plan    : ${gate.planDigest}`);
+    write(`  approve : ${approveCommand(gate.op, gate.gate, undefined, gate.planDigest, sealed)}`);
+    if (gate.url)
+        write(`  approve at: ${gate.url}`);
+    write(`  expires : ${gate.expiresAt}`);
+    // #2310: this run's own append reached only the local chant/lifecycle
+    // branch, not the remote. The pending fact is still correct — the gate is
+    // still right to stand — but an operator working from a clone of the
+    // remote cannot see it to approve it, and nothing else here says so.
+    // #3677: with no remote at all, nobody elsewhere approves; one quiet line.
+    if (result.gatePushed === false && isLifecycleLocalNote(result.gatePushWarning)) {
+        write(`  note    : ${LIFECYCLE_LOCAL_NOTE}`);
+    }
+    else if (result.gatePushed === false) {
+        write(`  warning : the pending fact was not pushed to the remote — ` +
+            (result.gatePushWarning ?? "it exists only in this checkout") +
+            `. An operator elsewhere cannot approve it until it does.`);
+    }
+}
+/**
+ * Render the run's ledger record as JSON on stdout (and nothing else on
+ * stdout).
+ *
+ * The record, not the whole `OpRunResult` (#2118): what `chant run <op> --json`
+ * emits is byte-for-byte what the run appended to `<env>/runs__<op>.jsonl`, so
+ * a consumer reading stdout and one reading the ledger back later agree on
+ * every field, the run id included. A gated run's record names the gate it
+ * stopped on; the `approve` command line rides alongside so a CI job reporting
+ * the gate doesn't have to reassemble it from the op and gate names.
+ */
+export function renderJson(result, write = stdout, sealed = false) {
+    const approve = result.gate ? { approve: approveCommand(result.gate.op, result.gate.gate, undefined, result.gate.planDigest, sealed) } : {};
+    // #2310: whether this run's own append reached the remote — not part of
+    // the persisted ledger record (a replay has nothing new to report), but a
+    // live run's JSON consumer needs it exactly where the human render shows it.
+    const push = result.gatePushed === false
+        ? { pushed: false, pushWarning: result.gatePushWarning ?? "the pending fact was recorded locally only" }
+        : {};
+    write(JSON.stringify({ ...result.record, ...approve, ...push }));
+}
+/** The command a person answers an open decision point with (#2749). */
+export function pointAnswerCommand(id) {
+    return `chant workspace points answer ${id} --answer <answer> --by <your name>`;
+}

package/dist/op/op-ir.js

@@ -0,0 +1,317 @@
+/**
+ * op.json IR — chant #1289 ("An Op compiles only to TypeScript, so walk-away
+ * cost is zero everywhere except Ops").
+ *
+ * `OpConfig` is already inert data: every field is a string, number, boolean,
+ * or a nested object of those (no functions, no closures, no runtime
+ * references — see `./types.ts`). This module is the "second, simpler output
+ * from the same walk" the issue asks for: a deterministic
+ * `dist/ops/<name>/op.json`, so a foreign runtime (or a dashboard, a policy
+ * check, an agent) can read what an Op does without importing chant or
+ * parsing generated TypeScript.
+ *
+ * It lives in core, not in a hosting lexicon (#2118, epic #2114). The IR is a
+ * restatement of `OpConfig`, and `OpConfig` is core's — as is the profile
+ * table a step's `profile` key names, since #2117. What core does not own is
+ * the activity contracts that give a step's args a schema: those stay
+ * decentralized, so `buildOpIR` takes the registry as a parameter and defaults
+ * it to empty. A caller holding a lexicon's contracts passes them in, and the
+ * `activityContracts` section fills out without core ever importing that
+ * lexicon.
+ *
+ * Two things beyond a literal restatement of `OpConfig` earn their place:
+ *
+ *  - Every step's `profile` / gate `timeout` is resolved to its effective
+ *    value (chant's own default when omitted), and every referenced profile's
+ *    actual retry/timeout policy rides along out of `ACTIVITY_PROFILES`.
+ *    Without it a foreign runtime would have to read chant's TypeScript to
+ *    know what "fastIdempotent" means.
+ *  - Every step whose `fn` has a registered {@link ActivityContract} in the
+ *    contract registry the caller passes (chant #1288 Stage 1) gets its args/
+ *    returns zod schema embedded as JSON Schema (via zod 4's built-in
+ *    `z.toJSONSchema`), keyed by activity name. This is exactly the payoff
+ *    the Stage 1 decision comment named: "#1289 (op.json IR) ... build on
+ *    these [Stage 1] contracts." Ownership stays decentralized — only
+ *    activities the passed registry knows are covered; a step calling an
+ *    activity from a lexicon outside it (or one with no registered contract
+ *    yet) simply has no entry here.
+ *  - Every step whose contract declares entity-identifying args
+ *    (`ActivityContract.entities`, chant #2022) gets those args' literal
+ *    string values resolved into `entities` — the estate join a renderer
+ *    otherwise had to invent off scope fields like `stackName`. The contract
+ *    entry echoes the declared key list, so a consumer can resolve values
+ *    this serialization could not (a step-output ref) itself.
+ *    JSON-Schema-incompatible contracts (schemas containing transforms or
+ *    custom types that zod cannot serialize) are skipped gracefully: the
+ *    activity appears in the Op's step graph but has no entry in
+ *    activityContracts, consistent with the decentralized and partial
+ *    coverage philosophy.
+ *
+ * Resolving defaults loses nothing: parsing `op.json` back into an
+ * `OpConfig`-shaped object (`opConfigFromIR`) and re-serializing it produces
+ * a byte-identical `op.json`, and a lexicon serializer fed the reconstruction
+ * emits byte-identical code (verified by the round-trip tests here) — the
+ * issue's own verification criterion.
+ *
+ * ## Step-output references (chant #1290, #1288 Stage 2 follow-up)
+ *
+ * A step's `args` may hold a {@link StepOutputRef} (`./step-output-ref.ts`)
+ * anywhere in its structure — a placeholder for a
+ * prior step's declared return value, which the executor substitutes for at
+ * run time from the producing step's record. This module does not
+ * special-case it: `irActivityStep` copies `step.args` through as-is (same as
+ * every other value), and `JSON.stringify` — both the literal one in
+ * `serializeOpIR` and the structural-equality one `z.toJSONSchema`-adjacent
+ * consumers would use — drops a `StepOutputRef`'s brand (a `Symbol.for(...)`
+ * key; JSON has no symbols) while keeping its three own enumerable string
+ * properties. The result is a plain, first-class IR value at exactly the
+ * position the reference sat in `args`:
+ *
+ * ```json
+ * { "kind": "step-output-ref", "step": "build-step", "path": "manifestPath" }
+ * ```
+ *
+ * (`path` omitted when the reference is to the whole return value.) This is
+ * deliberate, not an accident of `JSON.stringify`'s symbol-dropping — a
+ * foreign consumer of op.json can match on `args.<field>.kind ===
+ * "step-output-ref"` to recognize a placeholder and resolve it against
+ * `steps[].id`/`activityContracts[fn].returns` itself, without ever loading
+ * chant's TypeScript. `op-ir.test.ts` asserts the shape directly so a future
+ * change to `StepOutputRef`'s own fields (`./step-output-ref.ts`) that would
+ * silently change this JSON shape gets caught here.
+ */
+import { z } from "zod";
+import { ACTIVITY_PROFILES } from "./activity-profiles.js";
+import { gateName } from "./gate-name.js";
+/**
+ * The op.json IR schema version. Bumped on a breaking change to this
+ * module's output shape — additive fields (a new optional key) do not
+ * require a bump.
+ *
+ * `2.0` (#2118): `taskQueue` and `namespace` are gone and `searchAttributes`
+ * is replaced by `labels`. Those three were the fields only a workflow engine
+ * read; an op.json now states what the Op does, not where it runs.
+ */
+export const OP_IR_FORMAT_VERSION = "2.0";
+// ── Step helpers ──────────────────────────────────────────────────────────────
+function effectiveProfile(step) {
+    return step.profile ?? "fastIdempotent";
+}
+/**
+ * The step's entity-identifying arg values (#2022): the literal strings at
+ * the arg names its contract declares in `entities`. A non-string there (a
+ * step-output ref placeholder, a structured value) is skipped — the IR only
+ * states joins it can resolve at serialization; a consumer holding the
+ * contract's own `entities` key list can resolve the rest itself.
+ */
+function stepEntities(step, contracts) {
+    const declared = contracts.get(step.fn)?.entities;
+    if (!declared || declared.length === 0)
+        return undefined;
+    const values = [];
+    for (const key of declared) {
+        const value = (step.args ?? {})[key];
+        if (typeof value === "string")
+            values.push(value);
+    }
+    return values.length > 0 ? values : undefined;
+}
+function irActivityStep(step, contracts) {
+    const entities = stepEntities(step, contracts);
+    return {
+        kind: "activity",
+        fn: step.fn,
+        args: step.args ?? {},
+        profile: effectiveProfile(step),
+        ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
+        ...(entities ? { entities } : {}),
+        ...(step.outcomeAttribute ? { outcomeAttribute: step.outcomeAttribute } : {}),
+    };
+}
+function irGateStep(step) {
+    return {
+        kind: "gate",
+        gate: gateName(step),
+        timeout: step.timeout ?? "48h",
+        ...(step.description ? { description: step.description } : {}),
+        ...(step.plan !== undefined ? { plan: step.plan } : {}),
+        ...(step.approval !== undefined ? { approval: step.approval } : {}),
+        ...(step.point !== undefined ? { point: step.point } : {}),
+    };
+}
+function irEffectStep(step, contracts) {
+    return {
+        kind: "effect",
+        receipt: step.receipt,
+        ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+        steps: step.steps.map((s) => (s.kind === "activity" ? irActivityStep(s, contracts) : irGateStep(s))),
+        ...(step.description ? { description: step.description } : {}),
+    };
+}
+function irStep(step, contracts) {
+    if (step.kind === "activity")
+        return irActivityStep(step, contracts);
+    if (step.kind === "gate")
+        return irGateStep(step);
+    return irEffectStep(step, contracts);
+}
+function irPhase(phase, contracts) {
+    return {
+        name: phase.name,
+        parallel: phase.parallel ?? false,
+        steps: phase.steps.map((s) => irStep(s, contracts)),
+    };
+}
+// ── Referenced-activity collection ─────────────────────────────────────────────
+/** Every `ActivityStep` reachable from a phase list, including ones nested inside an `EffectStep`. */
+function activityStepsOf(phases) {
+    const out = [];
+    for (const phase of phases) {
+        for (const step of phase.steps) {
+            if (step.kind === "activity")
+                out.push(step);
+            else if (step.kind === "effect") {
+                for (const nested of step.steps)
+                    if (nested.kind === "activity")
+                        out.push(nested);
+            }
+        }
+    }
+    return out;
+}
+/** No contracts unless a caller supplies them — core does not own that registry. See the module doc. */
+const NO_CONTRACTS = new Map();
+/** Sort object keys for a set-like dictionary without a meaningful authored order (profiles/contracts, keyed by name). */
+function sortedEntries(map) {
+    const out = {};
+    for (const key of [...map.keys()].sort())
+        out[key] = map.get(key);
+    return out;
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Build the deterministic op.json IR for one Op's config.
+ *
+ * `contractRegistry` is the one thing core does not own (see the module doc):
+ * a caller holding a lexicon's activity contracts passes them in and
+ * `activityContracts` fills out. Omitted, that section is empty — the step
+ * graph, the labels and every step's resolved `profile` name are unaffected
+ * either way. `profileRegistry` defaults to core's own `ACTIVITY_PROFILES`;
+ * a test overrides it.
+ */
+export function buildOpIR(config, contractRegistry = NO_CONTRACTS, profileRegistry = ACTIVITY_PROFILES) {
+    const allSteps = [...activityStepsOf(config.phases), ...activityStepsOf(config.onFailure ?? [])];
+    const profiles = new Map();
+    const contracts = new Map();
+    for (const step of allSteps) {
+        const prof = effectiveProfile(step);
+        if (!profiles.has(prof) && prof in profileRegistry) {
+            profiles.set(prof, profileRegistry[prof]);
+        }
+        if (!contracts.has(step.fn)) {
+            const contract = contractRegistry.get(step.fn);
+            if (contract) {
+                try {
+                    const args = z.toJSONSchema(contract.args);
+                    const returns = contract.returns ? z.toJSONSchema(contract.returns) : undefined;
+                    contracts.set(step.fn, {
+                        args,
+                        ...(returns ? { returns } : {}),
+                        ...(contract.entities && contract.entities.length > 0 ? { entities: contract.entities } : {}),
+                    });
+                }
+                catch {
+                    // zod 4's toJSONSchema throws on schemas containing transforms or custom types.
+                    // Gracefully skip this contract — the activity remains in the step graph but
+                    // has no entry in activityContracts. Consistent with the decentralized and
+                    // partial coverage philosophy.
+                }
+            }
+        }
+    }
+    return {
+        formatVersion: OP_IR_FORMAT_VERSION,
+        name: config.name,
+        overview: config.overview,
+        depends: config.depends ?? [],
+        labels: config.labels ?? {},
+        ...(config.schedule ? { schedule: config.schedule } : {}),
+        ...(config.workLease ? { workLease: config.workLease } : {}),
+        ...(config.changesCheckout ? { changesCheckout: true } : {}),
+        ...(config.neverOverMcp ? { neverOverMcp: true } : {}),
+        ...(config.failOn ? { failOn: config.failOn } : {}),
+        phases: config.phases.map((p) => irPhase(p, contractRegistry)),
+        onFailure: (config.onFailure ?? []).map((p) => irPhase(p, contractRegistry)),
+        activityProfiles: sortedEntries(profiles),
+        activityContracts: sortedEntries(contracts),
+    };
+}
+/** Serialize one Op's op.json IR to a deterministic JSON string (stable key order, 2-space indent, trailing newline). Takes the same two optional registries as {@link buildOpIR}. */
+export function serializeOpIR(config, contractRegistry, profileRegistry) {
+    return JSON.stringify(buildOpIR(config, contractRegistry, profileRegistry), null, 2) + "\n";
+}
+// ── Round trip (op.json → OpConfig) ────────────────────────────────────────────
+//
+// The inverse of `buildOpIR`. Exists primarily to prove the IR's own
+// verification criterion (chant #1289): parsing `op.json` back into an
+// `OpConfig`-shaped object and re-serializing it round-trips byte-identically,
+// and a lexicon serializer fed the reconstruction emits identical code. Also
+// the mechanical shape a foreign consumer would use to drive its own executor
+// off the IR rather than the generated TypeScript.
+function opStepFromIR(step) {
+    if (step.kind === "activity") {
+        return {
+            kind: "activity",
+            fn: step.fn,
+            args: step.args,
+            profile: step.profile,
+            ...(step.timeout !== undefined ? { timeout: step.timeout } : {}),
+            ...(step.outcomeAttribute ? { outcomeAttribute: step.outcomeAttribute } : {}),
+        };
+    }
+    if (step.kind === "gate") {
+        return {
+            kind: "gate",
+            gate: step.gate,
+            timeout: step.timeout,
+            ...(step.description ? { description: step.description } : {}),
+            ...(step.plan !== undefined ? { plan: step.plan } : {}),
+            ...(step.approval !== undefined ? { approval: step.approval } : {}),
+            ...(step.point !== undefined ? { point: step.point } : {}),
+        };
+    }
+    return {
+        kind: "effect",
+        receipt: step.receipt,
+        ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+        steps: step.steps.map((s) => opStepFromIR(s)),
+        ...(step.description ? { description: step.description } : {}),
+    };
+}
+function opPhaseFromIR(phase) {
+    return {
+        name: phase.name,
+        steps: phase.steps.map(opStepFromIR),
+        ...(phase.parallel ? { parallel: true } : {}),
+    };
+}
+/** Reconstruct an `OpConfig` from its op.json IR. */
+export function opConfigFromIR(ir) {
+    if (ir.formatVersion !== OP_IR_FORMAT_VERSION) {
+        throw new Error(`op.json IR format mismatch: expected "${OP_IR_FORMAT_VERSION}", got "${ir.formatVersion}". ` +
+            `This op.json may be stale or from a newer chant version.`);
+    }
+    return {
+        name: ir.name,
+        overview: ir.overview,
+        phases: ir.phases.map(opPhaseFromIR),
+        ...(ir.depends.length > 0 ? { depends: ir.depends } : {}),
+        ...(ir.onFailure.length > 0 ? { onFailure: ir.onFailure.map(opPhaseFromIR) } : {}),
+        ...(Object.keys(ir.labels).length > 0 ? { labels: ir.labels } : {}),
+        ...(ir.schedule ? { schedule: ir.schedule } : {}),
+        ...(ir.workLease ? { workLease: ir.workLease } : {}),
+        ...(ir.changesCheckout ? { changesCheckout: true } : {}),
+        ...(ir.neverOverMcp ? { neverOverMcp: true } : {}),
+        ...(ir.failOn ? { failOn: ir.failOn } : {}),
+    };
+}

package/dist/op/op-verb-class.js

@@ -0,0 +1,131 @@
+/**
+ * Op verb classification (#1484) — generalizes `delete: "never" | "owned-only"
+ * | "gated"` (`../lifecycle` teardown/apply's `DeleteMode`) up one level, to
+ * the whole Op: read-only, mutating, or destructive. `ConvergeOp`'s
+ * dial × verb-class matrix (the issue's "Autonomy" table) needs to answer
+ * "what kind of thing is this dispatched Op, from the outside" for an
+ * arbitrary declared Op — including one this project's authors wrote, not
+ * just the pre-built composites — so classification walks `OpConfig`'s
+ * steps rather than trusting a self-reported tag.
+ *
+ * There is no existing per-Op verb-class field (`labels` is a free
+ * `Record<string,string>` an author may or may not set — `ApplyOp` tags
+ * `{ Apply: "true" }` but nothing requires it, and it carries no verb-class
+ * semantics on its own) and no existing "which activity names are
+ * destructive" registry (`../lint/pipeline-change-gate.ts`'s classifier is
+ * shaped for a `Component` composition's capability-verb steps, not an
+ * `OpConfig`'s activity steps — a genuinely different graph). This module is
+ * that registry's Op-shaped sibling: a small, explicit set of known
+ * mutating/destructive activity function names, plus the one piece of
+ * structured signal that already exists (`nativeApply`'s `deleteMode` arg).
+ *
+ * Fail-closed by construction: an activity `fn` this module doesn't
+ * recognize is classified `mutating`, never `read-only` — an unknown step
+ * might do anything, and "unknown never remediates" (the issue's own honesty
+ * requirement for symptoms) applies here too: this module never silently
+ * clears an Op to free-run just because its steps aren't in the known-safe
+ * list.
+ */
+/** Activity function names known to be read-only — verification, observation, audit. Anything not in this set is treated as at least `mutating` (fail-closed). */
+const READ_ONLY_ACTIVITY_FNS = new Set([
+    "lifecycleSnapshot",
+    "lifecycleDiff",
+    "composeChangeSet",
+    "lifecyclePlanChangeSet",
+    "readChangeSetPart",
+    "httpCheck",
+    "policyGate",
+    "workflowSupplyChainAudit",
+    "pipelineSupplyChainAudit",
+    "receiptStaleness",
+    "waitForStack",
+    "waitForReady",
+    "waitForArgoSync",
+    "spriteReadFile",
+    "spriteListDir",
+    "listCheckpoints",
+    "convergeTick",
+    "spriteUrl",
+    "spriteServiceGet",
+    "spriteServiceList",
+    "spriteServiceLogs",
+    "spriteServicesObserve",
+]);
+/** Activity function names that always delete/destroy, regardless of args. */
+const ALWAYS_DESTRUCTIVE_ACTIVITY_FNS = new Set([
+    "envTeardown",
+    "chantTeardown",
+    "azDelete",
+    "awsDelete",
+    "gcpDelete",
+    "spriteDestroy",
+    "spriteDelete",
+    "spriteServiceDelete",
+    "k3dDown",
+    "k3sUninstall",
+]);
+function stepsOf(config) {
+    const all = [...config.phases, ...(config.onFailure ?? [])].flatMap((p) => p.steps);
+    const flat = [];
+    for (const step of all) {
+        if (step.kind === "activity")
+            flat.push(step);
+        else if (step.kind === "effect")
+            flat.push(...step.steps.filter((s) => s.kind === "activity"));
+    }
+    return flat;
+}
+/**
+ * Classify an Op's own composition. Pure — reads only the passed config, no
+ * I/O. `nativeApply`'s `deleteMode` (`"never" | "owned-only" | "gated"`) is
+ * read straight off the step's `args` — `"owned-only"`/`"gated"` are
+ * destructive (both can delete a live resource), `"never"`/absent is merely
+ * mutating (creates/updates only). A step whose `fn` matches neither the
+ * read-only nor the destructive set is `mutating` by default (fail-closed).
+ */
+export function classifyOpVerbClass(config) {
+    let sawMutating = false;
+    for (const step of stepsOf(config)) {
+        if (ALWAYS_DESTRUCTIVE_ACTIVITY_FNS.has(step.fn))
+            return "destructive";
+        if (step.fn === "nativeApply") {
+            const deleteMode = step.args?.deleteMode;
+            if (deleteMode === "owned-only" || deleteMode === "gated")
+                return "destructive";
+            sawMutating = true;
+            continue;
+        }
+        if (step.fn === "compensateApply") {
+            // Rollback compensation — mutating (it re-applies a prior state), not
+            // itself a fresh destructive act.
+            sawMutating = true;
+            continue;
+        }
+        if (READ_ONLY_ACTIVITY_FNS.has(step.fn))
+            continue;
+        // Unknown or known-mutating fn: fail-closed to mutating.
+        sawMutating = true;
+    }
+    return sawMutating ? "mutating" : "read-only";
+}
+/**
+ * Does this Op have its own approval gate anywhere in its phases (main or
+ * `onFailure`), including one nested inside an effect step?
+ *
+ * A declaration-time question, not a run-time one: a gate is a fact the
+ * executor decides against the ledger when it reaches one (#2119,
+ * `./gate.ts`), so this says "this op can stop for a human", never "this op
+ * will stop". `OPS014`'s dispatch refusals are the caller that needs it.
+ */
+export function isGated(config) {
+    const isGate = (s) => s.kind === "gate";
+    for (const phase of [...config.phases, ...(config.onFailure ?? [])]) {
+        for (const step of phase.steps) {
+            if (isGate(step))
+                return true;
+            if (step.kind === "effect" && step.steps.some(isGate))
+                return true;
+        }
+    }
+    return false;
+}