@intentius/chant 0.124.13 → 0.124.14

package/dist/op/change-signal.js

@@ -0,0 +1,118 @@
+/**
+ * The wake gate between a substrate's change signal and `chant operator`'s
+ * sleep (#1981, epic #1487).
+ *
+ * A lexicon that implements `subscribeChanges` (`../lexicon.ts`) can say
+ * "something moved". This module is everything the loop does with that: it
+ * shortens the current sleep, at most once per floor. It is deliberately the
+ * only place a signal touches, so the rule that a signal is a trigger and
+ * never a fact is a property of the code rather than a convention. Nothing
+ * here has a parameter, a return value or a field that could carry what
+ * changed.
+ *
+ * ## Backpressure: the floor
+ *
+ * A watch on a busy namespace is not a trickle. A rollout, a Job sweep or a
+ * controller resyncing its whole world produces hundreds of events in a
+ * second, and each one is a truthful "something moved". Waking a tick per
+ * event would turn a convergence loop into a load generator pointed at the
+ * cluster it is meant to be watching.
+ *
+ * So the gate coalesces. Signals are collapsed into a single pending flag, and
+ * a pending flag wakes the sleep no earlier than {@link
+ * ChangeSignalGateOptions.floorMs} after the last round *started*. A storm of
+ * a thousand signals inside one floor window costs exactly one early wake, and
+ * a substrate that never stops sending settles into ticking on the floor
+ * rather than on the interval, which is the fastest the loop is ever allowed
+ * to run.
+ *
+ * The floor is measured from the start of the last round, not from the last
+ * signal, so a steady stream can never push the wake further out (that would
+ * be a debounce, and a debounce starves: the busier the cluster, the later the
+ * tick). Measuring from the round start makes the guarantee a rate limit,
+ * never more than one signal-driven tick per floor, which is the property the
+ * loop actually needs.
+ */
+/**
+ * The shortest gap between two rounds a change signal may produce. Signals
+ * arriving inside this window of the last round's start are coalesced into one
+ * wake at the end of it.
+ *
+ * Five seconds: long enough that a rollout's event storm costs one tick rather
+ * than dozens, short enough that "wakes within a second or so of a change"
+ * holds for the quiet case a signal exists for. The timer
+ * (`DEFAULT_OPERATOR_INTERVAL_MS`, 60s) is unchanged and remains the ceiling.
+ */
+export const DEFAULT_SIGNAL_FLOOR_MS = 5000;
+export function createChangeSignalGate(options = {}) {
+    const floorMs = options.floorMs ?? DEFAULT_SIGNAL_FLOOR_MS;
+    const now = options.now ?? (() => Date.now());
+    let pending = false;
+    let lastRoundAt = now();
+    let signalCount = 0;
+    let wakeCount = 0;
+    /** Set only while a `wait` is in flight. */
+    let arm;
+    return {
+        get signalCount() {
+            return signalCount;
+        },
+        get wakeCount() {
+            return wakeCount;
+        },
+        signal() {
+            signalCount++;
+            pending = true;
+            arm?.();
+        },
+        roundStarted() {
+            lastRoundAt = now();
+            pending = false;
+        },
+        wait(intervalMs, abortSignal) {
+            return new Promise((resolve) => {
+                if (abortSignal?.aborted)
+                    return resolve("aborted");
+                let settled = false;
+                let floorTimer;
+                const finish = (reason) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(intervalTimer);
+                    if (floorTimer)
+                        clearTimeout(floorTimer);
+                    abortSignal?.removeEventListener("abort", onAbort);
+                    arm = undefined;
+                    if (reason === "signal")
+                        wakeCount++;
+                    resolve(reason);
+                };
+                const intervalTimer = setTimeout(() => finish("timer"), intervalMs);
+                const onAbort = () => finish("aborted");
+                abortSignal?.addEventListener("abort", onAbort, { once: true });
+                // A pending signal wakes the sleep the moment the floor has passed,
+                // and not one moment earlier. `remaining` is measured from the last
+                // round's start, so repeated signals inside the window collapse onto
+                // the same deadline instead of pushing it out.
+                const consider = () => {
+                    if (settled || !pending)
+                        return;
+                    const remaining = lastRoundAt + floorMs - now();
+                    if (remaining <= 0)
+                        return finish("signal");
+                    if (floorTimer)
+                        return; // already waiting out this window
+                    floorTimer = setTimeout(() => {
+                        floorTimer = undefined;
+                        consider();
+                    }, remaining);
+                };
+                arm = consider;
+                // A signal that arrived between rounds, while nothing was sleeping,
+                // is honoured here rather than lost.
+                consider();
+            });
+        },
+    };
+}

