@intentius/chant-lexicon-aws 0.13.1 → 0.15.0

package/src/components/host-delivery.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { createCodeDeployCapability, createCopyToHostCapability, createRemoteExecCapability } from "./host-delivery";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+describe("code-deploy (#557 — AWS CodeDeploy)", () => {
+  it("creates a deployment and waits for a terminal status", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createCodeDeployCapability(mock.executor);
+
+    const output = await capability.run(
+      { env: "dev", component: "neo4j-cluster" },
+      { application: "neo4j", deploymentGroup: "neo4j-0", revision: { type: "s3", uri: "s3://bucket/neo4j.zip" } },
+    );
+
+    expect(output.status).toBe("Succeeded");
+    expect(mock.calls.map((c) => c.method)).toEqual(["createDeployment", "waitForDeployment"]);
+  });
+
+  it("accepts a bare wired string as the revision (matches the Neo4j pilot's `revision: \"@Seed.templateUri\"`)", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createCodeDeployCapability(mock.executor);
+
+    await capability.run(
+      { env: "dev", component: "neo4j-cluster" },
+      { instance: 1, revision: "s3://bucket/neo4j-seed-uri.zip" },
+    );
+
+    const createCall = mock.calls.find((c) => c.method === "createDeployment")!;
+    expect(createCall.args).toMatchObject({
+      application: "neo4j-cluster",
+      deploymentGroup: "neo4j-cluster-1",
+      revision: { type: "s3", uri: "s3://bucket/neo4j-seed-uri.zip" },
+    });
+  });
+
+  it("derives application from ctx.component and deploymentGroup from instance when both are omitted", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createCodeDeployCapability(mock.executor);
+    await capability.run({ env: "dev", component: "neo4j-cluster" }, { instance: 0, revision: "@Seed.templateUri" });
+    const createCall = mock.calls.find((c) => c.method === "createDeployment")!;
+    expect(createCall.args).toMatchObject({ application: "neo4j-cluster", deploymentGroup: "neo4j-cluster-0" });
+  });
+
+  it("throws when the deployment ends in a non-Succeeded terminal status", async () => {
+    const mock = createMockCloudExecutor({ deployments: {} });
+    const capability = createCodeDeployCapability(mock.executor);
+    // Script the deployment id this run will create to fail.
+    const runPromise = capability.run(
+      { env: "dev", component: "neo4j-cluster" },
+      { instance: 2, revision: "@Seed.templateUri" },
+    );
+    // The mock assigns deployment ids sequentially; set its status to Failed before awaiting.
+    mock.setDeployment("mock-deployment-1", { terminalStatus: "Failed" });
+    await expect(runPromise).rejects.toThrow(/ended Failed/);
+  });
+
+  it("rollback stops and rolls back the most recent deployment for the same application/deploymentGroup", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createCodeDeployCapability(mock.executor);
+    const input = { instance: 1, revision: "@Seed.templateUri" };
+    await capability.run({ env: "dev", component: "neo4j-cluster" }, input);
+    await capability.rollback!({ env: "dev", component: "neo4j-cluster" }, input);
+    expect(mock.calls.map((c) => c.method)).toEqual(["createDeployment", "waitForDeployment", "stopAndRollback"]);
+  });
+
+  it("rollback is a no-op when this capability instance never deployed to that target", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createCodeDeployCapability(mock.executor);
+    await capability.rollback!({ env: "dev", component: "neo4j-cluster" }, { instance: 9, revision: "x" });
+    expect(mock.calls).toEqual([]);
+  });
+});
+
+const hostCtx = { env: "dev", component: "svc" };
+
+describe("remote-exec (#557 — SSM Run Command)", () => {
+  it("runs the command on the host and returns its stdout + exit code", async () => {
+    const mock = createMockCloudExecutor({ hostExecStdout: "hello\n" });
+    const out = await createRemoteExecCapability(mock.executor).run(hostCtx, { host: "i-123", command: "echo hello" });
+    expect(out).toEqual({ stdout: "hello\n", exitCode: 0 });
+    expect(mock.calls).toEqual([{ client: "host", method: "exec", args: { host: "i-123", command: "echo hello", cwd: undefined } }]);
+  });
+
+  it("passes cwd through", async () => {
+    const mock = createMockCloudExecutor();
+    await createRemoteExecCapability(mock.executor).run(hostCtx, { host: "i-1", command: "ls", cwd: "/app" });
+    expect(mock.calls[0]!.args).toMatchObject({ cwd: "/app" });
+  });
+
+  it("rejects the not-yet-supported ssh transport with a clear message", async () => {
+    const mock = createMockCloudExecutor();
+    await expect(
+      createRemoteExecCapability(mock.executor).run(hostCtx, { host: "h", command: "x", via: "ssh" }),
+    ).rejects.toThrow(/ssh transport not yet supported/);
+  });
+
+  it("declares no rollback", () => {
+    expect(createRemoteExecCapability(createMockCloudExecutor().executor).rollback).toBeUndefined();
+  });
+});
+
+describe("copy-to-host (#557 — SSM Run Command)", () => {
+  it("has the host pull the file from S3 and reports the byte count", async () => {
+    const mock = createMockCloudExecutor({ hostExecStdout: "2048\n" });
+    const out = await createCopyToHostCapability(mock.executor).run(hostCtx, {
+      from: "s3://assets/app.jar",
+      host: "i-9",
+      to: "/opt/app.jar",
+    });
+    expect(out).toEqual({ bytesCopied: 2048 });
+    const call = mock.calls.find((c) => c.method === "exec")!;
+    expect((call.args as { command: string }).command).toContain("aws s3 cp s3://assets/app.jar /opt/app.jar");
+    expect((call.args as { command: string }).command).toContain("stat -c %s /opt/app.jar");
+  });
+
+  it("reports 0 bytes when the host returns no size", async () => {
+    const mock = createMockCloudExecutor({ hostExecStdout: "" });
+    const out = await createCopyToHostCapability(mock.executor).run(hostCtx, { from: "s3://b/x", host: "i", to: "/x" });
+    expect(out).toEqual({ bytesCopied: 0 });
+  });
+});

