@intentius/chant 0.56.0 → 0.58.0

package/src/op/builders-typed.test.ts

@@ -0,0 +1,164 @@
+/**
+ * The typed step-builder wrappers over core's own base activities (chant #1288
+ * Stage 2, moved here from a hosting lexicon by #2114). `opts` in each is
+ * the activity's own `*Args` interface (`./activities/*.ts`) via `Omit`/
+ * `WithStepRefs`, never a hand-restated mirror, so a signature change in the
+ * activity is a compile error at the builder rather than a silently-dropped arg.
+ *
+ * These are asserted against the `ActivityStep` they emit — the fixed profiles
+ * (`policyGate`/`guardValidate` on `policyCheck`, `teardown` on `longInfra`)
+ * and defaults (`waitForStack` → `k8sWait`, `httpCheck`/`envTeardown`) are
+ * pinned here, since there is no longer a second, untyped implementation to
+ * compare against.
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  build,
+  shell,
+  waitForStack,
+  lifecycleSnapshot,
+  teardown,
+  envTeardown,
+  httpCheck,
+  policyGate,
+  guardValidate,
+  stepOutput,
+  type StepOutputRef,
+} from "./index";
+
+describe("typed step builders over the base activities", () => {
+  test("build: names chantBuild, path is positional, opts spread into args", () => {
+    expect(build("examples/gitlab-aws-alb-infra")).toMatchObject({
+      kind: "activity",
+      fn: "chantBuild",
+      args: { path: "examples/gitlab-aws-alb-infra" },
+    });
+    expect(build(".", { script: "build:aws", env: { NODE_ENV: "production" } })).toMatchObject({
+      fn: "chantBuild",
+      args: { path: ".", script: "build:aws", env: { NODE_ENV: "production" } },
+    });
+  });
+
+  test("shell: names shellCmd; env and profile route where they belong", () => {
+    expect(shell("npm run db:seed")).toMatchObject({ fn: "shellCmd", args: { cmd: "npm run db:seed" } });
+    const step = shell("docker push image", { env: { FOO: "bar" }, profile: "longInfra" });
+    expect(step.args).toEqual({ cmd: "docker push image", env: { FOO: "bar" } });
+    expect(step.profile).toBe("longInfra");
+  });
+
+  test("shell: cwd is reachable (the untyped builder this replaced dropped it)", () => {
+    const step = shell("ls", { cwd: "/tmp" });
+    expect(step.args?.cwd).toBe("/tmp");
+  });
+
+  test("waitForStack: defaults to the k8sWait profile", () => {
+    const step = waitForStack("alb-api", { namespace: "alb" });
+    expect(step).toMatchObject({ fn: "waitForStack", args: { name: "alb-api", namespace: "alb" } });
+    expect(step.profile).toBe("k8sWait");
+  });
+
+  test("lifecycleSnapshot: env is the only arg", () => {
+    expect(lifecycleSnapshot("staging")).toMatchObject({
+      fn: "lifecycleSnapshot",
+      args: { env: "staging" },
+    });
+  });
+
+  test("lifecycleSnapshot: .out is reachable via an id", () => {
+    const step = lifecycleSnapshot("staging", { id: "snap" });
+    const ref: StepOutputRef = step.out.env;
+    expect(ref.step).toBe("snap");
+    expect(ref.path).toBe("env");
+  });
+
+  test("teardown: fixed longInfra profile", () => {
+    const step = teardown("examples/getting-started");
+    expect(step).toMatchObject({ fn: "chantTeardown", args: { path: "examples/getting-started" } });
+    expect(step.profile).toBe("longInfra");
+  });
+
+  test("envTeardown: defaults to longInfra, confirmProd passes through", () => {
+    const step = envTeardown("prod", { confirmProd: true });
+    expect(step.args).toEqual({ env: "prod", confirmProd: true });
+    expect(step.profile).toBe("longInfra");
+  });
+
+  test("httpCheck: defaults to fastIdempotent", () => {
+    const step = httpCheck("https://example.com/health", { status: 200, contains: "ok" });
+    expect(step.args).toEqual({ url: "https://example.com/health", status: 200, contains: "ok" });
+    expect(step.profile).toBe("fastIdempotent");
+  });
+
+  test("policyGate: fixed policyCheck profile, path defaults to '.'", () => {
+    expect(policyGate()).toMatchObject({ fn: "policyGate", args: { path: "." }, profile: "policyCheck" });
+    expect(policyGate({ env: "staging" }).args).toEqual({ path: ".", env: "staging" });
+  });
+
+  test("waitForStack: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("build-step", "namespace");
+    const step = waitForStack("alb-api", { namespace: ref });
+    expect(step.args?.namespace).toBe(ref);
+  });
+
+  test("guardValidate: builds an activity step naming the guardValidate activity", () => {
+    const step = guardValidate("rules.guard");
+    expect(step.kind).toBe("activity");
+    expect(step.fn).toBe("guardValidate");
+    expect(step.args).toEqual({ rules: "rules.guard" });
+    expect(step.profile).toBe("policyCheck");
+  });
+
+  test("guardValidate: template/binary/onFinding pass through as args; id routes to the step, not args", () => {
+    const step = guardValidate("rules.guard", { template: "dist/out.json", binary: "/opt/bin/cfn-guard", onFinding: "report", id: "guard" });
+    expect(step.args).toEqual({
+      rules: "rules.guard",
+      template: "dist/out.json",
+      binary: "/opt/bin/cfn-guard",
+      onFinding: "report",
+    });
+    expect(step.id).toBe("guard");
+    expect(step.profile).toBe("policyCheck");
+  });
+
+  test("guardValidate: .out is reachable once the step is given an id", () => {
+    const step = guardValidate("rules.guard", { id: "guard" });
+    const ref: StepOutputRef = step.out.findings;
+    expect(ref.step).toBe("guard");
+    expect(ref.path).toBe("findings");
+  });
+
+  test("guardValidate: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("build-step", "outPath");
+    const step = guardValidate("rules.guard", { template: ref });
+    expect(step.args?.template).toBe(ref);
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — "environment" is not a key of ChantBuildArgs (the
+  // exact typo class chant #1288 names: `env` is the field, not
+  // `environment` — e.g. activity("lifecycleDiff", { environment: "prod" })
+  // silently ignored the whole arg before this).
+  build(".", { environment: "prod" });
+
+  // @ts-expect-error — waitForStack's intervalMs must be a number.
+  waitForStack("alb-api", { intervalMs: "5000" });
+
+  // @ts-expect-error — httpCheck's status must be a number.
+  httpCheck("https://example.com", { status: "200" });
+
+  // @ts-expect-error — policyGate has no `profile` override (fixed to
+  // policyCheck, single-attempt).
+  policyGate({ profile: "fastIdempotent" });
+
+  // @ts-expect-error — guardValidate has no `profile` override either
+  // (fixed to policyCheck, same reasoning as policyGate).
+  guardValidate("rules.guard", { profile: "fastIdempotent" });
+
+  // @ts-expect-error — onFinding only admits "report" today (#522 leaves
+  // issue/pull-request modes to a follow-up).
+  guardValidate("rules.guard", { onFinding: "issue" });
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -2,7 +2,17 @@ import { OpResource } from "./resource";
 import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
 import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receipt";
 import { receiptCheckInput } from "./receipt-store";
-import { makeOutProxy, type StepOutputRef } from "./step-output-ref";
+import { makeOutProxy, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
+import type { ChantBuildArgs } from "./activities/build";
+import type { ShellCmdArgs } from "./activities/shell";
+import type { WaitForStackArgs } from "./activities/wait";
+import type { LifecycleSnapshotArgs } from "./activities/lifecycle";
+import type { ChantTeardownArgs } from "./activities/teardown";
+import type { EnvTeardownArgs } from "./activities/env-teardown";
+import type { HttpCheckArgs } from "./activities/http-check";
+import type { PolicyGateArgs } from "./activities/policy";
+import type { GuardValidateArgs } from "./activities/guard-validate";
+import { isValidCronExpression, cronSyntaxMessage } from "./cron";
 
 /** An `activity()` result — the plain `ActivityStep` shape plus the `.out` reference sugar (#1290). */
 export interface NamedActivityStep extends ActivityStep {
@@ -18,7 +28,7 @@ export interface NamedActivityStep extends ActivityStep {
 // ── Core builders ─────────────────────────────────────────────────────────────
 
 /**
- * Declare a named, phased Temporal workflow.
+ * Declare a named, phased Op.
  *
  * @example
  * ```ts
@@ -31,8 +41,15 @@ export interface NamedActivityStep extends ActivityStep {
  *   ],
  * });
  * ```
+ *
+ * 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: OpConfig): InstanceType<typeof OpResource> {
+  if (config.schedule && !isValidCronExpression(config.schedule.cron)) {
+    throw new Error(`Op "${config.name}": ${cronSyntaxMessage(config.schedule.cron)}`);
+  }
   return new OpResource(config as unknown as Record<string, unknown>);
 }
 
@@ -85,7 +102,12 @@ export function activity(
   return step;
 }
 
-/** Insert a human gate — the workflow pauses until the named signal is received. */
+/**
+ * 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> <signalName>`
+ * writes the resolution, and the next run walks through carrying the approver.
+ */
 export function gate(
   signalName: string,
   opts?: { timeout?: string; description?: string },
@@ -113,9 +135,10 @@ export function gate(
  * would sever the step from the declaration that lint, plan, and the lexicon
  * row all key on.
  *
- * A gate authored inside `steps` pauses 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).
+ * 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).
  *
  * @example
  * ```ts
@@ -190,10 +213,25 @@ export function takeProfileAndId(
   return { args, profile, id };
 }
 
-/** Run an npm build script in the given project directory. `opts.script` selects the script (default `build`, e.g. `build:aws`); `opts.env` adds env vars. */
-export const build = (path: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("chantBuild", { path, ...args }, profile);
+/**
+ * Extra opts every typed base-activity wrapper below accepts alongside its
+ * activity's own fields: the step's `profile` override and its `id` (which
+ * routes to the step, never into args, so `.out` works — chant #1290).
+ */
+type StepOpts = { profile?: ActivityStep["profile"]; id?: string };
+
+/**
+ * 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: string,
+  opts?: WithStepRefs<Omit<ChantBuildArgs, "path">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("chantBuild", { path, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
 };
 
 /** Run `kubectl apply -f <manifest>`. Defaults to the `longInfra` profile (override via `opts.profile`). */
@@ -228,10 +266,17 @@ export const helmInstallPinned = (
   return activity("helmInstall", { name, contentDigest, ...args }, profile ?? "longInfra");
 };
 
-/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Defaults to the `k8sWait` profile (override via `opts.profile`). */
-export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("waitForStack", { name, ...args }, profile ?? "k8sWait");
+/**
+ * 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: string,
+  opts?: WithStepRefs<Omit<WaitForStackArgs, "name">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  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`). */
@@ -246,20 +291,26 @@ export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): Ac
   return activity("gitlabPipeline", { name, ...args }, profile ?? "longInfra");
 };
 
