@intentius/chant 0.46.0 → 0.50.0

package/src/components/component-schema.test.ts

@@ -143,6 +143,38 @@ describe("Component JSON Schema", () => {
     expect(validate(invalid)).toBe(false);
   });
 
+  it("accepts an optional composites list (#1492)", () => {
+    const withComposites = {
+      name: "aws-plane",
+      archetype: "infra",
+      dependsOn: [],
+      composites: ["ArtifactBucket", "OperatorRole"],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(withComposites)).toBe(true);
+  });
+
+  it("omitting composites still validates (backward-compatible default)", () => {
+    const noComposites = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(noComposites)).toBe(true);
+  });
+
+  it("rejects an empty composites array (minItems: 1)", () => {
+    const invalid = {
+      name: "table",
+      archetype: "infra",
+      dependsOn: [],
+      composites: [],
+      deploy: [{ phase: "Apply", steps: [{ kind: "cfn-deploy", template: "t.json" }] }],
+    };
+    expect(validate(invalid)).toBe(false);
+  });
+
   it("rejects an invalid archetype value", () => {
     const invalid = {
       name: "x",

package/src/components/component.schema.json

@@ -54,6 +54,12 @@
       "description": "Optional: the live lexicon entity/resource name(s) this component owns, when they differ from `name` (#598). `chant components status --live` reconciles the release ledger against live evidence by joining on this name; omitted entirely (the default), the join falls back to `name` itself with no behavior change. A component that owns several live entities (e.g. a fan-out cluster with one stack per node) may list them all.",
       "items": { "type": "string", "minLength": 1 },
       "minItems": 1
+    },
+    "composites": {
+      "type": "array",
+      "description": "Optional: the composite kind name(s) this component's deployed resources come from, when a consumer cannot infer it from `name` (#1492). Without this, a consumer joining a composite graph to the component DAG guesses by kebab-casing each composite's kind and matching it against this component's `name`, which only holds when a component maps 1:1 to a composite named for it. Omitted entirely (the default), the naming convention stays in effect with no behavior change. A component built from several composites may list them all.",
+      "items": { "type": "string", "minLength": 1 },
+      "minItems": 1
     }
   },
   "$defs": {

package/src/components/component.test.ts

@@ -202,6 +202,27 @@ describe("projectToJson()", () => {
     expect("liveNames" in projected).toBe(false);
   });
 
+  it("projects an explicit composites list through unchanged (#1492)", () => {
+    const component: Component = {
+      name: "aws-plane",
+      dependsOn: [],
+      composites: ["ArtifactBucket", "OperatorRole"],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as { composites?: string[] };
+    expect(projected.composites).toEqual(["ArtifactBucket", "OperatorRole"]);
+  });
+
+  it("omits composites from the projection when not authored (#1492)", () => {
+    const component: Component = {
+      name: "table",
+      dependsOn: [],
+      deploy: [phase("Apply", [{ kind: "cfn-deploy" }])],
+    };
+    const projected = projectToJson(component) as Record<string, unknown>;
+    expect("composites" in projected).toBe(false);
+  });
+
   it("projects a stackOutput() wiring reference to its plain-JSON form", () => {
     const component: Component = {
       name: "svc",

package/src/components/component.ts

@@ -148,6 +148,21 @@ export interface Component {
    * name == entity join with no behavior change.
    */
   liveNames?: string[];
+  /**
+   * Optional: the composite kind name(s) this component's deployed resources
+   * come from, when a consumer joining a composite graph to the component DAG
+   * cannot infer it from `name` (#1492). Components and composites are
+   * different namespaces, the same class of mismatch `liveNames` covers for
+   * components and lexicon entities: a consumer without this field guesses by
+   * kebab-casing each composite's kind and matching it against this
+   * component's `name` (`LoomBackend` -> `loom-backend`), which only holds
+   * when a component maps 1:1 to a composite named for it. A component built
+   * from several composites (e.g. one stack containing both an ArtifactBucket
+   * and an OperatorRole composite, plus loose resources) lists them all.
+   * Omitted entirely (the common case), the naming convention stays the
+   * default and nothing changes.
+   */
+  composites?: string[];
 }
 
 /** Author a named phase. `steps` may mix capability `Step`s, `Gate`s, and nested `Phase`s (fan-out). */

package/src/components/driver.ts

@@ -313,11 +313,19 @@ export function resolveStepInput(
 
 // ── Step + phase execution ───────────────────────────────────────────────
 
-/** A step executed and its resolved input, kept so saga rollback can call the same capability's `rollback` with the same input. */
+/**
+ * A step executed and its resolved input, kept so saga rollback can call the
+ * same capability's `rollback` with the same input. `output` is the step's
+ * own `run()` result — threaded through to `rollback` (#1944) as the
+ * serializable identity channel `Capability.rollback`'s doc comment
+ * describes, alongside object identity (which already works here, since this
+ * driver runs entirely in-process — see this module's own doc comment).
+ */
 interface ExecutedStep {
   step: DriverStep;
   resolvedInput: Record<string, unknown>;
   phaseName: string;
+  output: unknown;
 }
 
 class StepFailure extends Error {
@@ -435,7 +443,7 @@ async function runPhase(
     }
     return {
       records: [record],
-      executed: record.status === "ok" ? [{ step: entry, resolvedInput, phaseName: phaseDef.phase }] : [],
+      executed: record.status === "ok" ? [{ step: entry, resolvedInput, phaseName: phaseDef.phase, output }] : [],
       failed: record.status === "fail",
     };
   };
@@ -505,7 +513,7 @@ async function rollbackExecuted(
   registry: CapabilityRegistry,
 ): Promise<DriverStepRecord[]> {
   const records: DriverStepRecord[] = [];
-  for (const { step, resolvedInput, phaseName } of [...executed].reverse()) {
+  for (const { step, resolvedInput, phaseName, output } of [...executed].reverse()) {
     const start = Date.now();
     try {
       const capability = registry.resolve(step.kind);
@@ -521,7 +529,7 @@ async function rollbackExecuted(
         });
         continue;
       }
-      await capability.rollback(ctx, resolvedInput as never);
+      await capability.rollback(ctx, resolvedInput as never, output as never);
       records.push({
         component: ctx.component,
         phase: phaseName,

package/src/components/registry.test.ts

@@ -92,9 +92,14 @@ describe("createCapabilityRegistry", () => {
     }
   });
 
-  test("family table lists exactly the agnostic starter families (cloud leaves moved to lexicons)", () => {
+  // Every AWS/k8s cloud leaf moved out to its lexicon — but the three
+  // Cloudflare Workers apply verbs (#1293, epic #1296) stay in core by
+  // deliberate decision (see ./verbs/wrangler.ts's module doc): the epic
+  // cedes the Workers plane to `wrangler` and there is no cloudflare lexicon
+  // for them to live in instead.
+  test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
     expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
-      ["build", "escapeHatch", "sbom", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+      ["build", "cloudflare", "escapeHatch", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
     );
   });
 

package/src/components/starter-plugin.ts

@@ -41,6 +41,10 @@ import {
   waitEndpointCapability,
   healthGateCapability,
   shellCapability,
+  ensureSecretCapability,
+  wranglerDeployCapability,
+  wranglerVersionsPromoteCapability,
+  r2SyncCapability,
 } from "./verbs/index";
 import { ownPackageVersion, type CapabilityPlugin } from "./capability-plugin";
 
@@ -64,7 +68,16 @@ export const STARTER_VERB_FAMILIES = {
   // cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`) are
   // contributed by the relevant lexicon (aws) — see docs/components/cloud-boundary.
   waitVerify: ["wait-cluster-healthy", "wait-endpoint", "health-gate"],
+  // generated-once secret materialization (#1829, epic #1365): read-then-write,
+  // present means done; the k8s store adapter is #1830.
+  secrets: ["ensure-secret"],
   escapeHatch: ["shell"],
+  // The Cloudflare Workers apply leaves (#1293, epic #1296) — placed in core
+  // rather than a cloudflare lexicon (decided explicitly, see ./verbs/wrangler.ts's
+  // module doc): the epic cedes the Workers plane to `wrangler` entirely, and
+  // there is no cloudflare lexicon for these three verbs to live in. Revisit
+  // if/when the zone-plane lexicon (#1294) lands.
+  cloudflare: ["wrangler-deploy", "wrangler-versions-promote", "r2-sync"],
 } as const;
 
 /**
@@ -88,7 +101,11 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
     waitClusterHealthyCapability,
     waitEndpointCapability,
     healthGateCapability,
+    ensureSecretCapability,
     shellCapability,
+    wranglerDeployCapability,
+    wranglerVersionsPromoteCapability,
+    r2SyncCapability,
   ] as unknown as Array<Capability<never, unknown>>;
 }
 

package/src/components/verbs/ensure-secret.test.ts

@@ -0,0 +1,130 @@
+/**
+ * `ensure-secret` capability surface tests (#1829, epic #1365 decision 3):
+ * the verb is the same engine as the `ensureSecret(...)` op builder, its
+ * rollback disposition is `needs-opt-out`, and COMP003 fires on a component
+ * that uses it without acknowledging the compensation gap — through the same
+ * registry-derived policy map `chant lint` builds, not a hard-coded list.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { DeployContext } from "../capability";
+import { CapabilityNotImplementedError, type RollbackPolicy } from "../capability";
+import { createCapabilityRegistry } from "../registry";
+import { createEnsureSecretCapability, ensureSecretCapability } from "./ensure-secret";
+import {
+  SecretMaterial,
+  SecretContractMismatchError,
+  consumeSecretMaterial,
+  type SecretMaterialGenerator,
+  type SecretStoreAdapter,
+} from "../../secret-materialization";
+import { loadComponentChecks } from "../../lint/rules/comp";
+
+const ctx: DeployContext = { env: "dev", component: "fountain" };
+
+function fakeStore(seed?: Record<string, Record<string, string>>) {
+  const secrets = new Map<string, Record<string, string>>(Object.entries(seed ?? {}));
+  const adapter: SecretStoreAdapter = {
+    exists: vi.fn(async (name: string) => secrets.has(name)),
+    describe: vi.fn(async (name: string) => ({ keys: Object.keys(secrets.get(name) ?? {}) })),
+    create: vi.fn(async (name: string, keys: readonly string[], generate: SecretMaterialGenerator) => {
+      const data: Record<string, string> = {};
+      for (const key of keys) data[key] = consumeSecretMaterial(await generate(key));
+      secrets.set(name, data);
+    }),
+  };
+  return { adapter, secrets };
+}
+
+describe("ensure-secret capability", () => {
+  it("creates an absent secret, then treats present-and-matching as done (create fires once across reruns)", async () => {
+    const { adapter } = fakeStore();
+    const capability = createEnsureSecretCapability({
+      store: adapter,
+      generator: (key) => SecretMaterial.mint(`v:${key}`),
+    });
+    const first = await capability.run(ctx, { name: "app-secret", keys: ["token"] });
+    const second = await capability.run(ctx, { name: "app-secret", keys: ["token"] });
+    expect(first.outcome).toBe("created");
+    expect(second.outcome).toBe("present");
+    expect(adapter.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("propagates the loud mismatch from the shared engine", async () => {
+    const { adapter } = fakeStore({ "app-secret": { other: "x" } });
+    const capability = createEnsureSecretCapability({ store: adapter });
+    await expect(capability.run(ctx, { name: "app-secret", keys: ["token"] })).rejects.toThrowError(
+      SecretContractMismatchError,
+    );
+  });
+
+  it("output carries names only — no field of the outcome can hold material", async () => {
+    const { adapter } = fakeStore();
+    const capability = createEnsureSecretCapability({
+      store: adapter,
+      generator: (key) => SecretMaterial.mint(`v:${key}`),
+    });
+    const outcome = await capability.run(ctx, { name: "app-secret", keys: ["token"] });
+    expect(outcome).toEqual({ outcome: "created", name: "app-secret", keys: ["token"] });
+    expect(JSON.stringify(outcome)).not.toContain("v:token");
+  });
+
+  it("is registered in the starter set as a typed stub until a provider row (#1830) wires an adapter", async () => {
+    const registry = createCapabilityRegistry();
+    const starter = registry.resolve("ensure-secret");
+    expect(starter.rollbackPolicy).toBe("needs-opt-out");
+    await expect(starter.run(ctx as never, {} as never)).rejects.toThrowError(CapabilityNotImplementedError);
+  });
+});
+
+describe("COMP003 over ensure-secret", () => {
+  /** The same derivation chant lint's resolveRegistryContext performs. */
+  function registryRollbackPolicies(): Map<string, RollbackPolicy> {
+    const registry = createCapabilityRegistry();
+    const policies = new Map<string, RollbackPolicy>();
+    for (const kind of registry.kinds()) {
+      const capability = registry.resolve(kind);
+      policies.set(kind, capability.rollbackPolicy ?? (capability.rollback ? "native" : "none-by-design"));
+    }
+    return policies;
+  }
+
+  const [comp003] = loadComponentChecks().filter((c) => c.id === "COMP003");
+
+  function checkComponent(step: Record<string, unknown>) {
+    const checkCtx = {
+      rollbackPolicies: registryRollbackPolicies(),
+      components: new Map([
+        [
+          "fountain",
+          {
+            component: {
+              name: "fountain",
+              dependsOn: [],
+              deploy: [{ phase: "Secrets", steps: [step] }],
+            },
+            filePath: "fountain.component.ts",
+          },
+        ],
+      ]),
+    };
+    return comp003.check(checkCtx as never);
+  }
+
+  it("flags a bare ensure-secret step — minting has no safe undo, so the gap needs an explicit opt-out", () => {
+    const diagnostics = checkComponent({ kind: "ensure-secret", name: "master-key", keys: ["MASTER_SECRETS_KEY"] });
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].checkId).toBe("COMP003");
+    expect(diagnostics[0].message).toContain("ensure-secret");
+  });
+
+  it("accepts the step once the component acknowledges the gap via noRollback", () => {
+    const diagnostics = checkComponent({
+      kind: "ensure-secret",
+      name: "master-key",
+      keys: ["MASTER_SECRETS_KEY"],
+      noRollback: "generated-once: un-creating would destroy the only copy of the material",
+    });
+    expect(diagnostics).toHaveLength(0);
+  });
+});

package/src/components/verbs/ensure-secret.ts

@@ -0,0 +1,79 @@
+/**
+ * secrets family — `ensure-secret` (#1829, epic #1365 decision 3). The
+ * capability surface over the one generated-once materialization engine
+ * (../../secret-materialization.ts); the op step builder `ensureSecret(...)`
+ * (../../op/builders.ts) is the other surface over the same engine.
+ *
+ * Contract (read-then-write): present means done. The verb never mints over
+ * an existing value and never rotates implicitly; an existing secret that
+ * does not match the declared key-set/metadata stops the apply with a
+ * `SecretContractMismatchError` naming key names and metadata keys — never
+ * values. There is no safe undo for minting a secret others may already have
+ * consumed, and un-creating it would destroy the only copy of the material —
+ * so `rollbackPolicy: "needs-opt-out"`: COMP003 requires a component using
+ * this verb to acknowledge the compensation gap explicitly.
+ *
+ * The store adapter is per-provider (#1830 is the k8s row). Core registers a
+ * typed stub; a provider builds the real capability with
+ * {@link createEnsureSecretCapability}.
+ */
+
+import type { Capability } from "../capability";
+import { CapabilityNotImplementedError } from "../capability";
+import {
+  ensureSecretMaterialization,
+  defaultSecretMaterialGenerator,
+  type EnsureSecretOutcome,
+  type SecretMaterialGenerator,
+  type SecretStoreAdapter,
+} from "../../secret-materialization";
+
+export interface EnsureSecretInput {
+  /** The secret's name as the store knows it. */
+  name: string;
+  /** The declared key-set. Creation mints one value per key; verification compares names only. */
+  keys: string[];
+  /** Declared metadata an existing secret must carry. Mismatches are reported by KEY. */
+  metadata?: Record<string, string>;
+}
+
+/** Names only — no field of the output can carry material. */
+export type EnsureSecretOutput = EnsureSecretOutcome;
+
+/**
+ * Build the real `ensure-secret` capability over a provider's
+ * {@link SecretStoreAdapter}. The generator seam defaults to 32 CSPRNG bytes
+ * per key; the material it mints flows straight through the adapter to the
+ * store and is never returned, logged, or retained (see
+ * ../../secret-materialization.ts).
+ */
+export function createEnsureSecretCapability(deps: {
+  store: SecretStoreAdapter;
+  generator?: SecretMaterialGenerator;
+}): Capability<EnsureSecretInput, EnsureSecretOutput> {
+  return {
+    kind: "ensure-secret",
+    rollbackPolicy: "needs-opt-out",
+    async run(_ctx, input) {
+      return ensureSecretMaterialization(
+        deps.store,
+        { name: input.name, keys: input.keys, metadata: input.metadata },
+        deps.generator ?? defaultSecretMaterialGenerator,
+      );
+    },
+  };
+}
+
+/**
+ * The starter-set registration: fully typed, correct `rollbackPolicy` for
+ * COMP003, but no store adapter — running it throws
+ * `CapabilityNotImplementedError` until a provider row (#1830, k8s) wires a
+ * real adapter via {@link createEnsureSecretCapability}.
+ */
+export const ensureSecretCapability: Capability<EnsureSecretInput, EnsureSecretOutput> = {
+  kind: "ensure-secret",
+  rollbackPolicy: "needs-opt-out",
+  async run(): Promise<EnsureSecretOutput> {
+    throw new CapabilityNotImplementedError("ensure-secret");
+  },
+};

package/src/components/verbs/index.ts

@@ -26,6 +26,15 @@
  * `ProvenanceLink` material. `verify` (#622, ./verify.ts) is the matching
  * deploy-time gate — `cosign verify`/`verify-attestation` against a
  * configured identity policy, mirroring ../../lint/policy.ts's `policyGate`.
+ * `wrangler-deploy`/`wrangler-versions-promote` (#1293, epic #1296,
+ * ./wrangler.ts) and `r2-sync` (#1293, ./r2-sync.ts) are the Cloudflare
+ * Workers apply leaves — real implementations over the same injectable
+ * `ProcessRunner` `sign` uses, shelling to `wrangler`/`rclone` rather than an
+ * AWS-shaped SDK client. `run-agent` (#1941, epic #1564 phase 1, ./run-agent.ts)
+ * is the typed schema + registry entry for a bounded, attested agent-turn
+ * capability over a fly Sprite — a typed stub for now (`run`/`rollback`
+ * reject with `CapabilityNotImplementedError`), `rollbackPolicy: "native"`
+ * declared up front; the real sprite-lifecycle implementation is #1942.
  */
 
 export * from "./build-archive";
@@ -39,11 +48,15 @@ export * from "./component-bom";
 export * from "./reproducibility";
 export * from "./sign";
 export * from "./verify";
+export * from "./run-agent";
+export * from "./wrangler";
+export * from "./r2-sync";
 export * from "./vuln-scan";
 export * from "./vex";
 export * from "./license-policy";
 export * from "./vuln-gate";
 export * from "./wait-verify";
 export * from "./shell";
+export * from "./ensure-secret";
 export * from "./cloud-executor";
 export * from "./process-runner";

package/src/components/verbs/r2-sync.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests `r2-sync` (#1293, epic #1296, ./r2-sync.ts) against a
+ * `MockProcessRunner` — no live `rclone`, no network call, ever. Asserts the
+ * `r2://` destination shape mirrors `s3-sync`'s `s3://` shape, the
+ * copy-vs-sync dispatch on `delete`, the uploaded/deleted count parsing, and
+ * the `needs-opt-out` rollback disposition `s3-sync` also carries.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  buildR2SyncArgs,
+  createR2SyncCapability,
+  parseRcloneStats,
+  R2SyncInvalidDestinationError,
+  toRcloneDest,
+} from "./r2-sync";
+import { ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "prod", component: "assets" };
+
+describe("toRcloneDest", () => {
+  it("translates r2://bucket/prefix to the default 'r2' rclone remote", () => {
+    expect(toRcloneDest("r2://my-bucket/assets")).toBe("r2:my-bucket/assets");
+  });
+
+  it("translates a bare bucket with no prefix", () => {
+    expect(toRcloneDest("r2://my-bucket")).toBe("r2:my-bucket");
+  });
+
+  it("honours an explicit remote name override", () => {
+    expect(toRcloneDest("r2://my-bucket/assets", "cf-r2")).toBe("cf-r2:my-bucket/assets");
+  });
+
+  it("throws R2SyncInvalidDestinationError for a non-r2:// URI (e.g. an s3:// one passed by mistake)", () => {
+    expect(() => toRcloneDest("s3://my-bucket/assets")).toThrow(R2SyncInvalidDestinationError);
+  });
+});
+
+describe("buildR2SyncArgs", () => {
+  it("uses 'rclone copy' by default — never deletes destination-only keys, matching s3-sync's default", () => {
+    const cmd = buildR2SyncArgs({ from: "dist/assets", to: "r2://my-bucket/assets" });
+    expect(cmd).toBe(`rclone copy 'dist/assets' 'r2:my-bucket/assets' -v`);
+  });
+
+  it("uses 'rclone sync' when delete: true — matching s3-sync's opt-in delete", () => {
+    const cmd = buildR2SyncArgs({ from: "dist/assets", to: "r2://my-bucket/assets", delete: true });
+    expect(cmd).toBe(`rclone sync 'dist/assets' 'r2:my-bucket/assets' -v`);
+  });
+});
+
+describe("parseRcloneStats", () => {
+  it("counts new and replaced uploads together as 'uploaded'", () => {
+    const stdout = [
+      "2026/08/24 10:00:00 INFO  : a.txt: Copied (new)",
+      "2026/08/24 10:00:00 INFO  : b.txt: Copied (replaced existing)",
+      "2026/08/24 10:00:00 INFO  : c.txt: Copied (new)",
+    ].join("\n");
+    expect(parseRcloneStats(stdout)).toEqual({ uploaded: 3, deleted: 0 });
+  });
+
+  it("counts deletions separately", () => {
+    const stdout = [
+      "2026/08/24 10:00:00 INFO  : a.txt: Copied (new)",
+      "2026/08/24 10:00:00 INFO  : stale.txt: Deleted",
+    ].join("\n");
+    expect(parseRcloneStats(stdout)).toEqual({ uploaded: 1, deleted: 1 });
+  });
+
+  it("returns zeros for a no-op sync", () => {
+    expect(parseRcloneStats("2026/08/24 10:00:00 INFO  : There was nothing to transfer\n")).toEqual({
+      uploaded: 0,
+      deleted: 0,
+    });
+  });
+});
+
+describe("r2-sync capability", () => {
+  it("round-trips a directory upload and reports the object count", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "rclone copy": "2026/08/24 10:00:00 INFO  : a.txt: Copied (new)\n2026/08/24 10:00:00 INFO  : b.txt: Copied (new)\n",
+      },
+    });
+    const capability = createR2SyncCapability(mock.runner);
+
+    const output = await capability.run(ctx, { from: "dist/assets", to: "r2://my-bucket/assets" });
+
+    expect(output).toEqual({ uploaded: 2, deleted: 0 });
+    expect(mock.calls.some((c) => c.command === `rclone copy 'dist/assets' 'r2:my-bucket/assets' -v`)).toBe(true);
+  });
+
+  it("throws ToolNotAvailableError when rclone is absent, rather than silently skipping the sync", async () => {
+    const mock = createMockProcessRunner({ tools: { rclone: false } });
+    const capability = createR2SyncCapability(mock.runner);
+
+    await expect(capability.run(ctx, { from: "dist/assets", to: "r2://my-bucket/assets" })).rejects.toBeInstanceOf(
+      ToolNotAvailableError,
+    );
+  });
+
+  it("declares rollbackPolicy: needs-opt-out — a mutating, destructive-capable sync with no native undo, same as s3-sync", () => {
+    const capability = createR2SyncCapability(createMockProcessRunner().runner);
+    expect(capability.rollbackPolicy).toBe("needs-opt-out");
+    expect(capability.rollback).toBeUndefined();
+  });
+});