package/dist/op/composites/apply-op.js

@@ -0,0 +1,151 @@
+/**
+ * ApplyOp composite — the code → cloud workflow as an Op.
+ *
+ * Compute the plan, then apply via the target's native mechanism. Authority
+ * stays with the platform (the CloudFormation stack, the Kubernetes API
+ * server, the ARM resource group) — chant never hosts a state file.
+ *
+ * Phases: build → plan → [approve] → apply. Deletes ride the native
+ * prune path, whose bound is per target: the ownership marker on `kubectl`,
+ * the ownership tag on `arm` (chant #1448 — previously `--mode Complete`, which
+ * removed resources chant never applied), the ownership label on `gcp`
+ * (chant #1449), the metadata marker (machines) and managed app
+ * (volumes/ips/certs/secrets) on `fly` (chant #1449), the ownership labels on
+ * `grafana` (chant #3011), the comment marker on `clickhouse` (chant #3208)
+ * and `postgres` (chant #3280), the declared ruler namespaces on `ruler`
+ * (chant #3372),
+ * and the stack itself on `cloudformation`, which a
+ * resource CFN did not create is not in. All of
+ * them are owned-only. See {@link DeleteMode}.
+ *
+ * A gate is a fact, not a wait (#2119): the local executor reads the gate
+ * ledger, and a run that finds no resolution ends `gated` with the `chant
+ * approve <op> <gate>` line to run. Approve, run again, and the same Op
+ * converges — no durable workflow engine is involved.
+ *
+ * The gate binds the plan (#2300). The Plan phase's `lifecycleDiff` publishes
+ * a digest of its change set, the gate step references it, and a resolution
+ * counts only for that digest. Approve, change the declared source, re-run,
+ * and the run stops again with both digests named rather than applying a
+ * change set the approver never saw.
+ *
+ * @example
+ * ```typescript
+ * // additive, local executor
+ * export const { op } = ApplyOp({ name: "prod-apply", env: "prod", target: "kubectl" });
+ *
+ * // gated destructive apply — `chant approve prod-apply approve-apply`, then re-run
+ * export const { op } = ApplyOp({
+ *   name: "prod-apply",
+ *   env: "prod",
+ *   target: "kubectl",
+ *   delete: "gated",
+ *   gate: { gate: "approve-apply", description: "Approve prod apply with deletes" },
+ * });
+ *
+ * // the gate asks the prod-apply decision point (#3170): answered with
+ * // `chant workspace points answer <id>`, then re-run
+ * export const { op } = ApplyOp({
+ *   name: "prod-apply",
+ *   env: "prod",
+ *   target: "kubectl",
+ *   gate: { gate: "approve-apply", point: "prod-apply" },
+ * });
+ * ```
+ *
+ * @see #112 — stateless-authoritative state model + live import
+ */
+import { Op, phase, activity, gate } from "../builders.js";
+import { stepOutput } from "../step-output-ref.js";
+import { gateName } from "../gate-name.js";
+import { defaultOutput, hasNativeRollback } from "../activities/apply.js";
+export function ApplyOp(config) {
+    const target = config.target ?? "kubectl";
+    const output = config.output ?? defaultOutput(target);
+    const deleteMode = config.delete ?? "never";
+    const gated = deleteMode === "gated" || config.effects === "gated" || config.gate !== undefined;
+    const phases = [
+        phase("Build", [activity("chantBuild", { path: config.path ?? "." })]),
+        phase("Plan", [
+            {
+                kind: "activity",
+                // #2300: the gate below references this step's digest, and a
+                // reference needs an id. `plan` rather than `diff`, because what the
+                // Approve phase binds to is the plan this step produced.
+                id: "plan",
+                fn: "lifecycleDiff",
+                args: { env: config.env, live: true },
+                outcomeAttribute: { name: "Drift", from: "drifted" },
+            },
+        ]),
+    ];
+    if (gated) {
+        phases.push(phase("Approve", [
+            gate(gateName(config.gate ?? {}) || `approve-${config.name}`, {
+                ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
+                // #2300: the approval is for the change set the Plan phase just
+                // produced. Edit the source between approving and re-running and
+                // the gate refuses, naming the approved digest and the planned one,
+                // instead of applying what nobody read.
+                plan: stepOutput("plan", "planDigest"),
+                ...(config.gate?.point !== undefined ? { point: config.gate.point } : {}),
+                description: config.gate?.description ??
+                    `Approve apply to ${config.env} (delete mode: ${deleteMode}` +
+                        `${config.effects === "gated" ? ", effects: gated" : ""})`,
+            }),
+        ]));
+    }
+    phases.push(phase("Apply", [
+        activity("nativeApply", {
+            target,
+            env: config.env,
+            output,
+            deleteMode,
+            // Only present when the author asked for it, so an Op that does not
+            // mention conflicts serializes exactly as it always has.
+            ...(config.forceConflicts !== undefined ? { forceConflicts: config.forceConflicts } : {}),
+        }, "longInfra"),
+    ]));
+    // Compensation is total or refused (#1449). A rollback path is either the
+    // target's mapped native rollback (cloudformation's rollbackStack) or an
+    // explicit command; without one there is nothing a Rollback phase could run,
+    // so asking for one is refused here — at build time, with the op named —
+    // rather than surfacing as a warn when the rollback is already needed.
+    const compensateCommand = typeof config.compensate === "object" ? config.compensate.command : undefined;
+    const rollbackAvailable = hasNativeRollback(target) || compensateCommand !== undefined;
+    if (config.compensate !== undefined && config.compensate !== false && !rollbackAvailable) {
+        throw new Error(`ApplyOp "${config.name}": compensate is enabled, but target "${target}" has no automatic ` +
+            `rollback — the mapped ones are cloudformation's rollbackStack and the ruler's previous-group re-apply. Either supply ` +
+            `compensate: { command: "..." } with a rollback of your own, or set compensate: false.`);
+    }
+    // Compensation defaults on for destructive applies — a partial failure should
+    // unwind rather than leave the cloud half-applied — but only where a rollback
+    // path exists; a destructive apply on a rollback-less target gets no
+    // compensation phase rather than one that could only warn.
+    const compensateDefault = deleteMode !== "never" && rollbackAvailable;
+    const compensateEnabled = config.compensate === undefined ? compensateDefault : config.compensate !== false;
+    const op = Op({
+        name: config.name,
+        overview: `Apply declared source to the ${config.env} environment (code → cloud)`,
+        labels: {
+            Apply: "true",
+            Env: config.env,
+        },
+        phases,
+        ...(compensateEnabled
+            ? {
+                onFailure: [
+                    phase("Rollback", [
+                        activity("compensateApply", {
+                            target,
+                            env: config.env,
+                            ...(target === "ruler" ? { output } : {}),
+                            ...(compensateCommand ? { command: compensateCommand } : {}),
+                        }),
+                    ]),
+                ],
+            }
+            : {}),
+    });
+    return { op };
+}