-/** Take a chant lifecycle snapshot for the given environment. */
-export const lifecycleSnapshot = (env: string): ActivityStep =>
-  activity("lifecycleSnapshot", { env });
+/**
+ * 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: string, opts?: { id?: string }): NamedActivityStep =>
+  activity("lifecycleSnapshot", { env } satisfies LifecycleSnapshotArgs, opts?.id ? { id: opts.id } : undefined);
 
 /**
  * Run an arbitrary shell command. Tag long-running commands with a `profile`
  * (e.g. `longInfra` for a multi-GB image push) so they get the right
- * start-to-close timeout under both the local executor and Temporal.
+ * start-to-close timeout on whichever runtime hosts the run.
  */
 export const shell = (
   cmd: string,
-  opts?: { env?: Record<string, string>; profile?: ActivityStep["profile"] },
-): ActivityStep =>
-  activity("shellCmd", { cmd, ...(opts?.env ? { env: opts.env } : {}) }, opts?.profile);
+  opts?: WithStepRefs<Omit<ShellCmdArgs, "cmd">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("shellCmd", { cmd, ...args }, { ...(profile ? { profile } : {}), ...(id ? { id } : {}) });
+};
 
 /**
  * Ensure a `generated-once` secret exists in the target store (#1829, epic
@@ -283,9 +334,17 @@ export const ensureSecret = (
   return activity("ensureSecret", { name, keys, ...args }, profile);
 };
 
-/** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
-export const teardown = (path: string): ActivityStep =>
-  activity("chantTeardown", { path }, "longInfra");
+/**
+ * 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: string, opts?: { id?: string }): NamedActivityStep =>
+  activity(
+    "chantTeardown",
+    { path } satisfies ChantTeardownArgs,
+    { profile: "longInfra", ...(opts?.id ? { id: opts.id } : {}) },
+  );
 
 /**
  * Tear down one environment's marker-owned resources — the durable form of
@@ -309,13 +368,16 @@ export const teardown = (path: string): ActivityStep =>
  * ]),
  * ```
  *
- * `opts` also accepts `path` (the chant project directory, default the
- * worker's cwd). Defaults to the `longInfra` profile (override via
+ * `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: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("envTeardown", { env, ...args }, profile ?? "longInfra");
+export const envTeardown = (
+  env: string,
+  opts?: WithStepRefs<Omit<EnvTeardownArgs, "env">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("envTeardown", { env, ...args }, { profile: profile ?? "longInfra", ...(id ? { id } : {}) });
 };
 
 /**
@@ -455,9 +517,12 @@ export const flociGcpDown = (opts?: Record<string, unknown>): ActivityStep => {
  * Defaults to the `fastIdempotent` profile. `opts` accepts `method`, `status`
  * (default any 2xx), `contains` (body substring), `retries`, `intervalMs`.
  */