package/src/components/host-delivery.ts

@@ -0,0 +1,193 @@
+/**
+ * host / code delivery family — run against a mutable host.
+ *
+ * `code-deploy` (AWS CodeDeploy) is the managed, nearly AWS-only leaf: create
+ * a deployment of a revision (S3/GitHub) to a deployment group, appspec-driven
+ * lifecycle hooks (BeforeInstall/AfterInstall/ApplicationStart/ValidateService),
+ * in-place or blue/green, native automatic rollback, wait for terminal status.
+ * Pairs with `publish-artifact` — the revision is the published S3 bundle
+ * (`@publish.uri`).
+ *
+ * `copy-to-host` / `remote-exec` (SSM Run Command or SSH) are the portable,
+ * lower-level generic verbs for host bootstrap, on-host migrations, and
+ * single-host compose where CodeDeploy is not used or not available
+ * (no clean Azure/GCP peer — see docs/components/cloud-boundary).
+ *
+ * `code-deploy` is a real implementation (#557, epic #551) over the
+ * injectable `CloudExecutor` (./cloud-executor.ts) — the capability the
+ * Neo4j fan-out pilot uses once per instance. `copy-to-host` and `remote-exec`
+ * are also real, over the executor's `host.exec` (SSM Run Command, waited to
+ * completion); the SSH transport is not yet implemented.
+ */
+
+import type { Capability } from "@intentius/chant/components/capability";
+import { defaultCloudExecutor, type CloudExecutor } from "./cloud-executor";
+
+// ── code-deploy (AWS CodeDeploy) ─────────────────────────────────────────────
+
+export interface CodeDeployInput {
+  /** CodeDeploy application name. Default: derived from `ctx.component` when omitted (per-instance fan-out steps, e.g. the Neo4j pilot, don't repeat it per node). */
+  application?: string;
+  /** CodeDeploy deployment group name. Default: `<application>-<instance>` when `instance` is given, else `<application>`. */
+  deploymentGroup?: string;
+  /**
+   * Revision location — an S3 bundle (typically `"@publish.uri"`), a GitHub
+   * reference, or a bare wired string (e.g. `"@Seed.templateUri"`, as the
+   * Neo4j pilot passes) treated as an S3 URI shorthand.
+   */
+  revision: { type: "s3"; uri: string } | { type: "github"; repository: string; commitId: string } | string;
+  /** Deployment strategy. Default: "in-place". */
+  strategy?: "in-place" | "blue-green";
+  /** Cluster-relative instance index, for a per-instance fan-out step (e.g. one Neo4j node). Folded into the deployment group name when `deploymentGroup` is not given explicitly. */
+  instance?: number;
+}
+
+export interface CodeDeployOutput {
+  /** CodeDeploy deployment id, for polling terminal status. */
+  deploymentId: string;
+  /** Terminal deployment status once complete (`Succeeded`, `Failed`, `Stopped`). */
+  status: string;
+}
+
+/** Normalize `CodeDeployInput.revision` to the strict `{type, uri|repository+commitId}` shape the executor takes. */
+function normalizeRevision(revision: CodeDeployInput["revision"]): CodeDeployCreateArgsRevision {
+  return typeof revision === "string" ? { type: "s3", uri: revision } : revision;
+}
+
+type CodeDeployCreateArgsRevision =
+  | { type: "s3"; uri: string }
+  | { type: "github"; repository: string; commitId: string };
+
+/** Resolve the application/deployment-group names, defaulting from `ctx.component`/`instance` when the input omits them (matches the Neo4j pilot's per-instance shorthand). */
+function resolveTargets(
+  ctx: { component: string },
+  input: CodeDeployInput,
+): { application: string; deploymentGroup: string } {
+  const application = input.application ?? ctx.component;
+  const deploymentGroup =
+    input.deploymentGroup ?? (input.instance !== undefined ? `${application}-${input.instance}` : application);
+  return { application, deploymentGroup };
+}
+
+/**
+ * Deploy a revision to a host (fleet) via AWS CodeDeploy: create the
+ * deployment, then wait for a terminal status. Rollback re-invokes
+ * `stopAndRollback` against the deployment id this step created (captured in
+ * a closure-scoped map keyed by application/deploymentGroup, since the
+ * driver's saga rollback calls `rollback(ctx, sameInput)` rather than passing
+ * `run`'s output) — riding CodeDeploy's own native automatic rollback to the
+ * last known-good revision rather than a chant-scripted compensation, the
+ * "auto" rollback style the Neo4j pilot's docs comment contrasts with the
+ * ALB/ECS pilot's component-declared one.
+ */
+export function createCodeDeployCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<CodeDeployInput, CodeDeployOutput> {
+  const lastDeploymentByTarget = new Map<string, string>();
+
+  return {
+    kind: "code-deploy",
+    async run(ctx, input) {
+      const { application, deploymentGroup } = resolveTargets(ctx, input);
+      const { deploymentId } = await executor.codeDeploy.createDeployment({
+        application,
+        deploymentGroup,
+        revision: normalizeRevision(input.revision),
+        strategy: input.strategy,
+      });
+      lastDeploymentByTarget.set(`${application}/${deploymentGroup}`, deploymentId);
+      const { status } = await executor.codeDeploy.waitForDeployment(deploymentId);
+      if (status !== "Succeeded") {
+        throw new Error(`code-deploy "${application}/${deploymentGroup}": deployment ${deploymentId} ended ${status}`);
+      }
+      return { deploymentId, status };
+    },
+    async rollback(ctx, input) {
+      const { application, deploymentGroup } = resolveTargets(ctx, input);
+      const deploymentId = lastDeploymentByTarget.get(`${application}/${deploymentGroup}`);
+      if (!deploymentId) return; // nothing this capability instance deployed for this target — nothing to unwind.
+      await executor.codeDeploy.stopAndRollback(deploymentId);
+    },
+  };
+}
+
+/** Default `code-deploy` capability, backed by the real `CloudExecutor`. */
+export const codeDeployCapability: Capability<CodeDeployInput, CodeDeployOutput> = createCodeDeployCapability();
+
+// ── copy-to-host ─────────────────────────────────────────────────────────────
+
+export interface CopyToHostInput {
+  /** Source path (local, or archive-relative reference). */
+  from: string;
+  /** Target host (SSM instance id, hostname, or host group). */
+  host: string;
+  /** Destination path on the host. */
+  to: string;
+}
+
+export interface CopyToHostOutput {
+  /** Number of bytes copied. */
+  bytesCopied: number;
+}
+
+/**
+ * Copy a file to a host via SSM Run Command: the host pulls `from` (an S3 URI)
+ * to `to` with `aws s3 cp`, then `stat`s the result for the byte count. `from`
+ * must be reachable from the host (typically a prior `publish-artifact`'s URI).
+ */
+export function createCopyToHostCapability(executor: CloudExecutor = defaultCloudExecutor()): Capability<CopyToHostInput, CopyToHostOutput> {
+  return {
+    kind: "copy-to-host",
+    rollbackPolicy: "needs-opt-out",
+    async run(_ctx, input) {
+      const { stdout } = await executor.host.exec({
+        host: input.host,
+        command: `aws s3 cp ${input.from} ${input.to} >/dev/null 2>&1 && stat -c %s ${input.to}`,
+      });
+      return { bytesCopied: Number.parseInt(stdout.trim(), 10) || 0 };
+    },
+  };
+}
+
+/** Default `copy-to-host` capability, backed by the real `CloudExecutor`. */
+export const copyToHostCapability: Capability<CopyToHostInput, CopyToHostOutput> = createCopyToHostCapability();
+
+// ── remote-exec ──────────────────────────────────────────────────────────────
+
+export interface RemoteExecInput {
+  /** Target host (SSM instance id, hostname, or host group). */
+  host: string;
+  /** Command to run on the host. */
+  command: string;
+  /** Working directory on the host. */
+  cwd?: string;
+  /** Transport. Default: "ssm". */
+  via?: "ssm" | "ssh";
+}
+
+export interface RemoteExecOutput {
+  /** Process exit code. */
+  exitCode: number;
+  /** Captured stdout. */
+  stdout: string;
+}
+
+/**
+ * Run a command on a remote host via SSM Run Command, waiting for it to finish
+ * and returning its stdout + exit code. SSH transport is not yet supported.
+ */
+export function createRemoteExecCapability(executor: CloudExecutor = defaultCloudExecutor()): Capability<RemoteExecInput, RemoteExecOutput> {
+  return {
+    kind: "remote-exec",
+    rollbackPolicy: "needs-opt-out",
+    async run(_ctx, input) {
+      if (input.via === "ssh") {
+        throw new Error(`remote-exec: ssh transport not yet supported for host "${input.host}" — use the default ssm transport`);
+      }
+      return executor.host.exec({ host: input.host, command: input.command, cwd: input.cwd });
+    },
+  };
+}
+
+/** Default `remote-exec` capability, backed by the real `CloudExecutor`. */
+export const remoteExecCapability: Capability<RemoteExecInput, RemoteExecOutput> = createRemoteExecCapability();