package/dist/op/composites/behaviour-op.js

@@ -0,0 +1,65 @@
+/**
+ * BehaviourOp composite — the predicted delta of a pull request as a review
+ * finding (#2358, epic #2355).
+ *
+ * One phase, one step: `behaviourFinding` predicts the declared estate on the
+ * pull request's head and on its base branch, differences the two under the
+ * contract's rules, and posts the finding in `comment` mode on the pull
+ * request (GitHub, Forgejo) or as a note on the merge request (GitLab) that
+ * triggered the run. There is no `schedule` here and there never will be: the
+ * cadence is the pull request, and the trigger lives on the `ScheduledOpSpec`
+ * handed to `generateOpsPipeline` (`{ kind: "pull_request" }`), the way
+ * `TerraformWatchOp`'s does.
+ *
+ * `findingMode: "report"` returns the body without posting, for a `chant run`
+ * on a developer's machine with `base` named by hand.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = BehaviourOp({
+ *   name: "pr-behaviour",
+ *   env: "prod",
+ *   traffic: "1000 rps, p99",
+ * });
+ * ```
+ */
+import { Op, phase } from "../builders.js";
+export function BehaviourOp(config) {
+    const mode = config.findingMode ?? "comment";
+    const args = {
+        environment: config.env,
+        traffic: config.traffic,
+        // `op` names this Op in the marker the sticky comment is found by (#2319).
+        op: config.name,
+        mode,
+        ...(config.base ? { base: config.base } : {}),
+        ...(config.stack ? { stack: config.stack } : {}),
+        ...(config.region ? { region: config.region } : {}),
+        ...(config.scope?.owned !== undefined ? { owned: config.scope.owned } : {}),
+    };
+    const op = Op({
+        name: config.name,
+        overview: `Predict the ${config.env} estate's behaviour at "${config.traffic}" against the base branch`,
+        labels: {
+            Behaviour: "true",
+            Env: config.env,
+        },
+        phases: [
+            phase("Predict", [
+                {
+                    kind: "activity",
+                    fn: "behaviourFinding",
+                    args: { ...args },
+                    // The finding's headline is the posted comment, and whether either
+                    // side refused: a refusal is a finding that says "no prediction",
+                    // and a reader of the run ledger should see that without opening it.
+                    outcomeAttribute: [
+                        { name: "Refused", from: "refused" },
+                        ...(mode === "comment" ? [{ name: "Comment", from: "commentUrl" }] : []),
+                    ],
+                },
+            ]),
+        ],
+    });
+    return { op };
+}