-export const httpCheck = (url: string, opts?: Record<string, unknown>): ActivityStep => {
-  const { args, profile } = takeProfile(opts);
-  return activity("httpCheck", { url, ...args }, profile ?? "fastIdempotent");
+export const httpCheck = (
+  url: string,
+  opts?: WithStepRefs<Omit<HttpCheckArgs, "url">> & StepOpts,
+): NamedActivityStep => {
+  const { args, profile, id } = takeProfileAndId(opts as Record<string, unknown> | undefined);
+  return activity("httpCheck", { url, ...args }, { profile: profile ?? "fastIdempotent", ...(id ? { id } : {}) });
 };
 
 /**
@@ -546,7 +611,7 @@ export const gcpDelete = (manifestPath: string, opts?: Record<string, unknown>):
 // 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 temporal lexicon to run the HTTP. They live in
+// 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
@@ -806,14 +871,33 @@ export const spritesDown = (args: {
 
 /**
  * Gate an apply on organizational policy: build the project and run its
- * `lint.policies` over the resolved resources, blocking the workflow on any
- * violation. Place it before the apply phase. `env` (or `ownership.env`) lets a
+ * `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?: { env?: string; path?: string }): ActivityStep =>
-  activity(
+export const policyGate = (opts?: WithStepRefs<PolicyGateArgs> & { id?: string }): NamedActivityStep => {
+  const path = (opts?.path as PolicyGateArgs["path"] | undefined) ?? ".";
+  const env = opts?.env;
+  return activity(
     "policyGate",
-    { path: opts?.path ?? ".", ...(opts?.env ? { env: opts.env } : {}) },
-    "policyCheck",
+    { path, ...(env !== undefined ? { env } : {}) },
+    { profile: "policyCheck", ...(opts?.id ? { id: opts.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: string,
+  opts?: WithStepRefs<Omit<GuardValidateArgs, "rules">> & { id?: string },
+): NamedActivityStep => {
+  const { id, ...rest } = (opts ?? {}) as Omit<GuardValidateArgs, "rules"> & { id?: string };
+  return activity("guardValidate", { rules, ...rest }, { profile: "policyCheck", ...(id ? { id } : {}) });
+};

package/src/op/composites/apply-op.ts

@@ -0,0 +1,208 @@
+/**
+ * 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), 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.
+ *
+ * @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: { signalName: "approve-apply", description: "Approve prod apply with deletes" },
+ * });
+ * ```
+ *
+ * @see #112 — stateless-authoritative state model + live import
+ */
+
+import { Op, phase, activity, gate } from "../builders";
+import type { OpResource } from "../resource";
+import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } from "../activities/apply";
+
+export interface ApplyOpConfig {
+  /** Op name (kebab-case). */
+  name: string;
+  /** Environment — CFN stack name / ARM resource group / kube context env;
+   * a log label on `gcp` and `fly`. */
+  env: string;
+  /** Native apply mechanism. Default: "kubectl". */
+  target?: ApplyTarget;
+  /** Built manifest/template path. Default per target: `dist` (dir) for kubectl,
+   * `template.json` (file) for CloudFormation/ARM, `dist/gcp.yaml` for gcp,
+   * `dist/fly.json` for fly. Must match your build output. */
+  output?: string;
+  /** Project directory to build. Default: ".". */
+  path?: string;
+  /** Delete handling. Default: "never". */
+  delete?: DeleteMode;
+  /**
+   * Effect handling (#1834, epic #1703 decision 6). `"gated"` routes the run
+   * through the approval gate whenever the plan proposes an effect, so the Plan
+   * phase's effect-will-fire rows (#1832) are reviewed before any effect
+   * runs. A run that reaches the gate unapproved ends `gated` and is answered
+   * by `chant approve`, the same shape `delete: "gated"` has. The generic
+   * apply itself never writes a receipt regardless (#1832); only an
+   * `effect()` step does, on success, last.
+   */
+  effects?: "gated";
+  /**
+   * Approval gate before the apply. Implied when `delete: "gated"`; may also be
+   * set explicitly. Omit `signalName` to default to `approve-<name>`. The gate
+   * is resolved by `chant approve` on the ledger (#2119), which the next run
+   * reads; nothing waits in the meantime.
+   */
+  gate?: { signalName?: string; timeout?: string; description?: string };
+  /**
+   * Saga-style rollback on partial apply failure, run as an `onFailure` phase.
+   *
+   * Compensation is total or refused (#1449): it only builds when the target
+   * has a rollback to run — a mapped native one (`cloudformation`, the aws
+   * lexicon's `rollbackStack`) or an explicit `{ command }`. Asking for it
+   * (`true`, or an object without a `command`) on any other target fails at
+   * build time rather than warning at rollback time.
+   *
+   * Defaults on for a destructive apply (`delete !== "never"`) when the target
+   * has a native rollback; a destructive apply on a target without one gets no
+   * compensation phase unless a `{ command }` supplies the rollback. Pass
+   * `false` to disable.
+   */
+  compensate?: boolean | { command?: string };
+  /**
+   * kubectl target only (chant #1075). Let the server-side apply take
+   * ownership of fields another field manager already owns, instead of failing
+   * with a conflict naming them.
+   *
+   * Off unless set, and chant never turns it on by itself — a conflict means
+   * something else in the cluster believes it owns that field, and deciding
+   * otherwise is a deliberate act. Set it when chant is meant to be the
+   * authority for those fields (adopting objects a previous `kubectl apply`
+   * created is the usual case).
+   */
+  forceConflicts?: boolean;
+}
+
+export interface ApplyOpResources {
+  /** Op resource — the build→plan→[approve]→apply Op. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
+  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" as const,
+        fn: "lifecycleDiff",
+        args: { env: config.env, live: true },
+        outcomeAttribute: { name: "Drift", from: "drifted" },
+      },
+    ]),
+  ];
+
+  if (gated) {
+    phases.push(
+      phase("Approve", [
+        gate(config.gate?.signalName ?? `approve-${config.name}`, {
+          ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
+          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 only mapped one today is cloudformation's rollbackStack. 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,
+                ...(compensateCommand ? { command: compensateCommand } : {}),
+              }),
+            ]),
+          ],
+        }
+      : {}),
+  });
+
+  return { op };
+}