@intentius/chant 0.124.13 → 0.124.14

package/dist/op/builders.js

@@ -0,0 +1,801 @@
+import { OpResource } from "./resource.js";
+import { workLeaseProblems } from "./work-lease-decl.js";
+import { WORK_LEASE_STEP_ID } from "./types.js";
+import { isEffectReceipt } from "../effect-receipt.js";
+import { receiptCheckInput } from "./receipt-store.js";
+import { gateApprovalProblems } from "./gate-approval.js";
+import { gatePointProblems } from "./gate-point.js";
+import { makeOutProxy, stepOutput } from "./step-output-ref.js";
+import { isValidCronExpression, cronSyntaxMessage } from "./cron.js";
+// ── Core builders ─────────────────────────────────────────────────────────────
+/**
+ * Declare a named, phased Op.
+ *
+ * @example
+ * ```ts
+ * export default Op({
+ *   name: "alb-deploy",
+ *   overview: "Build and deploy the ALB multi-service stack",
+ *   phases: [
+ *     phase("Build", [build("examples/gitlab-aws-alb-infra")], { parallel: true }),
+ *     phase("Deploy", [kubectlApply("dist/alb-infra.yaml")]),
+ *   ],
+ * });
+ * ```
+ *
+ * A `schedule` may be supplied for an Op that runs on a cadence (#2120); its
+ * cron is validated here, at construction, so a typo fails on `chant build`
+ * rather than becoming a schedule that silently never fires.
+ */
+export function Op(config) {
+    if (config.schedule && !isValidCronExpression(config.schedule.cron)) {
+        throw new Error(`Op "${config.name}": ${cronSyntaxMessage(config.schedule.cron)}`);
+    }
+    // #2748: a work lease declared badly, or a change to the checkout with none,
+    // fails on `chant build` rather than on the first run.
+    const leaseProblems = workLeaseProblems(config);
+    if (leaseProblems.length > 0)
+        throw new Error(leaseProblems.join("\n"));
+    return new OpResource(config);
+}
+/** Define a named execution phase containing one or more steps. */
+export function phase(name, steps, opts) {
+    return { name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
+}
+/**
+ * Reference a pre-built or custom activity by function name.
+ *
+ * The third argument is a profile string (unchanged) or, to name the step
+ * so a later step can reference its output (#1290), an options object:
+ * `activity("lifecycleDiff", { env: "prod" }, { id: "diff" })`. Named or
+ * not, the result carries `.out` — `diff.out.driftedStacks` builds a
+ * reference to this step's declared return value; see `stepOutput()` in
+ * `@intentius/chant/op` for the equivalent on a step authored as a plain
+ * object literal instead of via this builder.
+ */
+export function activity(fn, args, opts) {
+    const profile = typeof opts === "string" ? opts : opts?.profile;
+    const id = typeof opts === "string" ? undefined : opts?.id;
+    const timeout = typeof opts === "string" ? undefined : opts?.timeout;
+    const step = {
+        kind: "activity",
+        fn,
+        ...(args && Object.keys(args).length > 0 ? { args } : {}),
+        ...(profile ? { profile } : {}),
+        ...(id ? { id } : {}),
+        ...(timeout !== undefined ? { timeout } : {}),
+    };
+    Object.defineProperty(step, "out", {
+        enumerable: false,
+        get() {
+            if (!step.id) {
+                throw new Error(`activity(${JSON.stringify(fn)}, ...).out: this step has no id — pass one via ` +
+                    `activity(fn, args, { id: "..." }) before referencing its output.`);
+            }
+            return makeOutProxy(step.id);
+        },
+    });
+    return step;
+}
+/**
+ * Insert a human gate. A gate is a fact on the gate ledger, not a wait: a run
+ * that reaches this step with no resolution newer than its pending fact
+ * records the pending fact and ends `gated`. `chant approve <op> <gate>`
+ * writes the resolution, and the next run walks through carrying the approver.
+ *
+ * Pass `plan` to bind the approval to a specific plan (#2300) — normally the
+ * Plan phase's own digest, `plan.out.planDigest`. Then a resolution counts
+ * only for that plan, and a run whose fresh plan differs is refused by name
+ * instead of applying a change nobody approved. See {@link GateStep.plan}.
+ *
+ * Pass `approval` to require a quorum of human approvers, or to evaluate a
+ * policy for each approval (#2508). See {@link GateStep.approval}.
+ *
+ * Pass `point` to have the gate ask a declared decision point instead
+ * (#3170): `gate("apply", { plan: plan.out.digest, point: "prod-apply" })`.
+ * The point's deciders and quorum decide, `chant workspace points answer`
+ * answers an open question, and the run passes on the answer. See
+ * {@link GateStep.point}.
+ */
+export function gate(name, opts) {
+    if (opts?.approval !== undefined) {
+        const problems = gateApprovalProblems(opts.approval);
+        if (problems.length > 0)
+            throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
+    }
+    if (opts?.point !== undefined) {
+        const problems = gatePointProblems(opts.point, opts.approval !== undefined);
+        if (problems.length > 0)
+            throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
+    }
+    return {
+        kind: "gate",
+        gate: name,
+        ...(opts?.timeout ? { timeout: opts.timeout } : {}),
+        ...(opts?.description ? { description: opts.description } : {}),
+        ...(opts?.plan !== undefined ? { plan: opts.plan } : {}),
+        ...(opts?.approval !== undefined ? { approval: opts.approval } : {}),
+        ...(opts?.point !== undefined ? { point: opts.point } : {}),
+    };
+}
+/**
+ * Wrap nested steps in read-compare-run-write over an effect receipt (#1834,
+ * epic #1703). At run: read the live receipt through the receipt store,
+ * compare it against the resolved expectation, and on a match skip the nested
+ * steps ("effect already applied"). On a mismatch the nested steps run in
+ * authored order, and ONLY when every one of them succeeds is the receipt
+ * written — last, once. This step is the sole writer of a receipt (decision
+ * 3); a nested-step failure leaves the receipt untouched (stale), so the next
+ * run re-proposes the effect.
+ *
+ * `receipt` is the typed EffectReceipt declaration — import the const from
+ * your receipts module. There is no string form: a receipt named by string
+ * would sever the step from the declaration that lint, plan, and the lexicon
+ * row all key on.
+ *
+ * A gate authored inside `steps` is reached only when the effect will fire
+ * (the matched path never reaches it). The receipt-store activities
+ * (`receiptRead`, `receiptWrite`) are provided by the receipt row's lexicon
+ * (#1835 aws, #2074 k8s), or in a sql-only project by the sql lexicon's
+ * store on the database server (#3657).
+ *
+ * @example
+ * ```ts
+ * import { seededReceipt } from "./receipts";
+ * phase("Seed", [
+ *   effect(seededReceipt, [
+ *     shell("npm run db:seed"),
+ *   ]),
+ * ]),
+ * ```
+ */
+export function effect(receipt, steps, opts) {
+    if (!isEffectReceipt(receipt)) {
+        throw new Error("effect(): `receipt` must be the EffectReceipt declaration itself — import the const; there is no string form");
+    }
+    for (const step of steps) {
+        if (step.kind === "effect") {
+            throw new Error(`effect("${receipt.name}"): effect steps do not nest — one receipt witnesses one effect`);
+        }
+    }
+    const { receipt: ref, expectation } = receiptCheckInput(receipt);
+    return {
+        kind: "effect",
+        receipt: ref,
+        ...(expectation !== undefined ? { expectation } : {}),
+        steps,
+        ...(opts?.description ? { description: opts.description } : {}),
+    };
+}
+// ── Pre-built activity shortcuts ──────────────────────────────────────────────
+/**
+ * Pull an optional `profile` override out of an opts bag, returning the
+ * remaining keys (which become activity args) separately.
+ *
+ * Without this, a `profile` passed in opts would spread into the activity's
+ * **args** rather than set the step's `profile` — a silent no-op on the step's
+ * timeout. The activity then runs under the default profile, so a step the
+ * author tagged `longInfra` (20m) would still get the 5m default. Routing it
+ * here lets every shortcut accept a `profile` override that actually takes.
+ */
+function takeProfile(opts) {
+    if (!opts)
+        return { args: {} };
+    const { profile, ...args } = opts;
+    return { args, profile };
+}
+/**
+ * {@link takeProfile}'s sibling for the typed, lexicon-owned step-builder
+ * wrappers added in chant #1288 Stage 2 (e.g. `kubectlApply` in
+ * `@intentius/chant-lexicon-k8s`): also pulls `id` out of the opts bag so it
+ * routes to the step's `id` field (enabling `.out` — #1290) instead of
+ * leaking into the activity's args, the same way `profile` would without
+ * this split.
+ */
+export function takeProfileAndId(opts) {
+    if (!opts)
+        return { args: {} };
+    const { profile, id, ...args } = opts;
+    return { args, profile, id };
+}
+/**
+ * Run an npm build script in the given project directory. `opts` is
+ * {@link ChantBuildArgs} itself, minus the positional `path` — `script`
+ * selects the npm script (default `build`, e.g. `build:aws`), `env` adds
+ * env vars.
+ */
+export const build = (path, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("chantBuild", { path, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
+};
+/** Run `kubectl apply -f <manifest>`. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const kubectlApply = (manifest, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("kubectlApply", { manifest, ...args }, profile ?? "longInfra");
+};
+/** Run `helm upgrade --install`. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const helmInstall = (name, chart, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("helmInstall", { name, chart, ...args }, profile ?? "longInfra");
+};
+/**
+ * Deploy a recorded pinned render by its `sha256:` content digest (chant
+ * #1242): the helm lexicon's `helmInstall` activity loads the render from
+ * the render store, verifies the digest, and installs those exact bytes as
+ * a structure-preserving wrapper chart — no deploy-time render. Defaults to
+ * the `longInfra` profile (override via `opts.profile`).
+ */
+export const helmInstallPinned = (name, contentDigest, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("helmInstall", { name, contentDigest, ...args }, profile ?? "longInfra");
+};
+/**
+ * Poll until a Kubernetes Deployment/StatefulSet is fully rolled out. `opts` is
+ * {@link WaitForStackArgs} itself, minus the positional `name`. Defaults to the
+ * `k8sWait` profile (override via `opts.profile`).
+ */
+export const waitForStack = (name, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("waitForStack", { name, ...args }, { profile: profile ?? "k8sWait", ...(id ? { id } : {}) });
+};
+/** Poll any operator-backed Kubernetes resource until it reports ready, driven by a data-only readiness spec (CRD-aware; #365). Defaults to the `k8sWait` profile (override via `opts.profile`). */
+export const waitForReady = (kind, name, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("waitForReady", { kind, name, ...args }, profile ?? "k8sWait");
+};
+/** Trigger and wait for a GitLab CI pipeline to complete. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const gitlabPipeline = (name, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("gitlabPipeline", { name, ...args }, profile ?? "longInfra");
+};
+/**
+ * Take a chant lifecycle snapshot for the given environment.
+ * {@link LifecycleSnapshotArgs} has only `env`, which is positional here, so
+ * `opts` carries nothing but the step's `id` (for `.out`).
+ */
+export const lifecycleSnapshot = (env, opts) => activity("lifecycleSnapshot", { env }, opts?.id ? { id: opts.id } : undefined);
+/**
+ * Run an arbitrary shell command.
+ *
+ * Defaults to the `atMostOnce` profile: twenty minutes, one attempt (#2411).
+ * This is the one activity chant cannot know is idempotent, because its
+ * purpose is to run something chant does not model, so a failed command is
+ * not repeated unless the author says it may be. Name `fastIdempotent` or
+ * `longInfra` to get retries back for a command that is safe to repeat.
+ *
+ * Give the step an `id` and later steps can read what it produced —
+ * `sh.out.stdout`, `sh.out.stderr`, `sh.out.exitCode` (#2413) — and a value
+ * from an earlier step reaches the command through `env` (#2414):
+ *
+ * ```ts
+ * const host = shell("terraform output -raw host", { id: "host" });
+ * shell("./smoke.sh", { env: { HOST: host.out.stdout } });
+ * ```
+ *
+ * With `json: true`, stdout is parsed as JSON and published as `json`
+ * (#2787), so a list or an object reaches the next step or the Op's work
+ * lease as itself. A pick step that prints `["W-3","W-7"]` hands
+ * `workLease.item` its candidates:
+ *
+ * ```ts
+ * const pick = shell("node pick.mjs", { id: "pick", json: true });
+ * Op({ workLease: { item: pick.out.json }, ... });
+ * ```
+ *
+ * `timeout` sets how long the one attempt may run, in place of the profile's
+ * twenty minutes, and keeps the profile's retries: `shell("./build.sh", {
+ * timeout: "45m" })`. At most six hours (`MAX_STEP_TIMEOUT`).
+ *
+ * `cmd` stays a plain `string` and takes no references. A value spliced into
+ * a command line is a quoting decision chant would then be making on the
+ * author's behalf, and `env` carries the same value into the same command
+ * with the shell's own rules intact.
+ */
+export const shell = (cmd, opts) => {
+    const { timeout, ...rest } = (opts ?? {});
+    const { args, profile, id } = takeProfileAndId(rest);
+    return activity("shellCmd", { cmd, ...args }, { profile: profile ?? "atMostOnce", ...(id ? { id } : {}), ...(timeout !== undefined ? { timeout } : {}) });
+};
+/**
+ * Archive one directory of HEAD as a release artifact (#2782): a tar written by
+ * `git archive`, named by its sha256, the same bytes for the same commit.
+ * Defaults to the `fastIdempotent` profile.
+ *
+ * ```ts
+ * const archive = sourceArchive("../app", { id: "archive" });
+ * ```
+ */
+export const sourceArchive = (path, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("sourceArchive", { path, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Plan a release (#2782): a JSON object named by the sha256 of its canonical
+ * form, which the ship gate binds to (`gate("ship", { plan: plan.out.digest })`)
+ * and the release ledger records. Defaults to the `fastIdempotent` profile.
+ */
+export const releasePlan = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("releasePlan", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Join members' change-set parts into one document (#3181). Its `digest` is
+ * what a combined run's gate binds: `gate("approve", { plan:
+ * changeSet.out.digest })`. Defaults to the `fastIdempotent` profile.
+ */
+export const composeChangeSet = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("composeChangeSet", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/** A chant member's change-set part, from `chant lifecycle plan <env> --json` (#3181). Its `part` feeds {@link composeChangeSet}. */
+export const lifecyclePlanChangeSet = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("lifecyclePlanChangeSet", rest, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/** A member's change-set part from a plan file a chant or warden run wrote (#3181). Its `part` feeds {@link composeChangeSet}. */
+export const readChangeSetPart = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("readChangeSetPart", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Record a release in the release ledger with its plan (#2782, ws-055), once:
+ * a retry whose release the ledger already names records nothing. Defaults to
+ * the `fastIdempotent` profile.
+ */
+export const releaseRecord = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("releaseRecord", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Ask a decision point and record its answer (ws-058, #2740): the `decide`
+ * activity, core's since #2828. `opts` is the activity's own
+ * {@link DecideArgs}, minus the positional `point`, so the builder and the
+ * activity cannot drift. Defaults to the `fastIdempotent` profile: asking
+ * again with the same point, declaration and inputs returns the record
+ * already written. An open question stops the run `waiting`.
+ *
+ * ```ts
+ * decide("slice-tier", { read: { "work-item": "W-002" }, subject: "W-002" })
+ * ```
+ */
+export const decide = (point, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("decide", { point, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Plan a rollback of a source release (#2800): the release the site served
+ * before the latest one (or `to`), its plan read back from the ledger, and its
+ * source tree archived again from its commit and refused unless it hashes to
+ * the digest that plan recorded. Writes a rollback plan named by its own
+ * sha256, which the rollback gate binds to (`gate("rollback", { plan:
+ * plan.out.digest })`). Defaults to the `fastIdempotent` profile.
+ */
+export const releaseRollbackPlan = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("releaseRollbackPlan", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Record a rollback in the release ledger (#2800): the restored release's
+ * digest and commit, `restores` naming that release, the actor and the gate's
+ * approver, once. Defaults to the `fastIdempotent` profile.
+ */
+export const releaseRollbackRecord = (args) => {
+    const { args: rest, profile, id } = takeProfileAndId(args);
+    return activity("releaseRollbackRecord", rest, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Ensure a `generated-once` secret exists in the target store (#1829, epic
+ * #1365). The op-step surface over the same engine as the `ensure-secret`
+ * capability verb (`ensureSecretMaterialization`, core's
+ * secret-materialization module): read-then-write — if the secret exists, its
+ * declared key-set and any declared `metadata` are verified and the step
+ * stops (present means done); if absent, one value per key is minted at
+ * apply time and written straight to the store. Never mints over an existing
+ * value, never rotates implicitly; a mismatch fails the step loudly, naming
+ * key names and metadata keys — never values. No output of the activity
+ * carries secret material. The backing activity is provided by the store's
+ * lexicon (k8s, #1830).
+ */
+export const ensureSecret = (name, keys, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("ensureSecret", { name, keys, ...args }, profile);
+};
+/**
+ * Run `chant teardown` in the given project directory. Fixed `longInfra`
+ * profile (not overridable). {@link ChantTeardownArgs} has only `path`
+ * (positional), so `opts` is just the step's `id` (for `.out`).
+ */
+export const teardown = (path, opts) => activity("chantTeardown", { path }, { profile: "longInfra", ...(opts?.id ? { id: opts.id } : {}) });
+/**
+ * Tear down one environment's marker-owned resources — the durable form of
+ * `chant lifecycle teardown <env> --yes` (#1222). The activity runs core's
+ * teardown engine in-process: enumerate by ownership marker (this project's
+ * `ownership.stack` + `env`), delete through each lexicon's `executeTeardown`
+ * capability, retry failures once, and fail the step when any candidate is
+ * still failed. Distinct from {@link teardown}, which runs a project's own
+ * `npm run teardown` script.
+ *
+ * The CLI's guards apply unchanged, and a production-like environment name
+ * needs `confirmProd: true` in `opts` — the authored counterpart of
+ * `--confirm-prod`, since an Op never prompts. An ordinary {@link gate} step
+ * placed before this one composes as usual (steps run in authored order), so
+ * a human approval can precede the deletion:
+ *
+ * ```ts
+ * phase("Teardown", [
+ *   gate("approve-teardown", { description: "Release the staging teardown" }),
+ *   envTeardown("staging"),
+ * ]),
+ * ```
+ *
+ * `opts` also accepts `path` (the chant project directory, default the chant
+ * process's cwd). Defaults to the `longInfra` profile (override via
+ * `opts.profile`).
+ */
+export const envTeardown = (env, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("envTeardown", { env, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
+};
+/**
+ * Create a local k3d cluster (vanilla Kubernetes in Docker). Idempotent: skips
+ * creation if a cluster of the same name already exists. Defaults to the
+ * `longInfra` profile (creating a cluster may pull the k3s image); override via
+ * `opts.profile`.
+ *
+ * The implementation lives in the k3d lexicon (chant #1410) — the project's
+ * `chant.config.ts` must list `"k3d"` in `lexicons` for the activity to load.
+ * Unlike the upstream CLI, the activity leaves the caller's default kubeconfig
+ * and current context alone by default (chant #1411); pass
+ * `updateDefaultKubeconfig: true` / `switchCurrentContext: true` to opt back
+ * in. It resolves `{ context, kubeconfigPath? }` for reaching the cluster.
+ *
+ * `opts` accepts `servers`, `agents`, `image`, `ports` (e.g.
+ * `["8080:80@loadbalancer"]`), `registryCreate`, `configFile`, `timeout`,
+ * `updateDefaultKubeconfig`, and `switchCurrentContext`.
+ */
+export const k3dUp = (name, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("k3dUp", { name, ...args }, profile ?? "longInfra");
+};
+/**
+ * Delete a local k3d cluster. Defaults to the `fastIdempotent` profile
+ * (override via `opts.profile`). Implementation lives in the k3d lexicon
+ * (chant #1410) — requires `"k3d"` in the project's `lexicons`.
+ */
+export const k3dDown = (name, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("k3dDown", { name, ...args }, profile ?? "fastIdempotent");
+};
+/**
+ * Run the pinned k3s installer against a reachable host (`role`: `"server"`
+ * or `"agent"`). Idempotent on an already-installed matching version.
+ * Defaults to the `longInfra` profile (the installer downloads and starts
+ * the binary); override via `opts.profile`.
+ *
+ * The implementation lives in the k3s lexicon (chant #1601) — the project's
+ * `chant.config.ts` must list `"k3s"` in `lexicons` for the activity to load.
+ * Bounded exactly as `k3dUp`/`k3dDown` (chant #1410): drives the reachable-host
+ * case only, no host provisioning, no SSH orchestration.
+ *
+ * `opts` accepts `configFile` (required — path to the chant-emitted
+ * config.yaml, passed as `--config`), `version` (overrides the lexicon's
+ * pinned `INSTALL_K3S_VERSION`), and `tokenFile` (path to a file holding the
+ * join token, passed to the installer as `K3S_TOKEN_FILE`). There is no
+ * `token` option — the join secret's value never travels through this step;
+ * only a file path does (the #1601 token boundary, same stance as #1365).
+ */
+export const k3sInstall = (role, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("k3sInstall", { role, ...args }, profile ?? "longInfra");
+};
+/**
+ * Uninstall k3s from a reachable host (`role`: `"server"` or `"agent"`).
+ * Defaults to the `fastIdempotent` profile (override via `opts.profile`).
+ * Implementation lives in the k3s lexicon (chant #1601) — requires `"k3s"`
+ * in the project's `lexicons`. A host where k3s was never installed is a
+ * no-op success, the same shape as `k3dDown` against an already-gone
+ * cluster.
+ */
+export const k3sUninstall = (role, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("k3sUninstall", { role, ...args }, profile ?? "fastIdempotent");
+};
+/**
+ * Boot a local Floci AWS emulator in Docker and point subsequent steps at it —
+ * sets `AWS_ENDPOINT_URL` + test creds in the process env so a following
+ * `cloudformation` apply targets the emulator (local executor). Idempotent:
+ * reuses a running container of the same name. Defaults to the `longInfra`
+ * profile (the image may pull); override via `opts.profile`.
+ *
+ * `opts` accepts `name`, `port`, `image`, `dockerSocket` (mount the docker
+ * socket for the ECR backing registry), `region`, `readyService`, `timeoutMs`.
+ */
+export const flociUp = (opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("flociUp", args, profile ?? "longInfra");
+};
+/** Stop and remove the local Floci emulator container. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const flociDown = (opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("flociDown", args, profile ?? "fastIdempotent");
+};
+/**
+ * Boot a local floci-az (Azure emulator) and return its ARM `endpoint` — the
+ * typed twin of {@link flociUp} for `azApply`, so the emulator lifecycle is a
+ * modeled step, not a `docker run` shell. Provided by the azure lexicon; loaded
+ * when the project lists `azure`. Idempotent; defaults to the `longInfra`
+ * profile. `opts` accepts `name`, `port`, `image`, `timeoutMs`, `intervalMs`.
+ */
+export const flociAzUp = (opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("flociAzUp", args, profile ?? "longInfra");
+};
+/** Stop and remove the local floci-az container. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const flociAzDown = (opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("flociAzDown", args, profile ?? "fastIdempotent");
+};
+/**
+ * Boot a local floci-gcp (GCP emulator) and return its `endpoint` — the typed
+ * twin of {@link flociUp} for `gcpApply`, so the emulator lifecycle is a modeled
+ * step, not a `docker run` shell. Provided by the gcp lexicon; loaded when the
+ * project lists `gcp`. Idempotent; defaults to the `longInfra` profile. `opts`
+ * accepts `name`, `port`, `image`, `timeoutMs`, `intervalMs`.
+ */
+export const flociGcpUp = (opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("flociGcpUp", args, profile ?? "longInfra");
+};
+/** Stop and remove the local floci-gcp container. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const flociGcpDown = (opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("flociGcpDown", args, profile ?? "fastIdempotent");
+};
+/**
+ * Assert an HTTP endpoint responds as expected — a typed verify step replacing
+ * `shell("curl -fs ...")`. Fails the phase if the status/body doesn't match.
+ * Defaults to the `fastIdempotent` profile. `opts` accepts `method`, `status`
+ * (default any 2xx), `contains` (body substring), `retries`, `intervalMs`.
+ */
+export const httpCheck = (url, opts) => {
+    const { args, profile, id } = takeProfileAndId(opts);
+    return activity("httpCheck", { url, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
+};
+/**
+ * Ensure an Azure resource group exists before an ARM apply. `az deployment
+ * group create` (the `arm` apply target) fails without its group, so place this
+ * before the deploy phase. Idempotent. Defaults to the `fastIdempotent` profile
+ * (override via `opts.profile`). `opts` accepts `location` (default `eastus`).
+ */
+export const azGroupEnsure = (resourceGroup, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("azGroupEnsure", { resourceGroup, ...args }, profile ?? "fastIdempotent");
+};
+/** Delete an Azure resource group and its contents (non-blocking). Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
+export const azGroupDelete = (resourceGroup, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("azGroupDelete", { resourceGroup, ...args }, profile ?? "fastIdempotent");
+};
+/**
+ * Apply chant's built ARM template directly to the ARM resource API — the Azure
+ * twin of {@link gcpApply}. Targets floci-az's resource CRUD (which `az deployment`
+ * can't, floci-az having no deployments provider) or real Azure by endpoint
+ * override; ensures the resource group first. Defaults to the `longInfra` profile.
+ *
+ * `opts` requires `resourceGroup`; accepts `location`, `endpoint` (floci-az
+ * `http://localhost:4577`), `subscriptionId`, and `prune` (owned-only prune of
+ * chant-managed resources no longer in the template — destructive, off by default).
+ */
+export const azApply = (templatePath, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("azApply", { templatePath, ...args }, profile ?? "longInfra");
+};
+/** Delete the Azure (ARM) resources in a built template — the inverse of {@link azApply}. Defaults to the `longInfra` profile (override via `opts.profile`). `opts` requires `resourceGroup`. */
+export const azDelete = (templatePath, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("azDelete", { templatePath, ...args }, profile ?? "longInfra");
+};
+/**
+ * Deploy a built CloudFormation template by calling the CloudFormation API
+ * directly (create-or-update + poll) — the direct twin of {@link azApply} /
+ * {@link gcpApply} for AWS, targeting a local Floci emulator or real AWS by
+ * endpoint override. Speaks the CFN API over HTTP rather than shelling `aws` —
+ * `nativeApply({ target: "cloudformation" })` routes here too (#1449). Provided by
+ * the aws lexicon; loaded when the project lists `aws`. Defaults to the
+ * `longInfra` profile. `opts` requires `stackName`; accepts `endpoint`, `region`,
+ * `capabilities`, `timeoutMs`, `intervalMs`.
+ */
+export const awsApply = (templatePath, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("awsApply", { templatePath, ...args }, profile ?? "longInfra");
+};
+/** Delete a CloudFormation stack — the inverse of {@link awsApply}. Defaults to the `longInfra` profile (override via `opts.profile`). `opts` requires `stackName`. */
+export const awsDelete = (templatePath, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("awsDelete", { templatePath, ...args }, profile ?? "longInfra");
+};
+/**
+ * Apply chant's built GCP (CNRM) resources directly to their GCP REST APIs,
+ * targeting a local floci-gcp emulator or real GCP by endpoint override — the
+ * native GCP applier (#706 starter #711). `nativeApply({ target: "gcp" })`
+ * routes here too (#1449). Defaults to the `longInfra` profile (override via
+ * `opts.profile`).
+ *
+ * `opts` accepts `endpoint` (default `GCP_ENDPOINT_URL` env / each kind's
+ * real-GCP host) and `project` (default `GOOGLE_CLOUD_PROJECT` env / the CNRM
+ * project-id annotation).
+ */
+export const gcpApply = (manifestPath, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("gcpApply", { manifestPath, ...args }, profile ?? "longInfra");
+};
+/** Delete the GCP (CNRM) resources in a built manifest — the inverse of {@link gcpApply}. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const gcpDelete = (manifestPath, opts) => {
+    const { args, profile } = takeProfile(opts);
+    return activity("gcpDelete", { manifestPath, ...args }, profile ?? "longInfra");
+};
+// ── Sprites (#762) — imperative, checkpointable sandbox steps ──────────────────
+//
+// The builder and the executor-side activity function share a name (e.g.
+// `spriteCreate`), and that is intentional: the builder here returns an
+// `activity("spriteCreate", ...)` step; `loadActivities` loads the function of
+// the same name from the fly lexicon to run the HTTP. They live in
+// different modules and are both exported — exactly how `flapsUp`/`flapsDown`
+// already work. Op files import these builders; the executor resolves the
+// function by name. Endpoint override + bearer are read by the activity from
+// `SPRITES_BASE_URL` / `SPRITES_API_TOKEN` (or an explicit `endpoint` arg).
+/** Create a sprite with a caller-chosen `name` (used as its id). Defaults to the `longInfra` profile (override via `profile`). */
+export const spriteCreate = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteCreate", rest, profile ?? "longInfra");
+};
+/** Run a command in a sprite; a non-zero exit fails the step. Defaults to the `longInfra` profile (override via `profile`). */
+export const spriteExec = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteExec", rest, profile ?? "longInfra");
+};
+/** Checkpoint a sprite under a caller-chosen `comment` (the transactional boundary). Defaults to the `longInfra` profile (override via `profile`). */
+export const spriteCheckpoint = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteCheckpoint", rest, profile ?? "longInfra");
+};
+/**
+ * Restore a sprite — the checkpoint-as-compensation step (S5). Target an
+ * explicit `checkpoint` id, or the newest checkpoint carrying `comment`, or (with
+ * neither) the newest checkpoint overall. Defaults to the `longInfra` profile
+ * (override via `profile`).
+ */
+export const spriteRestore = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteRestore", rest, profile ?? "longInfra");
+};
+/** List a sprite's checkpoints (`[{ id, comment, create_time, is_auto }]`). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const listCheckpoints = (args) => {
+    const { profile, ...rest } = args;
+    return activity("listCheckpoints", rest, profile ?? "fastIdempotent");
+};
+/** Destroy a sprite (idempotent). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteDestroy = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteDestroy", rest, profile ?? "fastIdempotent");
+};
+// ── Sprite filesystem steps (#848) — stage inputs / read results without exec ──
+//
+// Same builder/activity split as the lifecycle steps above: these author
+// `activity("spriteWriteFile", ...)` steps; `loadActivities(["fly"])` binds them
+// to the implementations in fly's `op/activities/sprite-fs.ts`. All default to
+// `fastIdempotent` — write/remove converge on the same end state under retry.
+/** Write a file into a sprite. Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteWriteFile = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteWriteFile", rest, profile ?? "fastIdempotent");
+};
+/** Read a file from a sprite (returns `{ content }`). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteReadFile = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteReadFile", rest, profile ?? "fastIdempotent");
+};
+/** List a directory in a sprite (returns `[{ name, type, size? }]`). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteListDir = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteListDir", rest, profile ?? "fastIdempotent");
+};
+/** Remove a path in a sprite (idempotent). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteRemove = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteRemove", rest, profile ?? "fastIdempotent");
+};
+// ── Sprite config reconcile steps (#849) — desired-state on a live Sprite ──────
+//
+// Apply-activities, not a declarable resource: `spriteApplyNetworkPolicy`
+// whole-object-replaces the outbound policy; `spriteApplyServices` create-or-
+// updates each desired background service (optionally starting them in
+// dependency order). Validation runs pure before any HTTP. `loadActivities(["fly"])`
+// binds the impls in fly's `op/activities/sprite-config.ts`.
+/** Reconcile a sprite's outbound network policy (whole-object replace). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteApplyNetworkPolicy = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteApplyNetworkPolicy", rest, profile ?? "fastIdempotent");
+};
+/**
+ * Reconcile a sprite's background services (create-or-update, optionally
+ * start). With an `id`, through the Sprites API and its `services`; without
+ * one, inside the sprite through sprite-env, applying the box block's
+ * services (`box: true`, #2880): `only` names some of them, `start` starts
+ * the applied ones that are not running, `restart` restarts the converged
+ * ones. Defaults to the `fastIdempotent` profile (override via `profile`).
+ */
+export const spriteApplyServices = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteApplyServices", rest, profile ?? "fastIdempotent");
+};
+// ── Sprite keep-alive Task steps (#847) — hold a Sprite active for a session ──
+//
+// A hold stops the Sprite pausing while a session runs; release frees it. A
+// session that can outlast the 1-hour task cap refreshes in its own loop.
+// `loadActivities(["fly"])` binds the impls in fly's `op/activities/sprite-tasks.ts`.
+/** Create a keep-alive task holding the sprite active. Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteTaskCreate = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteTaskCreate", rest, profile ?? "fastIdempotent");
+};
+/** Refresh a keep-alive task's expiry. Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteTaskRefresh = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteTaskRefresh", rest, profile ?? "fastIdempotent");
+};
+/** Release a keep-alive task (idempotent). Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spriteTaskRelease = (args) => {
+    const { profile, ...rest } = args;
+    return activity("spriteTaskRelease", rest, profile ?? "fastIdempotent");
+};
+/**
+ * Boot a local spritzer (Fly Sprites API emulator) in Docker — the typed twin of
+ * `flociGcpUp` for Sprites. Resolves to the `spritesUp` activity. Defaults to the
+ * `longInfra` profile (the image may pull); override via `profile`.
+ */
+export const spritesUp = (args = {}) => {
+    const { profile, ...rest } = args;
+    return activity("spritesUp", rest, profile ?? "longInfra");
+};
+/** Stop and remove the local spritzer container. Resolves to the `spritesDown` activity. Defaults to the `fastIdempotent` profile (override via `profile`). */
+export const spritesDown = (args = {}) => {
+    const { profile, ...rest } = args;
+    return activity("spritesDown", rest, profile ?? "fastIdempotent");
+};
+/**
+ * Gate an apply on organizational policy: build the project and run its
+ * `lint.policies` over the resolved resources, failing the step on any
+ * violation so no later phase runs. Place it before the apply phase. `env` (or `ownership.env`) lets a
+ * policy branch on environment. Single-attempt (`policyCheck` profile) — a
+ * deterministic violation is not retried.
+ */
+export const policyGate = (opts) => {
+    const path = opts?.path ?? ".";
+    const env = opts?.env;
+    return activity("policyGate", { path, ...(env !== undefined ? { env } : {}) }, { profile: "policyCheck", ...(opts?.id ? { id: opts.id } : {}) });
+};
+/**
+ * Attach evidence to an acceptance criterion of the work item the run holds
+ * the lease on (#2772), for an Op that declares `workLease`. The run's lease
+ * is passed for it, so the write happens only while the lease is still the
+ * run's. `opts` takes the `result` (pass or fail), a `title`, and a `url` or a
+ * workspace `path` to pin by hash. A `manual` criterion is refused: the run
+ * is the item's implementer. The `atMostOnce` profile: each attempt appends.
+ */
+export const workEvidence = (criterion, opts) => {
+    const { id, ...rest } = opts;
+    return activity("workEvidence", { criterion, lease: stepOutput(WORK_LEASE_STEP_ID), ...rest }, { profile: "atMostOnce", ...(id ? { id } : {}) });
+};
+/**
+ * Run an external CloudFormation Guard rules pack against the project's built
+ * CloudFormation template (chant #522). `opts` is {@link GuardValidateArgs}
+ * itself, minus the positional `rules`; `template` defaults (inside the
+ * activity) to `<path>/template.json`. Fixed `policyCheck` profile — same
+ * reasoning as {@link policyGate}: a deterministic policy check is
+ * single-attempt — and not overridable.
+ */
+export const guardValidate = (rules, opts) => {
+    const { id, ...rest } = (opts ?? {});
+    return activity("guardValidate", { rules, ...rest }, { profile: "policyCheck", ...(id ? { id } : {}) });
+};