package/dist/op/composites/converge-op.js

@@ -0,0 +1,141 @@
+/**
+ * ConvergeOp composite (#1484, epic #1487 feature 1) — the executable
+ * runbook. Observe, classify against a typed rule table, dispatch to
+ * declared ops within a per-tick budget, record, rest. Peer to `WatchOp` /
+ * `ReconcileOp` / `ApplyOp` — same `{ op }` shape, with the cadence on the
+ * Op itself (#2120).
+ *
+ * Phases: `Observe` (snapshot + a quick live diff, exactly `WatchOp`'s own
+ * shape, for the `Drift` outcome and per-phase visibility) ->
+ * `Converge` (one `convergeTick` activity call —
+ * ../activities/converge.ts — that does classify + dispatch + record;
+ * see that module's doc for why this can't be split into further static
+ * phases). `Observe`'s drift signal threads into `Converge`'s args via a
+ * step-output reference (#1290), not a search-attribute round-trip.
+ *
+ * @example
+ * ```typescript
+ * import { ConvergeOp, eq, gt, run, report, when } from "@intentius/chant/op";
+ * import type { ConvergeSymptom } from "@intentius/chant/lifecycle/symptoms";
+ *
+ * export const { op } = ConvergeOp({
+ *   name: "fountain-converge",
+ *   env: "staging",
+ *   dial: "apply",
+ *   schedule: "*\/10 * * * *",
+ *   rules: [
+ *     when<ConvergeSymptom>(eq("status", "drifted"), run("fountain-apply"), {
+ *       id: "drift-apply",
+ *       why: "Live config drifted from declared source; re-apply converges it back.",
+ *     }),
+ *     when<ConvergeSymptom>(gt("adoptCount", 0), report("unowned resources present"), {
+ *       id: "adopt-report",
+ *       why: "An unowned resource is reported for a human to review — never auto-claimed.",
+ *     }),
+ *     when<ConvergeSymptom>(eq("status", "unknown"), report("environment could not be fully observed"), {
+ *       id: "unknown-report",
+ *       why: "unknown never remediates — a partial read is a hole to report, not a guess to act on.",
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @see #1484, #1487
+ */
+import { Op, phase, activity } from "../builders.js";
+import { stepOutput } from "../step-output-ref.js";
+import { isWellFormedPredicate, duplicateRuleIds } from "../converge-rule.js";
+import { CONVERGE_SYMPTOM_FIELDS, RESOURCE_SYMPTOM_FIELDS } from "../../lifecycle/symptoms.js";
+export function ConvergeOp(config) {
+    const dial = config.dial ?? "observe";
+    const budget = config.budget ?? 3;
+    const observer = config.observe !== undefined ? config.observe : undefined;
+    const fields = observer ? RESOURCE_SYMPTOM_FIELDS : CONVERGE_SYMPTOM_FIELDS;
+    // ── Build-time refusals (#1484) ─────────────────────────────────────────
+    // Thrown here, at Op-construction time — the same "refuse in the factory,
+    // named, before anything runs" shape ApplyOp's `compensate` check already
+    // uses. Cross-Op refusals that need the *whole* discovered graph (an
+    // unknown op referenced by `run()`, a mutating/destructive dispatch target
+    // whose own verb class the dial disallows) can't be checked here — a
+    // sibling `*.op.ts` file's Op may not exist yet at the moment this factory
+    // runs — and are instead OPS014's job
+    // (../../lint/rules/op/ops014-converge-rule-refusals.ts), which runs after
+    // the whole project is resolved.
+    if (config.rules.length === 0) {
+        throw new Error(`ConvergeOp "${config.name}": at least one rule is required — an empty table has nothing to converge.`);
+    }
+    const dupes = duplicateRuleIds(config.rules);
+    if (dupes.length > 0) {
+        throw new Error(`ConvergeOp "${config.name}": duplicate rule id(s) [${dupes.join(", ")}] — flap-damping counters are keyed by id, so ids must be unique.`);
+    }
+    if (!Number.isInteger(budget) || budget < 0) {
+        throw new Error(`ConvergeOp "${config.name}": budget must be a non-negative integer, got ${budget}`);
+    }
+    for (const rule of config.rules) {
+        if (!rule.why || rule.why.trim().length === 0) {
+            // Belt-and-suspenders: when() already refuses this, but a rule table
+            // assembled by hand (bypassing when()) reaches here too.
+            throw new Error(`ConvergeOp "${config.name}", rule "${rule.id}": every rule must carry its why — refused at build.`);
+        }
+        if (!isWellFormedPredicate(rule.when, fields)) {
+            throw new Error(`ConvergeOp "${config.name}", rule "${rule.id}": predicate is outside the evaluable subset — build it from ` +
+                `eq/neq/gt/gte/lt/lte/truthy/falsy/allOf/anyOf over a field ${observer ? "ResourceSymptom" : "ConvergeSymptom"} actually produces.`);
+        }
+    }
+    if (observer && observer.kind !== "activity") {
+        throw new Error(`ConvergeOp "${config.name}": observe must be an activity step, such as shell() or spriteServicesObserve()`);
+    }
+    const labels = { Converge: "true", Env: config.env, Dial: dial, ...(observer ? { Observe: "step" } : {}) };
+    const schedule = config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {};
+    if (observer) {
+        // #2778: the observer step is the Observe phase, and its whole result is
+        // the tick's observation.
+        const observeStep = { ...observer, id: observer.id ?? "observe" };
+        const tickStep = activity("convergeTick", { opName: config.name, env: config.env, dial, budget, rules: config.rules, observed: stepOutput(observeStep.id) }, "longInfra");
+        tickStep.outcomeAttribute = { name: "Remediated", from: "remediated" };
+        const op = Op({
+            name: config.name,
+            overview: `Converge ${config.env}'s observed resources toward their declaration (dial: ${dial})`,
+            labels,
+            ...schedule,
+            phases: [phase("Observe", [observeStep]), phase("Converge", [tickStep])],
+        });
+        return { op };
+    }
+    const live = config.live ?? true;
+    const snapshotStep = activity("lifecycleSnapshot", { env: config.env }, { id: "snapshot" });
+    const diffStep = activity("lifecycleDiff", { env: config.env, live }, { id: "diff", profile: "fastIdempotent" });
+    diffStep.outcomeAttribute = { name: "Drift", from: "drifted" };
+    // convergeTick's args are the rule table itself — too shaped (recursive
+    // predicates, a discriminated action union) for a hand-mirrored zod
+    // contract to earn its keep, the same "deliberately partial" call
+    // activity-contracts.ts already makes for kubectlApply/helmInstall's
+    // multi-field args. OPS012 skips an uncontracted `fn`, not flags it — see
+    // that module's doc. The `preflightDrift` step-output reference below is
+    // still fully validated: OPS013's producer-side checks only need
+    // `lifecycleDiff`'s own contract, which is registered.
+    const tickStep = activity("convergeTick", {
+        opName: config.name,
+        env: config.env,
+        dial,
+        budget,
+        rules: config.rules,
+        preflightDrift: diffStep.out.drifted,
+    }, "longInfra");
+    tickStep.outcomeAttribute = { name: "Remediated", from: "remediated" };
+    const op = Op({
+        name: config.name,
+        overview: `Converge the ${config.env} environment toward its declaration (dial: ${dial})`,
+        labels,
+        // Overlap (#1484 acceptance criterion: "skip-and-report when a prior
+        // remediation is in flight ... never queue"). `"skip"` is the only value
+        // `OpSchedule` has, and it means exactly that: a fire arriving while the
+        // previous tick still runs is dropped rather than queued or run
+        // alongside. There is no per-tick "in flight" ledger record for the
+        // skipped fire to produce — nothing ran, so nothing observed, classified,
+        // or dispatched.
+        ...schedule,
+        phases: [phase("Observe", [snapshotStep, diffStep]), phase("Converge", [tickStep])],
+    });
+    return { op };
+}

