@intentius/chant-lexicon-aws 0.14.0 → 0.15.0

package/src/components/publish.test.ts

@@ -0,0 +1,318 @@
+import { describe, expect, it } from "vitest";
+import {
+  createLoadImageOnHostCapability,
+  createPublishImageCapability,
+  createPublishArtifactCapability,
+  loadImageOnHostCapability as loadImageOnHost,
+  publishImageCapability as publishImage,
+  selectPublishBackend,
+} from "./publish";
+import { writeFileSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { createDockerBuildCapability } from "@intentius/chant/components/verbs/build";
+import { createMockCloudExecutor } from "./__tests__/mock-cloud-executor";
+import { createMockProcessRunner } from "@intentius/chant/components/verbs/__tests__/mock-process-runner";
+
+const ctx = { env: "dev", component: "search-service" };
+
+describe("publish-image (#557)", () => {
+  it("loads the archived tarball, tags for the destination registry, logs in, and pushes — promoting by digest", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createPublishImageCapability(mock.executor);
+
+    const output = await capability.run(ctx, { from: "archive/search.tar", to: "123.dkr.ecr.us-east-1.amazonaws.com/search" });
+
+    expect(output.digest).toMatch(/^sha256:/);
+    expect(output.uri).toBe(`123.dkr.ecr.us-east-1.amazonaws.com/search@${output.digest}`);
+    expect(mock.calls.map((c) => c.method)).toEqual(["load", "tag", "login", "push"]);
+    const loginCall = mock.calls.find((c) => c.method === "login")!;
+    expect(loginCall.args).toBe("123.dkr.ecr.us-east-1.amazonaws.com");
+  });
+
+  it("pushes additional tags alongside the digest", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createPublishImageCapability(mock.executor);
+
+    await capability.run(ctx, {
+      from: "archive/search.tar",
+      to: "123.dkr.ecr.us-east-1.amazonaws.com/search",
+      tags: ["latest", "v1.2.3"],
+    });
+
+    const pushCalls = mock.calls.filter((c) => c.method === "push");
+    // one push for the digest-qualified reference, one per extra tag
+    expect(pushCalls).toHaveLength(3);
+    const pushedImages = pushCalls.map((c) => (c.args as { image: string }).image);
+    expect(pushedImages.some((i) => i.endsWith(":latest"))).toBe(true);
+    expect(pushedImages.some((i) => i.endsWith(":v1.2.3"))).toBe(true);
+  });
+
+  it("surfaces a push failure (e.g. registry auth/network) as a rejected promise", async () => {
+    const mock = createMockCloudExecutor({ failDocker: true });
+    const capability = createPublishImageCapability(mock.executor);
+    await expect(
+      capability.run(ctx, { from: "archive/search.tar", to: "123.dkr.ecr.us-east-1.amazonaws.com/search" }),
+    ).rejects.toThrow(/docker push failed/);
+  });
+
+  it("declares no rollback — an already-pushed, content-addressed image is not itself something to undo", () => {
+    const capability = createPublishImageCapability(createMockCloudExecutor().executor);
+    expect(capability.rollback).toBeUndefined();
+  });
+
+  it("accepts an archive: wiring reference the same way cfn-deploy's template field does", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createPublishImageCapability(mock.executor);
+    await capability.run(ctx, { from: "archive:search.tar", to: "123.dkr.ecr.us-east-1.amazonaws.com/search" });
+    const loadCall = mock.calls.find((c) => c.method === "load")!;
+    expect(loadCall.args).toMatchObject({ inFile: "search.tar" });
+  });
+
+  it("requires to — throws a clear error rather than silently no-op-ing when the env forgot to configure a registry", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createPublishImageCapability(mock.executor);
+    await expect(capability.run(ctx, { from: "archive/search.tar" })).rejects.toThrow(/"to".*is required/);
+  });
+});
+
+describe("publish-image — SBOM/component-BOM referrer attach (#610)", () => {
+  it("does nothing (no oras call at all) when neither sbom nor componentBom is supplied", async () => {
+    const cloud = createMockCloudExecutor();
+    const proc = createMockProcessRunner();
+    const capability = createPublishImageCapability(cloud.executor, proc.runner);
+
+    const output = await capability.run(ctx, { from: "archive/search.tar", to: "123.dkr.ecr.us-east-1.amazonaws.com/search" });
+
+    expect(output.referrerAttach).toBeUndefined();
+    expect(proc.calls).toHaveLength(0);
+  });
+
+  it("attaches the SBOM as an OCI referrer on the pushed digest via oras attach", async () => {
+    const cloud = createMockCloudExecutor();
+    const proc = createMockProcessRunner();
+    const capability = createPublishImageCapability(cloud.executor, proc.runner);
+
+    const output = await capability.run(ctx, {
+      from: "archive/search.tar",
+      to: "123.dkr.ecr.us-east-1.amazonaws.com/search",
+      sbom: { bytes: '{"fake":"sbom"}', mediaType: "application/spdx+json" },
+    });
+
+    expect(output.referrerAttach).toEqual({ attached: true });
+    const attachCall = proc.calls.find((c) => c.command.startsWith("oras attach"))!;
+    expect(attachCall.command).toContain("--artifact-type 'application/spdx+json'");
+    expect(attachCall.command).toContain(`123.dkr.ecr.us-east-1.amazonaws.com/search@${output.digest}`);
+  });
+
+  it("attaches both the SBOM and the component BOM when both are supplied", async () => {
+    const cloud = createMockCloudExecutor();
+    const proc = createMockProcessRunner();
+    const capability = createPublishImageCapability(cloud.executor, proc.runner);
+
+    await capability.run(ctx, {
+      from: "archive/search.tar",
+      to: "123.dkr.ecr.us-east-1.amazonaws.com/search",
+      sbom: { bytes: '{"fake":"sbom"}', mediaType: "application/spdx+json" },
+      componentBom: { bytes: '{"fake":"bom"}', mediaType: "application/vnd.cyclonedx+json" },
+    });
+
+    const attachCalls = proc.calls.filter((c) => c.command.startsWith("oras attach"));
+    expect(attachCalls).toHaveLength(2);
+    expect(attachCalls.some((c) => c.command.includes("application/spdx+json"))).toBe(true);
+    expect(attachCalls.some((c) => c.command.includes("application/vnd.cyclonedx+json"))).toBe(true);
+  });
+
+  it("reports attached: false with a reason, and does not fail the publish, when oras is not installed", async () => {
+    const cloud = createMockCloudExecutor();
+    const proc = createMockProcessRunner({ tools: { oras: false } });
+    const capability = createPublishImageCapability(cloud.executor, proc.runner);
+
+    const output = await capability.run(ctx, {
+      from: "archive/search.tar",
+      to: "123.dkr.ecr.us-east-1.amazonaws.com/search",
+      sbom: { bytes: '{"fake":"sbom"}', mediaType: "application/spdx+json" },
+    });
+
+    expect(output.digest).toMatch(/^sha256:/); // the image itself still published successfully.
+    expect(output.referrerAttach?.attached).toBe(false);
+    expect(output.referrerAttach?.reason).toMatch(/oras.*not installed/);
+    expect(proc.calls.some((c) => c.command.startsWith("oras attach"))).toBe(false);
+  });
+
+  it("reports attached: false with a reason, and does not fail the publish, when oras attach itself fails", async () => {
+    const cloud = createMockCloudExecutor();
+    const proc = createMockProcessRunner({ failures: { "oras attach": "oras: unauthorized" } });
+    const capability = createPublishImageCapability(cloud.executor, proc.runner);
+
+    const output = await capability.run(ctx, {
+      from: "archive/search.tar",
+      to: "123.dkr.ecr.us-east-1.amazonaws.com/search",
+      sbom: { bytes: '{"fake":"sbom"}', mediaType: "application/spdx+json" },
+    });
+
+    expect(output.digest).toMatch(/^sha256:/);
+    expect(output.referrerAttach).toEqual({ attached: false, reason: "oras: unauthorized" });
+  });
+
+  it("load-image-on-host never attempts a referrer attach — registry-less, nothing to attach to", async () => {
+    const cloud = createMockCloudExecutor();
+    const proc = createMockProcessRunner();
+    const capability = createLoadImageOnHostCapability(cloud.executor);
+
+    const output = await capability.run(ctx, {
+      from: "archive/search.tar",
+      host: "i-abc",
+      sbom: { bytes: '{"fake":"sbom"}', mediaType: "application/spdx+json" },
+    });
+
+    expect(output.referrerAttach).toBeUndefined();
+    expect(proc.calls).toHaveLength(0);
+  });
+});
+
+describe("load-image-on-host (#564 — registry-less backend)", () => {
+  it("copies the archived tarball to the host and docker-loads it there, with no registry/ECR calls at all", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createLoadImageOnHostCapability(mock.executor);
+
+    const output = await capability.run(ctx, { from: "archive/search.tar", host: "i-0123456789abcdef0" });
+
+    expect(output.digest).toMatch(/^sha256:/);
+    expect(output.uri).toBe(`host:i-0123456789abcdef0#${output.digest}`);
+    expect(mock.calls.map((c) => `${c.client}.${c.method}`)).toEqual(["host.copyFile", "host.dockerLoad"]);
+    expect(mock.calls.some((c) => c.client === "ecr" || c.client === "docker")).toBe(false);
+  });
+
+  it("defaults the on-host path to the archive path's basename under /tmp/chant-archive", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createLoadImageOnHostCapability(mock.executor);
+    await capability.run(ctx, { from: "archive/search.tar", host: "i-abc" });
+    const copyCall = mock.calls.find((c) => c.method === "copyFile")!;
+    expect(copyCall.args).toMatchObject({ to: "/tmp/chant-archive/search.tar" });
+  });
+
+  it("accepts an archive: wiring reference and an explicit destination path", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createLoadImageOnHostCapability(mock.executor);
+    await capability.run(ctx, { from: "archive:search.tar", host: "i-abc", hostPath: "/opt/images/search.tar" });
+    const copyCall = mock.calls.find((c) => c.method === "copyFile")!;
+    expect(copyCall.args).toMatchObject({ from: "search.tar", to: "/opt/images/search.tar" });
+  });
+
+  it("requires host — throws a clear error rather than silently no-op-ing when the env forgot to configure one", async () => {
+    const mock = createMockCloudExecutor();
+    const capability = createLoadImageOnHostCapability(mock.executor);
+    await expect(capability.run(ctx, { from: "archive/search.tar" })).rejects.toThrow(/"host" is required/);
+  });
+
+  it("surfaces a host copy/load failure (unreachable host) as a rejected promise", async () => {
+    const mock = createMockCloudExecutor({ failHost: true });
+    const capability = createLoadImageOnHostCapability(mock.executor);
+    await expect(capability.run(ctx, { from: "archive/search.tar", host: "i-abc" })).rejects.toThrow(
+      /host copy failed/,
+    );
+  });
+
+  it("declares no rollback — an already-loaded, content-addressed image on the host is not itself something to undo", () => {
+    const capability = createLoadImageOnHostCapability(createMockCloudExecutor().executor);
+    expect(capability.rollback).toBeUndefined();
+  });
+});
+
+describe("promote by digest — deferred publish never rebuilds per environment (#564 acceptance criterion)", () => {
+  it("one docker-build's archived image promotes to two environments (registry + host-load) from the same archive, with no second build", async () => {
+    // One archive/executor shared across build + both env promotions — the
+    // same archive the build produced is what each environment's publish
+    // step reads from, never a fresh build.
+    const mock = createMockCloudExecutor();
+    const { archivePath } = await createDockerBuildCapability(mock.executor).run(ctx, {
+      context: ".",
+      into: "archive/search.tar",
+    });
+    expect(mock.calls.filter((c) => c.method === "build")).toHaveLength(1);
+
+    // dev: env config selects the registry backend.
+    const devBackend = selectPublishBackend("publish-image", {
+      "publish-image": createPublishImageCapability(mock.executor),
+      "load-image-on-host": createLoadImageOnHostCapability(mock.executor),
+    });
+    const devOutput = await devBackend.run(
+      { env: "dev", component: "search-service" },
+      { from: archivePath, to: "123.dkr.ecr.us-east-1.amazonaws.com/search" },
+    );
+
+    // prod: env config selects the registry-less host backend for the *same archive path* — no rebuild.
+    const prodBackend = selectPublishBackend("load-image-on-host", {
+      "publish-image": createPublishImageCapability(mock.executor),
+      "load-image-on-host": createLoadImageOnHostCapability(mock.executor),
+    });
+    const prodOutput = await prodBackend.run(
+      { env: "prod", component: "search-service" },
+      { from: archivePath, host: "i-prodhost" },
+    );
+
+    // Exactly one build happened for the whole scenario — both environment
+    // promotions read the same archived tarball rather than triggering a
+    // second `docker build`. `publish-image` reads it via `docker.load`;
+    // `load-image-on-host` reads the very same path via `host.copyFile`
+    // instead — two different backends, one unrebuilt archive.
+    expect(mock.calls.filter((c) => c.method === "build")).toHaveLength(1);
+    expect(mock.calls.find((c) => c.method === "load")?.args).toMatchObject({ inFile: archivePath });
+    expect(mock.calls.find((c) => c.method === "copyFile")?.args).toMatchObject({ from: archivePath });
+    expect(devOutput.digest).toMatch(/^sha256:/);
+    expect(prodOutput.digest).toMatch(/^sha256:/);
+  });
+
+  it("selectPublishBackend defaults to the two starter-set backends and throws on an unknown kind", () => {
+    expect(selectPublishBackend("publish-image")).toBe(publishImage);
+    expect(selectPublishBackend("load-image-on-host")).toBe(loadImageOnHost);
+    expect(() =>
+      selectPublishBackend(
+        // @ts-expect-error deliberately invalid kind to exercise the error path
+        "something-else",
+      ),
+    ).toThrow(/no publish backend registered/);
+  });
+});
+
+describe("publish-artifact (#557)", () => {
+  it("uploads the archive file to S3 and returns its uri + content digest", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-pa-"));
+    const file = join(dir, "app.jar");
+    writeFileSync(file, "JAR-BYTES");
+    const expectedDigest = `sha256:${createHash("sha256").update("JAR-BYTES").digest("hex")}`;
+    const mock = createMockCloudExecutor();
+
+    const out = await createPublishArtifactCapability(mock.executor).run(
+      { env: "dev", component: "jar-lib" },
+      { from: file, to: "s3://artifacts/jars/" },
+    );
+
+    expect(out.digest).toBe(expectedDigest);
+    expect(out.uri).toBe("s3://artifacts/jars/app.jar"); // trailing-slash `to` appends the basename
+    expect(mock.calls).toEqual([
+      { client: "s3", method: "cp", args: { from: file, to: "s3://artifacts/jars/app.jar" } },
+    ]);
+  });
+
+  it("strips an archive: prefix and uses `to` verbatim when it is a full key", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-pa-"));
+    const file = join(dir, "asset.bin");
+    writeFileSync(file, "X");
+    const mock = createMockCloudExecutor();
+
+    const out = await createPublishArtifactCapability(mock.executor).run(
+      { env: "dev", component: "c" },
+      { from: `archive:${file}`, to: "s3://b/exact-key" },
+    );
+
+    expect(out.uri).toBe("s3://b/exact-key");
+    expect(mock.calls[0]!.args).toEqual({ from: file, to: "s3://b/exact-key" });
+  });
+
+  it("declares no rollback", () => {
+    expect(createPublishArtifactCapability(createMockCloudExecutor().executor).rollback).toBeUndefined();
+  });
+});

