@intentius/chant 0.124.12 → 0.124.14

package/dist/op/gate.js

@@ -0,0 +1,449 @@
+/**
+ * Gate-as-fact (#2119, epic #2114) — the one place that decides what happens
+ * when a run reaches a `gate`, shared by the Op executor
+ * (`./local-executor.ts`) and the component driver
+ * (`../components/driver.ts`) so the two can never drift.
+ *
+ * A gate used to be a wait, which meant a runtime that cannot wait had to
+ * refuse the whole op before its first step (`LocalGateUnsupportedError`,
+ * deleted with this). It is a fact now: the run reads the gate ledger
+ * (`../lifecycle/gate-ledger.ts`) for a resolution someone wrote with `chant
+ * approve`, and either walks through carrying the approver, or records a
+ * pending fact and ends. Nothing blocks, nothing is queued, nothing has to be
+ * resumed — the next run re-evaluates from the ledger, which is exactly the
+ * level-triggered shape a converge tick already has.
+ *
+ * The staleness rule is the same one `chant operator status` has applied since
+ * #1485: a resolution counts only if it is newer than the newest pending fact
+ * for that gate. Approving before the gate was ever reached does not
+ * pre-authorize a future run's gate that has since been recorded pending; a
+ * resolution from last month does not answer the fact this run just wrote.
+ *
+ * Since #2300 a gate can also bind a plan. `GateCheckInput.planDigest` is
+ * what this run's Plan phase produced (`../lifecycle/plan-digest.ts`), and a
+ * resolution counts only when it was recorded for that same plan — recency
+ * demoted from the criterion to the tiebreak. Approve, edit the root, re-run,
+ * and the gate refuses by name instead of applying something no approver saw,
+ * which is what INTENTIUS/choudoufu#1026 measured it doing. A gate with no
+ * `planDigest` decides exactly as it did before.
+ *
+ * Ledger access goes through {@link GateLedgerPort} rather than straight to
+ * git, so a test (and the operator's own in-memory paths) can drive the
+ * decision without an orphan branch on disk.
+ */
+import { appendGateResolution, appendPendingGate, isPendingGateExpired, latestPendingGate, latestResolutionForPlan, readGateLedger, resolveApprovalUrl, DEFAULT_GATE_EXPIRY, } from "../lifecycle/gate-ledger.js";
+import { describePlanDigest, samePlanDigest } from "../lifecycle/plan-digest.js";
+import { isModelAuthored } from "../lifecycle/gate-origin.js";
+import { appliedGatePath, isApprovalSpent, parseAppliedGateLines } from "../lifecycle/gate-applied.js";
+import { sortedJsonReplacer } from "../utils.js";
+import { gateContextDigest } from "./gate-approval.js";
+import { pushLifecycleReport, readBlobBySha, readBlobFromPath, readPathSha, requireLifecycleLedger, writeBlobToPath, RefCASConflictError } from "../lifecycle/git.js";
+import { parseDuration } from "./duration.js";
+import { resolveGateRunLocator } from "./gate-run-locator.js";
+/**
+ * The real port: the `chant/lifecycle` orphan branch.
+ *
+ * Appending is always local-first and always lands (#2309's fetch-before-
+ * append). The push that follows is reported rather than swallowed (#2310):
+ * a pending fact that never reaches the remote is still a correct local
+ * answer — the run is right to gate, and does — but an operator elsewhere
+ * cannot approve a gate whose pending record they cannot see, so the caller
+ * gets `pushed: false` and a reason instead of silence. Mirrors the shape
+ * `chant approve` reports through (`../cli/handlers/operator.ts`'s
+ * `reportedPush`, #2309 review).
+ */
+export function gitGateLedgerPort(opts) {
+    return {
+        async read(op) {
+            // The ledger branch has to be in the checkout before it is read
+            // (#2303): a CI clone fetches the pipeline's own ref and nothing else,
+            // and an unfetched branch reads as an empty ledger — which is
+            // indistinguishable from "nothing has been approved" and makes a
+            // retried job record a second pending fact for a gate that was already
+            // approved. Refuses rather than guessing when the fetch cannot settle
+            // it; see `requireLifecycleLedger`.
+            await requireLifecycleLedger(opts);
+            const { resolutions, pending } = await readGateLedger(op, opts);
+            return { resolutions, pending };
+        },
+        async approvalRule(gate, at) {
+            // Loaded on demand: the rule lives in the workspace modules, which import the Op modules.
+            const { gateAdmission } = await import("../workspace/identity.js");
+            return gateAdmission(opts?.cwd ?? process.cwd(), gate, at?.base);
+        },
+        async appendResolution(input) {
+            const { record } = await appendGateResolution(input, opts);
+            return { record, ...(await pushLifecycleReport(opts)) };
+        },
+        async appendPending(input) {
+            const { record } = await appendPendingGate(input, opts);
+            return { record, ...(await pushLifecycleReport(opts)) };
+        },
+        async readApplied(op) {
+            await requireLifecycleLedger(opts);
+            const { dir, file } = appliedGatePath(op);
+            const text = await readBlobFromPath(dir, file, opts);
+            return text ? parseAppliedGateLines(text) : [];
+        },
+        async appendApplied(record) {
+            const { dir, file } = appliedGatePath(record.op);
+            const line = JSON.stringify(record, sortedJsonReplacer);
+            let lastErr;
+            // The same append-and-retry as a ledger line: another writer to the branch is the ordinary case.
+            for (let attempt = 1; attempt <= 5; attempt++) {
+                try {
+                    const prior = await readPathSha(dir, file, opts);
+                    const existing = prior ? await readBlobBySha(prior, opts) : null;
+                    await writeBlobToPath(dir, file, existing ? `${existing.replace(/\n$/, "")}\n${line}\n` : `${line}\n`, `Applied under ${record.gate}`, {
+                        ...opts,
+                        expectPriorPathSha: prior,
+                    });
+                    return pushLifecycleReport(opts);
+                }
+                catch (err) {
+                    if (!(err instanceof RefCASConflictError))
+                        throw err;
+                    lastErr = err;
+                }
+            }
+            throw lastErr;
+        },
+    };
+}
+/** A gate ledger held in memory — what a test, or a caller that has already read the ledger, hands {@link evaluateGate}. */
+export function memoryGateLedgerPort(seed = {}) {
+    const resolutions = [...(seed.resolutions ?? [])];
+    const pending = [...(seed.pending ?? [])];
+    const appended = [];
+    const resolved = [];
+    const applied = [...(seed.applied ?? [])];
+    return {
+        appended,
+        resolved,
+        applied,
+        async readApplied(op) {
+            return applied.filter((a) => a.op === op);
+        },
+        async appendApplied(record) {
+            applied.push(record);
+            return { pushed: true };
+        },
+        async read() {
+            return { resolutions: [...resolutions], pending: [...pending] };
+        },
+        async appendResolution(input) {
+            const record = { version: 1, ...input };
+            resolutions.push(record);
+            resolved.push(record);
+            return { record, pushed: true };
+        },
+        async appendPending(input) {
+            const record = { version: 1, kind: "pending", ...input };
+            pending.push(record);
+            appended.push(record);
+            // No remote in an in-memory ledger — there is nothing to fail to reach.
+            return { record, pushed: true };
+        },
+    };
+}
+/**
+ * The refusal line for a {@link GateDigestMismatch}: which plan was approved,
+ * which was planned, and what closes the gap. One function so the executor's
+ * step record, the human render and the CI summary say the same thing.
+ *
+ * The two cases get different prose because they are different facts. A
+ * resolution for another plan means something changed between the approval
+ * and this run. A resolution with no plan on it means nothing is known to
+ * have changed — the record simply never said what it approved, which is
+ * every record written before #2300.
+ */
+export function describeGateMismatch(op, gate, mismatch, sealed = false) {
+    const why = mismatch.approved === undefined
+        ? mismatch.environment !== undefined
+            ? "That approval predates environment- and plan-bound component gates (#2574) and records neither, " +
+                "so it cannot answer for this one. Approving again binds it:"
+            : "That resolution predates plan-bound gates (#2300) and records no plan at all, so it cannot " +
+                "answer for this one. Approving again binds it:"
+        : "The configuration or the live system changed between that approval and this plan, so it needs " +
+            "a fresh one:";
+    return (`Gate "${gate}" is approved, but not for this plan. ` +
+        `approved: ${describePlanDigest(mismatch.approved)} (by ${mismatch.resolvedBy} at ${mismatch.timestamp}); ` +
+        `planned: ${mismatch.planned}. ` +
+        `${why} ${approveCommand(op, gate, mismatch.environment, undefined, sealed)}`);
+}
+/** How a recorded approval reads: its own `approver`, or for a record written before #2508, a human unless a model-authored channel wrote it. */
+export function approverOf(record) {
+    if (record.approver)
+        return record.approver;
+    return { kind: isModelAuthored(record.origin) ? "agent" : "human" };
+}
+/**
+ * Tally the approvals that answer a gate with an `approval` block (#2508).
+ *
+ * An approval counts only if it is newer than `sinceIso` (the standing pending
+ * fact) and, on a plan-bound gate, recorded for `planDigest`. So a changed
+ * plan invalidates every approval collected for the old one, the rule #2300
+ * set for a single approval. A human's approval may be older than the
+ * standing fact, back to `humansSinceIso` ({@link humanQuorumSince}), so a
+ * pending fact re-recorded for a changed mode or context keeps a partly
+ * filled quorum (#3206). It defaults to `sinceIso`.
+ *
+ * Of those, only a human's counts toward the quorum, once per `resolvedBy`,
+ * and only with one of the quorum's roles when it names any. An agent counts
+ * only through a recorded `allow` in `enforce` mode, evaluated under the
+ * policy version the gate declares now, recorded while the gate was in
+ * `enforce` (#2512), and evaluated under the context the gate resolves now
+ * (#3774). A `log-only` decision never changes the outcome, even
+ * after the gate switches to `enforce`, and a `deny` never removes a human's approval: a policy can add
+ * a way through the gate but cannot take one away.
+ */
+export function tallyGateApprovals(records, gate, sinceIso, planDigest, approval, humansSinceIso = sinceIso) {
+    const since = new Date(sinceIso).getTime();
+    const humansSince = Math.min(since, new Date(humansSinceIso).getTime());
+    const at = (r) => new Date(r.timestamp).getTime();
+    const roles = approval.quorum?.roles;
+    const context = gateContextDigest(approval.context);
+    const byActor = new Map();
+    let permit;
+    let mismatched;
+    for (const r of records) {
+        if (r.gate !== gate || at(r) < humansSince)
+            continue;
+        if (planDigest !== undefined && !samePlanDigest(r.planDigest, planDigest)) {
+            if (at(r) >= since && (!mismatched || at(r) >= at(mismatched)))
+                mismatched = r;
+            continue;
+        }
+        const decision = r.policyDecision;
+        // #3206: an approval from before the standing fact can only be a human's
+        // toward the quorum. A permit is anchored on the standing fact, the one
+        // `chant approve` evaluated it under.
+        const sinceStanding = at(r) >= since;
+        // #2512: the decision must also have been recorded under `enforce`. An
+        // allow recorded while the gate was log-only was never binding, and a
+        // later switch to enforce does not make it binding. #3774: and under
+        // the context this run resolved, since the run checks approvals before it
+        // re-records the pending fact for a changed context.
+        if (sinceStanding && approval.mode === "enforce" && approval.policy && decision?.decision === "allow" &&
+            decision.mode === "enforce" && decision.version === approval.policy.version &&
+            decision.contextDigest === context && (!permit || at(r) >= at(permit))) {
+            permit = r;
+        }
+        const approver = approverOf(r);
+        if (approver.kind !== "human")
+            continue;
+        if (roles && !(approver.roles ?? []).some((role) => roles.includes(role)))
+            continue;
+        const prior = byActor.get(r.resolvedBy);
+        if (!prior || at(r) >= at(prior))
+            byActor.set(r.resolvedBy, r);
+    }
+    const counted = [...byActor.values()].sort((a, b) => at(a) - at(b));
+    return {
+        counted,
+        need: approval.quorum?.count ?? 1,
+        ...(permit ? { permit } : {}),
+        ...(mismatched ? { mismatched } : {}),
+    };
+}
+/**
+ * Where a gate's human quorum starts counting (#3206): the oldest pending fact
+ * in the unbroken run of facts, newest first from `standing`, recorded for
+ * `standing`'s plan and policy version.
+ *
+ * A pending fact is re-recorded when anything in the approval block changes,
+ * the mode and the context included, so `chant approve` evaluates the policy
+ * under what the gate now declares. A human's approval counts for the plan
+ * it names whatever the mode or context was, so re-recording for one of
+ * those must not drop it. The run stops at a fact for another plan or policy
+ * version, which needs fresh approvals, and at one that had expired by the
+ * time the next was recorded, which expiry already closed.
+ *
+ * `pending` may hold every pending fact in the ledger; only `standing`'s gate
+ * and environment are read.
+ */
+export function humanQuorumSince(pending, standing) {
+    const at = (p) => new Date(p.timestamp).getTime();
+    const version = (p) => p.approval?.policy?.version;
+    const sameKey = (p) => samePlanDigest(p.planDigest, standing.planDigest) && version(p) === version(standing);
+    const older = pending
+        .filter((p) => p !== standing && p.gate === standing.gate && p.environment === standing.environment && at(p) <= at(standing))
+        .sort((a, b) => at(b) - at(a));
+    let anchor = standing;
+    for (const p of older) {
+        if (!sameKey(p) || isPendingGateExpired(p, anchor.timestamp))
+            break;
+        anchor = p;
+    }
+    return anchor.timestamp;
+}
+/** Whether two resolved approval blocks are the same, so a standing pending fact still describes this gate. */
+function sameApproval(a, b) {
+    return JSON.stringify(a ?? null, sortedJsonReplacer) === JSON.stringify(b ?? null, sortedJsonReplacer);
+}
+/** The beginning of time — the anchor for a gate that has never been recorded pending, so any resolution for it counts. */
+const EPOCH = new Date(0).toISOString();
+/**
+ * Decide a gate against the ledger, recording the pending fact when it isn't
+ * answered.
+ *
+ * - A resolution recorded for this run's own plan, newer than the newest
+ *   pending fact, satisfies the gate. On a gate that binds no plan
+ *   (`input.planDigest` absent) the plan half of that drops out and the rule
+ *   is the pre-#2300 one: any resolution newer than the pending fact.
+ * - A resolution that stands for the gate but for a different plan does not
+ *   satisfy it (#2300). The run is gated, `mismatch` names both plans, and a
+ *   fresh pending fact is recorded for the plan that actually ran — so
+ *   `chant approve` has something current to approve and the loop closes in
+ *   one more command rather than needing the digest typed out.
+ * - Otherwise, a pending fact that hasn't expired *and was recorded for this
+ *   same plan* stands as it is: the run ends `gated` and the ledger is left
+ *   alone, so an operator ticking every minute against an unapproved gate
+ *   does not append a line a minute. A pending fact for a different plan is
+ *   stale in the way that matters and is replaced.
+ * - Otherwise (no pending fact, or the newest one has expired, or it is for
+ *   another plan) a fresh pending fact is appended and the run ends `gated`.
+ *   `recorded` says which of the two happened, so a renderer can tell "just
+ *   recorded" from "still standing".
+ */
+export async function evaluateGate(port, input) {
+    const now = input.now ?? new Date().toISOString();
+    const ledger = await port.read(input.op);
+    // #2574: a component's ledger holds every environment's facts. This run
+    // answers only to its own environment's pending facts and approvals. An
+    // approval that records no environment at all is kept, so it comes back as
+    // a mismatch with a message instead of silently not counting.
+    const env = input.environment;
+    const pending = env === undefined ? ledger.pending : ledger.pending.filter((p) => p.environment === env);
+    // #3163: a gate the workspace's identity.gates names counts only signed approvals from its class.
+    const rule = (await port.approvalRule?.(input.gate)) ?? null;
+    const standing = latestPendingGate(pending, input.gate);
+    const since = standing?.timestamp ?? EPOCH;
+    // #3841: an approval of this plan the rule refuses is named, so a wait says why.
+    const refused = [];
+    const resolutions = (env === undefined
+        ? ledger.resolutions
+        : ledger.resolutions.filter((r) => r.environment === undefined || r.environment === env))
+        .filter((r) => input.spent === undefined || r.gate !== input.gate || !isApprovalSpent(input.spent, r))
+        .filter((r) => {
+        if (rule === null || r.gate !== input.gate)
+            return true;
+        const reason = rule.refuses(r);
+        if (reason === null)
+            return true;
+        if (samePlanDigest(r.planDigest, input.planDigest) && new Date(r.timestamp).getTime() >= new Date(since).getTime())
+            refused.push({ resolution: r, reason });
+        return false;
+    });
+    refused.sort((a, b) => new Date(a.resolution.timestamp).getTime() - new Date(b.resolution.timestamp).getTime());
+    let mismatched;
+    let quorum;
+    if (input.approval) {
+        // #3206: the humans' anchor reaches back past facts re-recorded for this
+        // plan and policy version, so a mode or context change keeps the quorum.
+        const humansSince = standing && samePlanDigest(standing.planDigest, input.planDigest) &&
+            standing.approval?.policy?.version === input.approval.policy?.version
+            ? humanQuorumSince(pending, standing)
+            : since;
+        const tally = tallyGateApprovals(resolutions, input.gate, since, input.planDigest, input.approval, humansSince);
+        if (tally.permit) {
+            return { satisfied: true, resolution: tally.permit, via: "policy", approvals: tally.counted };
+        }
+        if (tally.counted.length >= tally.need) {
+            return {
+                satisfied: true,
+                resolution: tally.counted[tally.counted.length - 1],
+                via: "quorum",
+                approvals: tally.counted,
+            };
+        }
+        mismatched = tally.mismatched;
+        quorum = { approvers: tally.counted.map((r) => r.resolvedBy), need: tally.need };
+    }
+    else {
+        const found = latestResolutionForPlan(resolutions, input.gate, since, input.planDigest);
+        if (found.resolution)
+            return { satisfied: true, resolution: found.resolution };
+        mismatched = found.mismatched;
+    }
+    // `input.planDigest` is defined whenever `mismatched` is — `latestResolutionForPlan`
+    // returns a mismatch only on the plan-bound path.
+    const mismatch = mismatched
+        ? {
+            ...(mismatched.planDigest !== undefined ? { approved: mismatched.planDigest } : {}),
+            planned: input.planDigest,
+            resolvedBy: mismatched.resolvedBy,
+            timestamp: mismatched.timestamp,
+            ...(env !== undefined ? { environment: env } : {}),
+        }
+        : undefined;
+    const asMismatch = { ...(mismatch ? { mismatch } : {}), ...(quorum ? { quorum } : {}), ...(refused.length > 0 ? { refused } : {}) };
+    // A standing fact only stands for the plan it was recorded against. When
+    // the plan has moved, re-recording is what gives `chant approve` (which
+    // defaults to the newest pending fact's digest) the current plan to
+    // approve; leaving the old fact standing would make the common path
+    // approve a plan that is no longer the one being run.
+    // The same holds for the approval block (#2508): a pending fact recorded
+    // under another policy version or another context would have `chant
+    // approve` evaluate the policy against something this run no longer has.
+    if (standing && !isPendingGateExpired(standing, now) && samePlanDigest(standing.planDigest, input.planDigest) &&
+        sameApproval(standing.approval, input.approval)) {
+        return { satisfied: false, pending: standing, recorded: false, ...asMismatch };
+    }
+    const url = resolveApprovalUrl();
+    // #3683: in CI, where this job runs, so an approval can start it again.
+    const resume = resolveGateRunLocator();
+    const { record, pushed, pushWarning } = await port.appendPending({
+        ...input.fields,
+        op: input.op,
+        gate: input.gate,
+        timestamp: now,
+        expiresAt: new Date(new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY)).toISOString(),
+        ...(input.description ? { description: input.description } : {}),
+        ...(input.runId ? { runId: input.runId } : {}),
+        ...(url ? { url } : {}),
+        ...(resume ? { resume } : {}),
+        ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
+        ...(env !== undefined ? { environment: env } : {}),
+        ...(input.approval ? { approval: input.approval } : {}),
+        ...(input.neverOverMcp ? { neverOverMcp: true } : {}),
+    });
+    return {
+        satisfied: false,
+        pending: record,
+        recorded: true,
+        pushed,
+        ...(pushWarning ? { pushWarning } : {}),
+        ...asMismatch,
+    };
+}
+/**
+ * The line every renderer prints to say how a pending gate is cleared. A
+ * component gate names its environment (#2574), so the approval picks that
+ * environment's pending fact when others stand beside it. A gate bound to a
+ * plan (#2300) gets `--plan <digest>` too (#2832), so the line approves the
+ * plan the reader was shown and not whatever is pending by the time they run
+ * it.
+ */
+export function approveCommand(op, gate, environment, planDigest, sealed = false) {
+    return `chant approve ${op} ${gate}` +
+        (environment === undefined ? "" : ` --env ${environment}`) +
+        (planDigest === undefined ? "" : ` --plan ${planDigest}`) +
+        (sealed ? " --sign" : "");
+}
+/**
+ * Whether the workspace seals `gate` (`identity.gates`), so an approval
+ * without `--sign` doesn't count. Callers pass the answer to
+ * {@link approveCommand} so the hint names the flag. Loaded on demand, as the
+ * git ledger port does: the workspace modules import the Op modules. A read
+ * that throws counts as unsealed, since the hint is advice and not the check.
+ */
+export async function gateIsSealed(gate, cwd = process.cwd()) {
+    try {
+        const { gateAdmission } = await import("../workspace/identity.js");
+        return gateAdmission(cwd, gate) !== null;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/op/generate-pipeline.js

@@ -0,0 +1,124 @@
+/**
+ * Generate mode's Op counterpart (#927): synthesize scheduled CI for
+ * stateless Ops — the cron-triggered sibling of `generateComponentsPipeline`
+ * (../components/cli-support.ts, #563/#688). A component pipeline triggers a
+ * deploy-time graph on `workflow_dispatch`; this triggers already-built Ops
+ * on a cron, each via `chant run <name>` on the local executor — the same
+ * one-shot invocation documented at docs/src/content/docs/guide/ops.mdx. Core
+ * owns only Op discovery, so a typo'd name fails fast before any CI is
+ * generated; the CI-specific synthesis is contributed by the target
+ * lexicon's `generateOpPipeline` (../lexicon.ts), exactly like
+ * `generateComponentPipeline`.
+ *
+ * There is no dependency graph between scheduled Ops the way there is
+ * between components — `Op.depends` orders phases within one run, not
+ * separately scheduled cron triggers — so this does not call
+ * `resolveComponentGraph`; each `ScheduledOpSpec` is generated independently.
+ */
+import { discoverOps } from "./discover.js";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module.js";
+import { isLexiconPlugin, } from "../lexicon.js";
+import { assertOpWavesSpec } from "./op-waves.js";
+/**
+ * Load a lexicon's plugin (`@intentius/chant-lexicon-<name>`) to reach its
+ * `generateOpPipeline`. Tolerant: returns null when the package can't be
+ * resolved. Kept local (rather than imported from
+ * `../components/cli-support.ts`) so this module carries no dependency on
+ * `components/`.
+ */
+async function loadLexiconPlugin(name) {
+    let mod;
+    try {
+        mod = (await importLexiconPackage(lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`));
+    }
+    catch {
+        return null;
+    }
+    for (const value of Object.values(mod)) {
+        if (isLexiconPlugin(value))
+            return value;
+    }
+    return null;
+}
+/**
+ * Copy each discovered Op's own `schedule` (#2120) onto its spec, so a CI
+ * generator can render the cron the Op already declares — `WatchOp({ name,
+ * schedule })` then needs no second cron in the `generateOpsPipeline` call.
+ * The spec's own `trigger`/`schedule` still win; `resolveOpTrigger` reads
+ * `opSchedule` last. Specs for Ops with no cadence pass through untouched.
+ */
+export function withOpSchedules(specs, discovered) {
+    return specs.map((spec) => {
+        const schedule = discovered.get(spec.name)?.config.schedule;
+        return schedule ? { ...spec, opSchedule: schedule } : spec;
+    });
+}
+/**
+ * Synthesize scheduled CI for `ops` targeting `lexicon`: validate every named
+ * Op exists (`discoverOps`, under the git root — mirrors `chant run <name>`'s
+ * own resolution), then dispatch to the lexicon's `generateOpPipeline`. No
+ * deploy/audit logic is inlined into the generated YAML — the finding-mode
+ * behavior lives in the Op's own activity args, set by the composite that
+ * built it (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, …); this
+ * function only wires the cron trigger and the token/permission surface the
+ * declared `findingMode` needs.
+ */
+export async function generateOpsPipeline(ops, lexicon, options, cwd) {
+    const plugin = await loadLexiconPlugin(lexicon);
+    if (!plugin?.generateOpPipeline) {
+        return {
+            success: false,
+            error: `Lexicon "${lexicon}" does not support Op generate mode (no generateOpPipeline). GitLab, GitHub, and Forgejo are supported today.`,
+        };
+    }
+    const discovered = await discoverOps({ cwd });
+    if (discovered.errors.length > 0) {
+        return { success: false, error: discovered.errors.join("\n") };
+    }
+    const unknown = ops.filter((spec) => !discovered.ops.has(spec.name));
+    if (unknown.length > 0) {
+        const known = [...discovered.ops.keys()].sort().join(", ");
+        return {
+            success: false,
+            error: `Unknown Op(s): ${unknown.map((s) => s.name).join(", ")}.${known ? ` Known Ops: ${known}` : " No Ops discovered."}`,
+        };
+    }
+    const { files, jobs } = plugin.generateOpPipeline(withOpSchedules(ops, discovered.ops), options);
+    return { success: true, files, jobs };
+}
+/**
+ * Render ordered waves of Op runs for `lexicon` (#3679, `./op-waves.ts`):
+ * check the spec, check that every Op it names exists, then hand it to the
+ * lexicon's `generateOpWavesPipeline`.
+ */
+export async function generateOpWavesPipeline(spec, lexicon, options, cwd) {
+    const plugin = await loadLexiconPlugin(lexicon);
+    if (!plugin?.generateOpWavesPipeline) {
+        return {
+            success: false,
+            error: `Lexicon "${lexicon}" does not render Op waves (no generateOpWavesPipeline). GitLab, GitHub, and Forgejo do.`,
+        };
+    }
+    try {
+        assertOpWavesSpec(spec);
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    const discovered = await discoverOps({ cwd });
+    if (discovered.errors.length > 0)
+        return { success: false, error: discovered.errors.join("\n") };
+    const named = [...new Set([spec.op, ...spec.waves.flatMap((w) => w.runs.map((r) => r.op ?? spec.op))])];
+    const unknown = named.filter((name) => !discovered.ops.has(name));
+    if (unknown.length > 0) {
+        const known = [...discovered.ops.keys()].sort().join(", ");
+        return { success: false, error: `Unknown Op(s): ${unknown.join(", ")}.${known ? ` Known Ops: ${known}` : " No Ops discovered."}` };
+    }
+    try {
+        const { files, jobs } = plugin.generateOpWavesPipeline(spec, options);
+        return { success: true, files, jobs };
+    }
+    catch (err) {
+        return { success: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/op/index.js

@@ -0,0 +1,51 @@
+export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady, gitlabPipeline, lifecycleSnapshot, shell, sourceArchive, releasePlan, releaseRecord, composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart, releaseRollbackPlan, releaseRollbackRecord, decide, ensureSecret, teardown, envTeardown, k3dUp, k3dDown, k3sInstall, k3sUninstall, flociUp, flociDown, flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck, azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate, guardValidate, workEvidence, spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy, spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove, spriteApplyNetworkPolicy, spriteApplyServices, spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease, spritesUp, spritesDown } from "./builders.js";
+export { OpResource } from "./resource.js";
+export { sleep } from "./activity-runtime.js";
+export { clientHosts, emulatorLifecycle, emulatorsOf, endpointEnvVars, endpointOnHost, hostPortInUse, parsePublishedAddresses, pickReachableEndpoint } from "./emulator-lifecycle.js";
+export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness.js";
+export { outcomeAttributesOf, WORK_LEASE_STEP_ID, DRIFT_EXIT_CODE } from "./types.js";
+export { RunWorkLease, workLeaseOutput, stewardWorkHolder, workLeaseProblems, workLeaseNeedsRunItem, LEASE_LOST, WORK_BRANCH_PREFIX, } from "./work-lease-run.js";
+export { isValidCronExpression, cronSyntaxMessage, cronMatches, cronDueBetween } from "./cron.js";
+export { WatchOp, ReconcileOp, ApplyOp, ConvergeOp, WorkflowAuditOp, PipelineAuditOp, LexiconUpgradeOp, IN_SCOPE_LEXICONS, BehaviourOp, } from "./composites/index.js";
+export { parseResourceObservation, CONVERGE_RESOURCE_ENV } from "../lifecycle/symptoms.js";
+export { receiptActivities, receiptCheckInput } from "./receipt-store.js";
+export { discoverOps } from "./discover.js";
+export { generateOpsPipeline, generateOpWavesPipeline, withOpSchedules } from "./generate-pipeline.js";
+export { OP_WAVE_APPLY_HOOKS_RUNNERS, OP_WAVE_DEFAULT_APPLY, OP_WAVE_DEFAULT_GATE_NAME, OP_WAVE_GATE_POLICIES, OP_WAVE_HOOK_MOMENTS, assertOpWaveHooks, assertOpWavesSpec, opWaveApplyHooksRunBy, opWaveGateName, opWaveHooksAt, opWaveJobs, opWaveRecordPath, opWaveShare, } from "./op-waves.js";
+export { OP_WAVE_APPLY_OUTCOMES, OP_WAVE_MAX_REPLANS, opWaveHooksAtBase, opWaveNeedsApproval, opWavePlansPath, opWaveRunsPath, opWaveSetDigest, parseOpWavesSpec, recordOpWaveHeadPlans, readOpWaveHooksFile, readOpWavePolicy, runOpWave, runOpWaveApplyHooks, } from "./op-waves-run.js";
+export { notifyOpWave, opWaveNotifyFields } from "./op-waves-notify.js";
+export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry.js";
+export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry.js";
+export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES, MAX_STEP_TIMEOUT } from "./activity-profiles.js";
+export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure.js";
+export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor.js";
+export { currentOpRun, withOpRunContext } from "./run-context.js";
+export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand, describeGateMismatch, gateIsSealed } from "./gate.js";
+export { tallyGateApprovals, humanQuorumSince, approverOf } from "./gate.js";
+export { planGateResumes, standingGateFacts } from "./gate-resume-plan.js";
+export { gateApprovalProblems, gateContextDigest, gatePolicyRequest, gatePolicyVersion, isGatePolicyRef, loadGatePolicyEvaluator, GATE_APPROVAL_MODES, } from "./gate-approval.js";
+export { gatePlanSummary, gatePlanSummaryOfResult, changeSetOfResult, GATE_PLAN_CONTEXT_KEY, GATE_PLAN_ADDRESS_LIMIT, } from "./gate-plan-context.js";
+export { computePlanDigest, isPlanDigest, describePlanDigest, samePlanDigest, PLAN_DIGEST_ALGORITHM, PLAN_DIGEST_PREFIX, } from "../lifecycle/plan-digest.js";
+export { gateName, usesDeprecatedGateKey, DEPRECATED_GATE_KEY_WARNING } from "./gate-name.js";
+export { gatePointOf, gatePointProblems, gatePointInputs, gateSubject, GATE_POINT_INPUTS, DEFAULT_GATE_POINT_PASS } from "./gate-point.js";
+export { evaluatePointGate, workspaceGatePointAsker } from "./gate-point-run.js";
+export { createLocalOpRuntime } from "./runtimes/local.js";
+export { runStateOf } from "./runtime.js";
+export { buildOpIR, serializeOpIR, opConfigFromIR, OP_IR_FORMAT_VERSION } from "./op-ir.js";
+export { renderHuman, renderJson } from "./local-output.js";
+export { activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES, pathExistsInSchema, } from "./activity-contract.js";
+export { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope, makeOutProxy } from "./step-output-ref.js";
+export { eq, neq, gt, gte, lt, lte, truthy, falsy, allOf, anyOf, evaluatePredicate, isWellFormedPredicate, predicateReferencesField, run, report, when, duplicateRuleIds, DEFAULT_FLAP_THRESHOLD, } from "./converge-rule.js";
+export { discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine, formatSignalLine, DEFAULT_OPERATOR_INTERVAL_MS, acquireStewardLease, acquireStewardTurn, STEWARD_TURN_WAIT_MS, createBesideState, waitForBesideRuns, stopBesideRuns, } from "./operator.js";
+export { spawnBesideRun, inProcessBesideLauncher, holdBesideLease, askReady, DEFAULT_READY_TIMEOUT_MS, } from "./steward-beside.js";
+export { declareSteward, isStewardDeclaration, stewardFormFor, stewardOpConfig, normaliseStewardForm, stewardLeaseName, stewardTurnLeaseName, stewardBesideOf, stewardBesideFor, stewardTurnOps, readinessKeys, STEWARD_KIND, STEWARD_FORMS, STEWARD_NAME_PATTERN, DEFAULT_STEWARD_ENV, } from "./steward.js";
+export { discoverStewards } from "./discover.js";
+export { askPointInRun, brokeredModelAsk, isPointWait, PointWait, DEFAULT_INFERENCE_CAPABILITY, } from "./steward-points.js";
+export { GateWait, isGateWait } from "./gate-wait.js";
+export { currentStewardTurn, enterStewardTurn, setStewardTurn, resetStewardTurn, STEWARD_ENV, } from "./steward-turn.js";
+export { reportRunActivity, readInFlightRun, RUN_ACTIVITY_ENV, RUN_ID_ENV } from "./run-live.js";
+export { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS } from "./change-signal.js";
+export { classifyOpVerbClass, isGated } from "./op-verb-class.js";
+export { takeProfileAndId } from "./builders.js";
+// The factory reference Op (#3406, ws-087).
+export { factoryOp, factoryOpConfig, factoryReady } from "./factory.js";