package/dist/op/composites/index.js

@@ -0,0 +1,19 @@
+/**
+ * The Op composites (#2120) — the named verbs an operator authors instead of
+ * hand-writing phases: watch, reconcile, apply, converge, and the three audit
+ * runners.
+ *
+ * They lived in a hosting lexicon while a cadence meant a scheduler resource;
+ * now that the cadence is `OpConfig.schedule` they are runtime-neutral, each
+ * returns `{ op }`, and nothing here imports a hosting lexicon. A project that
+ * wants a real scheduler resource pairs one with the Op by hand (the pattern
+ * `lexicons/cedar/src/dogwood/replay-op.ts` documents).
+ */
+export { WatchOp } from "./watch-op.js";
+export { ReconcileOp } from "./reconcile-op.js";
+export { ApplyOp } from "./apply-op.js";
+export { ConvergeOp } from "./converge-op.js";
+export { WorkflowAuditOp } from "./workflow-audit-op.js";
+export { PipelineAuditOp } from "./pipeline-audit-op.js";
+export { LexiconUpgradeOp, IN_SCOPE_LEXICONS } from "./lexicon-upgrade-op.js";
+export { BehaviourOp } from "./behaviour-op.js";

package/dist/op/composites/lexicon-upgrade-op.js

@@ -0,0 +1,107 @@
+/**
+ * LexiconUpgradeOp composite — the runner that dogfoods chant to keep each
+ * in-scope lexicon current with its upstream spec (#527, epic #523).
+ *
+ * The shared tooling (#524) does the regen + surface-diff; the pinned (#525)
+ * and rolling (#526) pipelines do the detection. This Op wires them into an
+ * audit-style operational layer, modeled on `WorkflowAuditOp` / `PipelineAuditOp`:
+ * phases detect → run the right check for the lexicon → surface-diff → finding.
+ *
+ * It runs one-shot on the **local Op executor** via `chant run` — nothing
+ * durable is required for an upgrade check (the scheduled CI runner is the
+ * trigger). A `schedule` may still be supplied for continuous re-check; it
+ * lands on the Op itself (#2120).
+ *
+ * Lexicon classification (which check the activity dispatches to):
+ *   ROLLING {aws, azure, github, fly}  → checkRollingUpgrade
+ *   PINNED  any other lexicon whose plugin declares `upstreamPin`
+ *           (k8s, k3s, gcp, docker, gitlab, cedar, sql, ...) → checkPinnedUpgrade
+ * The pinned set is discovered from the plugin at run time, the way `chant dev
+ * pinned-upgrade` does. A pin that moves with other constants (`alsoMoves`, as
+ * sql's version plus digest) is report-only. helm / forgejo are excluded: no
+ * upstream spec.
+ *
+ * Finding-modes mirror ReconcileOp: `report` (default, no external services)
+ * | `issue` | `pull-request`. For the epic goal, `pull-request` opens/updates a
+ * long-lived branch per lexicon.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor, report only
+ * export const { op } = LexiconUpgradeOp({ lexicon: "aws" });
+ *
+ * // weekly, opening a PR when an upgrade is ready
+ * export const { op } = LexiconUpgradeOp({
+ *   lexicon: "k8s",
+ *   schedule: "0 6 * * 1",
+ *   onFinding: "pull-request",
+ * });
+ * ```
+ *
+ * @see #524 — shared regen-validate + surface-diff tooling.
+ * @see #525 — pinned-version bump pipeline.
+ * @see #526 — rolling-spec drift pipeline.
+ */
+import { Op, phase } from "../builders.js";
+/**
+ * The lexicons known to be in scope. This is not a gate: a lexicon that declares
+ * `upstreamPin` is dispatched without being listed. helm / forgejo are excluded
+ * (no upstream spec).
+ */
+export const IN_SCOPE_LEXICONS = [
+    "k8s",
+    "k3s",
+    "sql",
+    "gcp",
+    "docker",
+    "gitlab",
+    "aws",
+    "azure",
+    "github",
+    "fly",
+    "cedar",
+];
+const EXCLUDED_LEXICONS = new Set(["helm", "forgejo"]);
+/**
+ * Build a LexiconUpgradeOp for one lexicon. Rejects the lexicons with no
+ * upstream spec at construction time. Whether any other name declares a pin is
+ * only known by loading its plugin, so the activity checks that at run time and
+ * fails with a clear message for a name that has none.
+ */
+export function LexiconUpgradeOp(config) {
+    if (EXCLUDED_LEXICONS.has(config.lexicon)) {
+        throw new Error(`LexiconUpgradeOp: "${config.lexicon}" is not in scope. ` +
+            `Known lexicons: ${IN_SCOPE_LEXICONS.join(", ")}, and any lexicon declaring upstreamPin ` +
+            `(helm, forgejo have no upstream spec).`);
+    }
+    const name = config.name ?? `${config.lexicon}-upgrade`;
+    const onFinding = config.onFinding ?? "report";
+    const op = Op({
+        name,
+        overview: "Detect a newer upstream spec for the lexicon, regen + validate, and surface the API-surface delta",
+        labels: {
+            Upgrade: "true",
+            Lexicon: config.lexicon,
+        },
+        ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+        phases: [
+            phase("Upgrade", [
+                {
+                    kind: "activity",
+                    fn: "lexiconUpgrade",
+                    args: {
+                        lexicon: config.lexicon,
+                        ...(config.lexiconDir ? { lexiconDir: config.lexiconDir } : {}),
+                        ...(config.pin ? { pin: config.pin } : {}),
+                        mode: onFinding,
+                    },
+                    // Surface whether a PR-worthy upgrade was found as the run's
+                    // `HasUpgrade` outcome on the run ledger, so a reader can pick out
+                    // the lexicons with an upgrade ready.
+                    outcomeAttribute: { name: "HasUpgrade", from: "hasUpgrade" },
+                },
+            ]),
+        ],
+    });
+    return { op };
+}