package/src/components/index.ts

@@ -0,0 +1,19 @@
+/**
+ * The aws lexicon's component/release surface: the AWS-leaf capabilities, their
+ * typed step-builders, the injectable aws `CloudExecutor`, and the
+ * `awsCapabilityPlugin` core loads when a project declares `lexicons: ["aws"]`.
+ * Component authors import the AWS verbs' builders from here
+ * (`@intentius/chant-lexicon-aws/components`), the way agnostic verbs come from
+ * `@intentius/chant/components`.
+ */
+
+export { awsCapabilityPlugin, AWS_VERB_FAMILIES } from "./capability-plugin";
+export * from "./builders";
+export * from "./config-bom";
+export * from "./apply";
+export * from "./job-submission";
+export * from "./host-delivery";
+export * from "./safety";
+export * from "./wait-aws";
+export * from "./publish";
+export * from "./cloud-executor";

package/src/components/job-submission.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { createEmrStartJobRunCapability, createEmrSubmitStepCapability } from "./job-submission";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+
+describe("emr-start-job-run (#561)", () => {
+  it("starts a job run against the resolved artifact reference and returns the run id", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createEmrStartJobRunCapability(mock.executor);
+
+    const output = await capability.run(
+      { env: "dev", component: "emr-job" },
+      { clusterOrApplicationId: "app-123", jar: "s3://jar-bucket/jar-lib.jar", args: ["--input", "s3://data/in"] },
+    );
+
+    expect(output.runId).toBe("mock-job-run-1");
+    const call = mock.calls.find((c) => c.client === "emr" && c.method === "startJobRun")!;
+    expect(call.args).toMatchObject({
+      clusterOrApplicationId: "app-123",
+      jar: "s3://jar-bucket/jar-lib.jar",
+      args: ["--input", "s3://data/in"],
+    });
+  });
+
+  it("falls back to ctx.vars.emrApplicationId when clusterOrApplicationId is omitted (matches the emr-job pilot's bare step, which wires the artifact reference but not a literal application id)", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createEmrStartJobRunCapability(mock.executor);
+
+    await capability.run(
+      { env: "dev", component: "emr-job", vars: { emrApplicationId: "app-from-env" } },
+      { jar: "s3://jar-bucket/jar-lib.jar" },
+    );
+
+    const call = mock.calls.find((c) => c.client === "emr" && c.method === "startJobRun")!;
+    expect(call.args).toMatchObject({ clusterOrApplicationId: "app-from-env" });
+  });
+
+  it("falls back to ctx.component as a last resort when neither clusterOrApplicationId nor ctx.vars.emrApplicationId is given", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createEmrStartJobRunCapability(mock.executor);
+
+    await capability.run({ env: "dev", component: "emr-job" }, { jar: "s3://jar-bucket/jar-lib.jar" });
+
+    const call = mock.calls.find((c) => c.client === "emr" && c.method === "startJobRun")!;
+    expect(call.args).toMatchObject({ clusterOrApplicationId: "emr-job" });
+  });
+
+  it("never resolves the @<component>.publish.uri reference itself — it receives whatever the driver already resolved `jar` to", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createEmrStartJobRunCapability(mock.executor);
+
+    // Passing the raw reference string through unresolved documents that this
+    // capability is not where cross-component wiring happens — ../driver.ts's
+    // resolveWiring does that before `run` is ever called.
+    await capability.run({ env: "dev", component: "emr-job" }, { jar: "@jar-lib.publish.uri" });
+
+    const call = mock.calls.find((c) => c.client === "emr" && c.method === "startJobRun")!;
+    expect(call.args).toMatchObject({ jar: "@jar-lib.publish.uri" });
+  });
+
+  it("declares no rollback — starting a job run has nothing to compensate", () => {
+    const capability = createEmrStartJobRunCapability(createMockCloudExecutor().executor);
+    expect(capability.rollback).toBeUndefined();
+  });
+});
+
+describe("emr-submit-step", () => {
+  it("submits a step to the cluster and returns the step id", async () => {
+    const mock = createMockCloudExecutor();
+    const out = await createEmrSubmitStepCapability(mock.executor).run(
+      { env: "dev", component: "emr-job" },
+      { clusterId: "j-123", name: "nightly-rollup", jar: "s3://jar-bucket/jar-lib.jar", args: ["--date", "2026-07-04"] },
+    );
+    expect(out).toEqual({ stepId: "s-MOCK0001" });
+    const call = mock.calls.find((c) => c.client === "emr" && c.method === "addStep")!;
+    expect(call.args).toEqual({
+      clusterId: "j-123",
+      name: "nightly-rollup",
+      jar: "s3://jar-bucket/jar-lib.jar",
+      args: ["--date", "2026-07-04"],
+      actionOnFailure: undefined,
+    });
+  });
+
+  it("passes an unresolved artifact reference straight through (the graph resolves it before run)", async () => {
+    const mock = createMockCloudExecutor();
+    await createEmrSubmitStepCapability(mock.executor).run(
+      { env: "dev", component: "emr-job" },
+      { clusterId: "j-123", name: "step", jar: "@jar-lib.publish.uri", actionOnFailure: "CANCEL_AND_WAIT" },
+    );
+    const call = mock.calls.find((c) => c.method === "addStep")!;
+    expect(call.args).toMatchObject({ jar: "@jar-lib.publish.uri", actionOnFailure: "CANCEL_AND_WAIT" });
+  });
+
+  it("declares no rollback — a submitted step has nothing to compensate", () => {
+    expect(createEmrSubmitStepCapability(createMockCloudExecutor().executor).rollback).toBeUndefined();
+  });
+});