package/src/components/publish.ts

@@ -0,0 +1,356 @@
+/**
+ * publish family — deploy-time promotion by identity to the env location.
+ *
+ * "Make the image available at the deploy target" has more than one backend:
+ * `publish-image` promotes into a registry (ECR/ACR/Artifact Registry, pulled
+ * by the target); `load-image-on-host` copies the tarball straight onto a host
+ * and `docker load`s it (registry-less). Both satisfy the same
+ * `PublishImageBackend` interface — the backend is env config, not a pipeline
+ * fork. `publish-asset`/`publish-artifact` is the non-image sibling (S3 /
+ * CodeArtifact) used by producer/library components (e.g. a jar for EMR).
+ * See docs/components/build-archive.mdx.
+ *
+ * `publish-image` is a real implementation (#557, epic #551): it loads the
+ * archived image tarball, tags it for the destination registry, logs in via
+ * ECR, and pushes — promoting by digest, per the epic's build-once invariant.
+ *
+ * `load-image-on-host` is a real implementation (#564, epic #551 "4. Build
+ * archive + deferred publish"): it copies the archived tarball onto a host
+ * and runs `docker load` there via the injected `CloudExecutor.host` — no
+ * registry in the path at all. Both backends promote **by digest**, never
+ * rebuilding: the bytes they move are exactly what `docker-build` produced
+ * into the archive (see ./build-archive.ts). `selectPublishBackend` below is
+ * the per-environment choice between them — env config, not a pipeline fork,
+ * per docs/components/build-archive.mdx#backend-selection-is-per-environment.
+ *
+ * `publish-artifact` (aliased `publish-asset`) uploads a single archive
+ * artifact (jar/zip/asset) to S3 via `aws s3 cp` through the same
+ * endpoint-aware `CloudExecutor`, returning the object URI and a content digest
+ * of the uploaded bytes — the non-image sibling of `publish-image`.
+ *
+ * **#610 addition: publish-time SBOM/BOM referrer attach.** `publish-image`
+ * optionally registers the archive's SBOM (and, when given, the
+ * component-level aggregate BOM) as an OCI referrer on the just-pushed image
+ * digest via `oras attach` — a registry-side convenience for `oras
+ * discover`/`cosign tree` layered on top of the archive-carried copy, never a
+ * replacement for it (see ../../lifecycle/build-ledger.ts's module doc: the
+ * archive remains the universal home, working for every artifact type and
+ * the registry-less `load-image-on-host` path, which this attach step
+ * deliberately does not touch — non-image/registry-less publishes stay
+ * archive-carried only). Attach is opt-in per call (`input.sbom` supplied),
+ * guarded on `oras` availability, and never fails the publish itself: a
+ * missing `oras` binary or a failed attach is reported back on the output
+ * (`referrerAttach.attached: false` + a reason) rather than thrown, since the
+ * image is already successfully promoted by the time this step runs — the
+ * one part of this capability that is genuinely best-effort.
+ */
+
+import type { Capability } from "@intentius/chant/components/capability";
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { defaultCloudExecutor, type CloudExecutor } from "./cloud-executor";
+import { archiveRelativePath } from "@intentius/chant/components/verbs/build-archive";
+import { defaultProcessRunner, q, type ProcessRunner } from "@intentius/chant/components/verbs/process-runner";
+
+// ── shared backend interface ─────────────────────────────────────────────────
+
+/**
+ * Common input shape both image-publish backends accept: promote the image
+ * bytes at archive path `from` to wherever the deploy target can consume
+ * them. `to` (registry) and `host` (bare host) are each meaningful to only
+ * one backend, so a component authors one step shape (see
+ * docs/components/build-archive.mdx) and the env-selected backend (see
+ * `selectPublishBackend` below) reads whichever field it needs — the
+ * unselected backend's field is simply unused, never a pipeline fork.
+ */
+export interface PublishImageInput {
+  /** Path of the image tarball inside the build archive (as produced by `docker-build`; an `archive:`-prefixed reference is accepted and stripped). */
+  from: string;
+  /** Destination registry — required by `publish-image`, ignored by `load-image-on-host` (e.g. `$env.registry` resolved by the orchestrator). */
+  to?: string;
+  /** Target host — required by `load-image-on-host`, ignored by `publish-image` (SSM instance id, hostname, or host group). */
+  host?: string;
+  /** Destination path for the tarball on the host, used only by `load-image-on-host`. Default: `/tmp/chant-archive/<basename of from>`. */
+  hostPath?: string;
+  /** Additional tags to apply alongside the digest, used only by `publish-image`. */
+  tags?: string[];
+  /**
+   * #610: the artifact's software SBOM (typically wired from a prior
+   * `generate-sbom` step's `sbom` output — see ./sbom.ts's
+   * `GenerateSbomOutput`) to attach as an OCI referrer on the pushed image
+   * digest, via `oras attach`. Used only by `publish-image`; ignored by
+   * `load-image-on-host` (registry-less — nothing to attach to). Omit to
+   * skip the attach step entirely (the archive-carried copy remains the
+   * SBOM's home either way).
+   */
+  sbom?: { bytes: string; mediaType: string };
+  /**
+   * #610: the component-level aggregate BOM (wired from
+   * ./component-bom.ts's `aggregateComponentBom` output), attached as a
+   * second OCI referrer alongside `sbom` when supplied. Optional and
+   * independent of `sbom` — a caller may attach either, both, or neither.
+   */
+  componentBom?: { bytes: string; mediaType: string };
+}
+
+/** Result of `publish-image`'s best-effort OCI-referrer attach step (#610) — always present when `input.sbom`/`input.componentBom` was supplied, `undefined` when neither was (nothing to attach, attach step skipped entirely). */
+export interface ReferrerAttachResult {
+  /** True once every requested attach (`sbom`, `componentBom`) succeeded. `false` if `oras` was unavailable or any `oras attach` invocation failed. */
+  attached: boolean;
+  /** Human-readable reason `attached` is `false` (e.g. "oras is not installed"), omitted when `attached` is `true`. */
+  reason?: string;
+}
+
+export interface PublishImageOutput {
+  /** Content-addressed digest of the promoted image (`sha256:...`) — what the apply step references. */
+  digest: string;
+  /** Image reference the apply step can pull/run: `registry/repo@sha256:...` for `publish-image`, a host-local reference for `load-image-on-host`. */
+  uri: string;
+  /** #610: outcome of the best-effort SBOM/component-BOM referrer attach, when `input.sbom`/`input.componentBom` was supplied. `undefined` for `load-image-on-host` (no attach concept — registry-less) and for `publish-image` calls that supplied neither. */
+  referrerAttach?: ReferrerAttachResult;
+}
+
+/**
+ * Common shape both image-publish backends satisfy: promote the image bytes
+ * held in the build archive to wherever the deploy target can consume them,
+ * and return the identity the apply step references. The backend is
+ * selected per environment (`selectPublishBackend`), never per component.
+ */
+export type PublishImageBackend = Capability<PublishImageInput, PublishImageOutput>;
+
+// ── publish-image (registry backend) ────────────────────────────────────────
+
+/**
+ * Attempt to `oras attach` one referrer document (SBOM or component BOM) to
+ * `imageRef`'s digest. Writes the document's bytes to a scratch file (`oras
+ * attach` reads from a file path, not stdin) and shells out through
+ * `runner`. Never throws — a failure here is reported back to the caller as
+ * `{ ok: false, reason }` so a missing/erroring `oras` never fails the
+ * publish itself (see `attachReferrers`'s doc comment for why).
+ */
+async function attachOneReferrer(
+  runner: ProcessRunner,
+  imageRef: string,
+  doc: { bytes: string; mediaType: string },
+  label: string,
+): Promise<{ ok: boolean; reason?: string }> {
+  try {
+    const scratchFile = `/tmp/chant-referrer-attach/${label}-${Date.now()}.json`;
+    await runner.run(`mkdir -p ${q("/tmp/chant-referrer-attach")}`);
+    await runner.run(`printf '%s' ${q(doc.bytes)} > ${q(scratchFile)}`);
+    await runner.run(`oras attach --artifact-type ${q(doc.mediaType)} ${q(imageRef)} ${q(scratchFile)}:${q(doc.mediaType)}`);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * Best-effort OCI-referrer attach for a just-pushed image (#610): attaches
+ * `input.sbom` and/or `input.componentBom`, when supplied, to `imageRef` via
+ * `oras attach`. Guarded on `oras` availability — a missing binary is
+ * reported back as `{ attached: false, reason }` rather than thrown, since
+ * the image itself is already successfully promoted by the time this step
+ * runs (attach is additive registry-side convenience on top of the
+ * archive-carried copy, per this module's doc comment, never a condition the
+ * core promote-by-digest job depends on). Returns `undefined` when neither
+ * `input.sbom` nor `input.componentBom` was supplied — nothing to attach,
+ * skipped entirely, no `oras` call at all.
+ */
+async function attachReferrers(
+  runner: ProcessRunner,
+  imageRef: string,
+  input: Pick<PublishImageInput, "sbom" | "componentBom">,
+): Promise<ReferrerAttachResult | undefined> {
+  if (!input.sbom && !input.componentBom) return undefined;
+
+  if (!(await runner.available("oras"))) {
+    return { attached: false, reason: `"oras" is not installed or not on PATH — required to attach OCI referrers` };
+  }
+
+  const results: Array<{ ok: boolean; reason?: string }> = [];
+  if (input.sbom) results.push(await attachOneReferrer(runner, imageRef, input.sbom, "sbom"));
+  if (input.componentBom) results.push(await attachOneReferrer(runner, imageRef, input.componentBom, "component-bom"));
+
+  const failed = results.find((r) => !r.ok);
+  return failed ? { attached: false, reason: failed.reason } : { attached: true };
+}
+
+/**
+ * Promote a built image from the archive into the environment's container
+ * registry: `docker load` the archived tarball, tag it for `to` (the env
+ * registry), `aws ecr get-login-password | docker login`, then `docker push`.
+ * Returns the pushed image's registry digest — what `cfn-deploy`/
+ * `ecs-update-service` reference via `imageRef: "@Publish.digest"`. No
+ * rollback: an already-pushed, still-valid image in the registry is not
+ * itself a problem to compensate (immutable, content-addressed, and simply
+ * unreferenced if a later step fails) — the opt-out this capability takes.
+ *
+ * #610: when `input.sbom` and/or `input.componentBom` are supplied, also
+ * attaches them as OCI referrers on the pushed digest via `oras attach` (see
+ * `attachReferrers` above) — best-effort, guarded on `oras` availability,
+ * surfaced on the output's `referrerAttach` rather than failing the publish.
+ */
+export function createPublishImageCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+  processRunner: ProcessRunner = defaultProcessRunner(),
+): PublishImageBackend {
+  return {
+    kind: "publish-image",
+    async run(_ctx, input) {
+      if (!input.to) throw new Error(`publish-image "${input.from}": "to" (destination registry) is required`);
+      // `docker load` reports the archived image's local reference — a name:tag
+      // for a tagged build, or an image id. It's a valid `docker tag` source but
+      // never a registry digest, so the promoted digest is read back from the
+      // push below, not constructed from this.
+      const { digest: localRef } = await executor.docker.load({ inFile: archiveRelativePath(input.from) });
+      const repo = input.to.replace(/\/+$/, "");
+      // Publish under a tag: docker can neither tag nor push a digest-qualified
+      // reference (`repo@sha256:...`), so the transport is a tag and the stable
+      // identifier is the digest the push returns.
+      const pushRef = `${repo}:latest`;
+      await executor.docker.tag({ source: localRef, target: pushRef });
+      const registry = repo.split("/")[0]!;
+      await executor.ecr.login(registry);
+      const { digest: pushed } = await executor.docker.push({ image: pushRef });
+      // Normalize to a bare `sha256:...`, whether the client returned that or a
+      // full `repo@sha256:...` RepoDigest.
+      const digest = pushed.includes("@") ? pushed.slice(pushed.indexOf("@") + 1) : pushed;
+      for (const tag of input.tags ?? []) {
+        const tagged = `${repo}:${tag}`;
+        await executor.docker.tag({ source: localRef, target: tagged });
+        await executor.docker.push({ image: tagged });
+      }
+
+      const referrerAttach = await attachReferrers(processRunner, `${repo}@${digest}`, input);
+      return { digest, uri: `${repo}@${digest}`, ...(referrerAttach ? { referrerAttach } : {}) };
+    },
+  };
+}
+
+/** Default `publish-image` capability, backed by the real `CloudExecutor`. */
+export const publishImageCapability: PublishImageBackend = createPublishImageCapability();
+
+// ── load-image-on-host (host backend) ───────────────────────────────────────
+
+/** Default on-host tarball destination when `hostPath` is omitted, derived from the archive path's basename. */
+function defaultHostPath(from: string): string {
+  const base = archiveRelativePath(from).split("/").pop() ?? "image.tar";
+  return `/tmp/chant-archive/${base}`;
+}
+
+/**
+ * Copy the image tarball straight onto a host and `docker load` it there —
+ * genuinely registry-free promotion (#564): no `docker.push`, no ECR login,
+ * no registry ever in the path. Still promotes **by digest**: the tarball
+ * copied is the exact archive artifact `docker-build` produced, so the image
+ * loaded on the host is byte-identical to the one tested in any other
+ * environment, satisfying the same build-once invariant `publish-image`
+ * does. No rollback, for the same reason `publish-image` declares none: an
+ * already-loaded, content-addressed image sitting in a host's local Docker
+ * store is not itself a problem to compensate.
+ *
+ * See docs/components/build-archive.mdx#registry-less-caveat: this makes
+ * *your built* image registry-free. Third-party images a compose file
+ * references (`postgres:16`, `redis`) still pull from their upstream
+ * registry at `compose up` unless they are archived and loaded the same way.
+ */
+export function createLoadImageOnHostCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): PublishImageBackend {
+  return {
+    kind: "load-image-on-host",
+    async run(_ctx, input) {
+      if (!input.host) throw new Error(`load-image-on-host "${input.from}": "host" is required`);
+      const from = archiveRelativePath(input.from);
+      const to = input.hostPath ?? defaultHostPath(input.from);
+      await executor.host.copyFile({ host: input.host, from, to });
+      const { digest } = await executor.host.dockerLoad({ host: input.host, path: to });
+      return { digest, uri: `host:${input.host}#${digest}` };
+    },
+  };
+}
+
+/** Default `load-image-on-host` capability, backed by the real `CloudExecutor`. */
+export const loadImageOnHostCapability: PublishImageBackend = createLoadImageOnHostCapability();
+
+// ── per-environment backend selection ───────────────────────────────────────
+
+/** The `kind` of either image-publish backend — what an environment's config declares as its choice. */
+export type PublishImageBackendKind = "publish-image" | "load-image-on-host";
+
+/**
+ * Resolve which publish backend an environment uses, given its declared
+ * `kind` (`$env.publish.kind` in the component's env config — see
+ * docs/components/build-archive.mdx#backend-selection-is-per-environment).
+ * The decision is per environment, not per component: the same component's
+ * `Publish` phase runs `publish-image` against dev's ECR and
+ * `load-image-on-host` against a locked-down prod host, with no change to
+ * the component's own composition — only the env config `kind` differs.
+ *
+ * Accepts an optional registry of backends so a caller can extend the set
+ * (e.g. a third-party plugin registering another `PublishImageBackend`)
+ * without this function needing to change; defaults to the two starter-set
+ * backends built above.
+ */
+export function selectPublishBackend(
+  kind: PublishImageBackendKind,
+  backends: Partial<Record<PublishImageBackendKind, PublishImageBackend>> = {
+    "publish-image": publishImageCapability,
+    "load-image-on-host": loadImageOnHostCapability,
+  },
+): PublishImageBackend {
+  const backend = backends[kind];
+  if (!backend) {
+    throw new Error(
+      `no publish backend registered for kind "${kind}" (known: ${Object.keys(backends).sort().join(", ")})`,
+    );
+  }
+  return backend;
+}
+
+// ── publish-asset / publish-artifact ────────────────────────────────────────
+
+export interface PublishArtifactInput {
+  /** Path of the artifact inside the build archive (e.g. a jar or zip). */
+  from: string;
+  /** Destination (e.g. `$env.s3` resolved by the orchestrator). */
+  to: string;
+}
+
+export interface PublishArtifactOutput {
+  /** Location the artifact was published to — referenced downstream as `@<component>.publish.uri`. */
+  uri: string;
+  /** Content hash of the published artifact. */
+  digest: string;
+}
+
+/** Promote a non-image artifact (jar, zip, arbitrary asset) from the archive to S3/CodeArtifact. */
+/**
+ * Publish a single archive artifact (a jar, zip, or asset) to S3 via `aws s3 cp`
+ * (endpoint-aware through the `CloudExecutor`). Returns the object's URI —
+ * referenced downstream as `@<component>.publish.uri` — and a content digest of
+ * the exact bytes uploaded.
+ */
+export function createPublishArtifactCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<PublishArtifactInput, PublishArtifactOutput> {
+  return {
+    kind: "publish-artifact",
+    async run(_ctx, input) {
+      const localPath = archiveRelativePath(input.from);
+      const digest = `sha256:${createHash("sha256").update(readFileSync(localPath)).digest("hex")}`;
+      const basename = localPath.split("/").pop() ?? localPath;
+      const uri = input.to.endsWith("/") ? `${input.to}${basename}` : input.to;
+      await executor.s3.cp({ from: localPath, to: uri });
+      return { uri, digest };
+    },
+  };
+}
+
+/** Default `publish-artifact` capability, backed by the real `CloudExecutor`. */
+export const publishArtifactCapability: Capability<PublishArtifactInput, PublishArtifactOutput> =
+  createPublishArtifactCapability();
+
+/** Alias for `publish-artifact` — same capability, the docs/epic use both names for the same verb. */
+export const publishAssetCapability = publishArtifactCapability;