package/dist/op/composites/pipeline-audit-op.js

@@ -0,0 +1,50 @@
+/**
+ * PipelineAuditOp composite — the live include/component audit of GitLab
+ * pipelines as a chant Op with an optional schedule (#303).
+ *
+ * The gitlab post-synth checks (#297) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — a pinned component/include ref
+ * that no longer resolves, an archived or moved upstream project, or a new
+ * advisory covering a component/image in use. It sits at **observe** on the
+ * lifecycle dial, with a finding-mode (`report | issue | merge-request`) as the
+ * **reconcile** step — for GitLab the PR mode is a merge request.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; a `schedule` puts
+ * the cadence on the Op itself (#2120).
+ *
+ * @example
+ * ```typescript
+ * export const { op } = PipelineAuditOp({
+ *   name: "pipeline-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "merge-request",
+ * });
+ * ```
+ *
+ * @see #297 — the deterministic counterpart this freshens.
+ */
+import { Op, phase } from "../builders.js";
+export function PipelineAuditOp(config) {
+    const onFinding = config.onFinding ?? "report";
+    const op = Op({
+        name: config.name,
+        overview: "Resolve pipeline include/component/image references against live upstreams and report drift",
+        labels: {
+            Audit: "true",
+            Surface: "gitlab-pipeline",
+        },
+        ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" } } : {}),
+        phases: [
+            phase("Audit", [
+                {
+                    kind: "activity",
+                    fn: "pipelineSupplyChainAudit",
+                    args: { pipelineFile: config.pipelineFile ?? ".gitlab-ci.yml", mode: onFinding },
+                    outcomeAttribute: { name: "Findings", from: "findings" },
+                },
+            ]),
+        ],
+    });
+    return { op };
+}