package/src/components/job-submission.ts

@@ -0,0 +1,138 @@
+/**
+ * job submission family — point a running compute service at an artifact.
+ * Cloud-shaped (EMR here; the same shape reuses for Glue / Batch / Step
+ * Functions / SageMaker per docs/components/cloud-boundary). Typically
+ * consumes a producer component's published artifact, e.g.
+ * `jar: "@jar-lib.publish.uri"`.
+ *
+ * `emr-start-job-run` is a real implementation (#561, epic #551) — just
+ * enough against the injectable `CloudExecutor` (./cloud-executor.ts) to run
+ * the JAR-producer -> EMR-consumer cross-component example end to end (a
+ * mocked cloud is acceptable per #561's acceptance criteria; the full EMR
+ * surface — retries, Serverless vs EMR-on-EC2 branching, Glue/Batch peers —
+ * stays out of scope, per #561 explicitly deferring "the emr-start-job-run
+ * cloud impl beyond what the example needs"). `emr-submit-step` is a
+ * different verb (submit a step to an already-running EMR-on-EC2 cluster
+ * rather than starting an ephemeral job run), also real over the executor
+ * (`aws emr add-steps`) and unit-tested against the mock — the same
+ * "mocked cloud is acceptable" basis #561 set for its sibling, since a live
+ * long-running EMR cluster is not part of gating CI.
+ */
+
+import type { Capability } from "@intentius/chant/components/capability";
+import { defaultCloudExecutor, type CloudExecutor } from "./cloud-executor";
+
+// ── emr-start-job-run ────────────────────────────────────────────────────────
+
+export interface EmrStartJobRunInput {
+  /**
+   * EMR (Serverless) application id, or EMR on EC2 cluster id. Optional here
+   * (unlike the underlying `CloudExecutor.emr.startJobRun` args) because the
+   * epic's worked JAR->EMR example (component-contract fixture
+   * `../__fixtures__/emr-job-consumer.json`, docs/components/composition-and-wiring.mdx)
+   * wires it as env config rather than a literal in the component
+   * declaration; falls back to `ctx.vars.emrApplicationId`, matching how
+   * `wait-cluster-healthy` (../verbs/wait-verify.ts) falls back to
+   * `ctx.vars.clusterEndpoints` for the same reason (env resolution is the
+   * caller's `DeployContext.vars`, not a literal every component must repeat).
+   */
+  clusterOrApplicationId?: string;
+  /** Entry point artifact reference — resolved by the graph before this capability runs (e.g. from `"@jar-lib.publish.uri"` to a concrete S3 URI). */
+  jar: string;
+  /** Arguments passed to the job's main class/entry point. */
+  args?: string[];
+  /** Execution role ARN. */
+  executionRoleArn?: string;
+}
+
+export interface EmrStartJobRunOutput {
+  /** EMR job run id, for polling via `wait-job`. */
+  runId: string;
+}
+
+/**
+ * Start an EMR job run (Serverless application or EMR-on-EC2 cluster)
+ * against a published artifact. `input.jar` arrives already resolved by the
+ * driver's graph-driven wiring (`@<component>.publish.uri`) — this capability
+ * never resolves the reference itself, keeping cross-component wiring
+ * entirely the graph's job (../driver.ts's `resolveWiring`), never a
+ * capability- or orchestrator-level special case. No rollback: starting a
+ * job run has no "undo" that restores prior state — a failed/cancelled run
+ * simply produced no usable output, matching `wait-for-stack`/`wait-job`'s
+ * read-only-observation story (there is nothing to compensate for having
+ * asked the cluster to run something).
+ */
+export function createEmrStartJobRunCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<EmrStartJobRunInput, EmrStartJobRunOutput> {
+  return {
+    kind: "emr-start-job-run",
+    rollbackPolicy: "needs-opt-out",
+    async run(ctx, input) {
+      const clusterOrApplicationId =
+        input.clusterOrApplicationId ?? (ctx.vars?.emrApplicationId as string | undefined) ?? ctx.component;
+      const { runId } = await executor.emr.startJobRun({
+        clusterOrApplicationId,
+        jar: input.jar,
+        args: input.args,
+        executionRoleArn: input.executionRoleArn,
+      });
+      return { runId };
+    },
+  };
+}
+
+/** Default `emr-start-job-run` capability, backed by the real `CloudExecutor`. */
+export const emrStartJobRunCapability: Capability<EmrStartJobRunInput, EmrStartJobRunOutput> =
+  createEmrStartJobRunCapability();
+
+// ── emr-submit-step ──────────────────────────────────────────────────────────
+
+export interface EmrSubmitStepInput {
+  /** EMR-on-EC2 cluster id to submit the step to. */
+  clusterId: string;
+  /** Step name, shown in the EMR console. */
+  name: string;
+  /** Entry point artifact reference (e.g. `"@jar-lib.publish.uri"`) — resolved by the graph before this capability runs, exactly like `emr-start-job-run`'s `jar`. */
+  jar: string;
+  /** Arguments passed to the step. */
+  args?: string[];
+  /** What EMR does if the step fails. Default: "CONTINUE". */
+  actionOnFailure?: "CONTINUE" | "CANCEL_AND_WAIT" | "TERMINATE_CLUSTER";
+}
+
+export interface EmrSubmitStepOutput {
+  /** EMR step id, for polling via `wait-job`. */
+  stepId: string;
+}
+
+/**
+ * Submit a step to a long-running EMR-on-EC2 cluster (as opposed to
+ * `emr-start-job-run`, which starts an ephemeral Serverless/EC2 job run) via
+ * `aws emr add-steps` through the injectable `CloudExecutor`. Returns the step
+ * id for polling via `wait-job`. Like its sibling, `input.jar` arrives
+ * already resolved by the driver's graph-driven wiring, and there is no
+ * rollback — a submitted step has no "undo" that restores prior state.
+ */
+export function createEmrSubmitStepCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<EmrSubmitStepInput, EmrSubmitStepOutput> {
+  return {
+    kind: "emr-submit-step",
+    rollbackPolicy: "needs-opt-out",
+    async run(_ctx, input) {
+      const { stepId } = await executor.emr.addStep({
+        clusterId: input.clusterId,
+        name: input.name,
+        jar: input.jar,
+        args: input.args,
+        actionOnFailure: input.actionOnFailure,
+      });
+      return { stepId };
+    },
+  };
+}
+
+/** Default `emr-submit-step` capability, backed by the real `CloudExecutor`. */
+export const emrSubmitStepCapability: Capability<EmrSubmitStepInput, EmrSubmitStepOutput> =
+  createEmrSubmitStepCapability();