@intentius/chant 0.124.46 → 0.124.49

package/src/components/verbs/publish-artifact.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import {
+  createPublishArtifactCapability,
+  selectStorageBackend,
+  type ArtifactStorageBackend,
+} from "./publish-artifact";
+
+function fake(name: string, prefix: string) {
+  const uploads: Array<{ from: string; to: string }> = [];
+  const backend: ArtifactStorageBackend = {
+    name,
+    matches: (uri) => uri.startsWith(prefix),
+    upload: async (args) => void uploads.push(args),
+  };
+  return { backend, uploads };
+}
+
+describe("selectStorageBackend (#4408)", () => {
+  const s3 = fake("s3", "s3://").backend;
+  const gcs = fake("gcs", "gs://").backend;
+  it("prefers a named backend, then the matching one, then the only one", () => {
+    expect(selectStorageBackend([s3, gcs], "s3://b/k", "gcs")).toBe(gcs);
+    expect(selectStorageBackend([s3, gcs], "gs://b/k")).toBe(gcs);
+    expect(selectStorageBackend([s3], "weird://x")).toBe(s3);
+  });
+  it("refuses an unknown name, an ambiguous match and an undecidable pick", () => {
+    expect(() => selectStorageBackend([s3], "s3://b/k", "nope")).toThrow(/no storage backend "nope"/);
+    expect(() => selectStorageBackend([s3, fake("s3b", "s3://").backend], "s3://b/k")).toThrow(/matches several/);
+    expect(() => selectStorageBackend([s3, gcs], "weird://x")).toThrow(/cannot tell/);
+  });
+});
+
+describe("publish-artifact (core)", () => {
+  it("uploads through the backend the environment names and returns uri + digest", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-pa-core-"));
+    const file = join(dir, "app.jar");
+    writeFileSync(file, "JAR");
+    const a = fake("s3", "s3://");
+    const b = fake("gcs", "gs://");
+    const cap = createPublishArtifactCapability({ backends: [a.backend, b.backend] });
+    const out = await cap.run({ env: "dev", component: "c", vars: { publish: { backend: "gcs" } } } as never, { from: file, to: "gs://bk/jars/" });
+    expect(out).toEqual({ uri: "gs://bk/jars/app.jar", digest: `sha256:${createHash("sha256").update("JAR").digest("hex")}` });
+    expect(b.uploads).toEqual([{ from: file, to: "gs://bk/jars/app.jar" }]);
+    expect(a.uploads).toEqual([]);
+  });
+
+  it("withStorageBackends rebinds the verb", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "chant-pa-core-"));
+    const file = join(dir, "x.zip");
+    writeFileSync(file, "Z");
+    const a = fake("s3", "s3://");
+    const cap = createPublishArtifactCapability().withStorageBackends([a.backend]) as ReturnType<typeof createPublishArtifactCapability>;
+    await cap.run({ env: "dev", component: "c" } as never, { from: file, to: "s3://b/x.zip" });
+    expect(a.uploads).toHaveLength(1);
+  });
+});

package/src/components/verbs/publish-artifact.ts

@@ -0,0 +1,122 @@
+/**
+ * `publish-artifact` (aliased `publish-asset`): the object-storage half of the
+ * publish family, owned by core (#4408), the same way `publish-image` is.
+ * "Put this archive file at the deploy target" is one agnostic verb; what
+ * differs per cloud is the upload. Each cloud lexicon contributes that as an
+ * {@link ArtifactStorageBackend} through `CapabilityPlugin.storageBackends()`
+ * (aws: S3, azure: Blob, gcp: GCS), and the environment picks one (see
+ * {@link selectStorageBackend}).
+ *
+ * This is a sibling of `registryBackends()` rather than a reuse of it: a
+ * registry backend only logs a docker client in, while a storage backend
+ * moves bytes, and the two are matched against different destinations.
+ *
+ * Core computes the content digest and the final object URI; the backend only
+ * uploads. No rollback.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { Capability } from "../capability";
+import { archiveRelativePath } from "./build-archive";
+
+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). A trailing `/` appends the file's basename. */
+  to: string;
+  /** Which storage backend to use ("s3", "azure-blob", "gcs"). Normally left out: `$env.publish.backend` or the destination URI picks it. */
+  backend?: 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;
+}
+
+/** A cloud's way of putting one local file at a storage URI. */
+export interface ArtifactStorageBackend {
+  /** Stable name an environment selects by: "s3", "azure-blob", "gcs". */
+  readonly name: string;
+  /** True when this backend owns the destination URI. */
+  matches(uri: string): boolean;
+  /** Upload the local file `from` to the full object URI `to`. */
+  upload(args: { from: string; to: string }): Promise<void>;
+}
+
+export class StorageBackendError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StorageBackendError";
+  }
+}
+
+/**
+ * Pick the storage backend for one publish. Order: the step's `backend`, then
+ * the environment's `ctx.vars.publish.backend`, then the single backend whose
+ * `matches` claims the destination, then the only backend there is.
+ */
+export function selectStorageBackend(
+  backends: readonly ArtifactStorageBackend[],
+  uri: string,
+  named?: string,
+): ArtifactStorageBackend {
+  const names = backends.map((b) => b.name).sort().join(", ") || "none";
+  if (named) {
+    const found = backends.find((b) => b.name === named);
+    if (!found) {
+      throw new StorageBackendError(
+        `publish-artifact: no storage backend "${named}" is registered (available: ${names}); declare the lexicon that contributes it in chant.config.ts`,
+      );
+    }
+    return found;
+  }
+  const matched = backends.filter((b) => b.matches(uri));
+  if (matched.length === 1) return matched[0]!;
+  if (matched.length > 1) {
+    throw new StorageBackendError(
+      `publish-artifact: destination "${uri}" matches several backends (${matched.map((b) => b.name).join(", ")}); set $env.publish.backend`,
+    );
+  }
+  if (backends.length === 1) return backends[0]!;
+  throw new StorageBackendError(
+    `publish-artifact: cannot tell which storage backend serves "${uri}" (available: ${names}); set $env.publish.backend`,
+  );
+}
+
+/** Implemented by a capability that wants the plugins' storage backends injected when a registry is built. */
+export interface StorageBackendConsumer {
+  withStorageBackends(backends: readonly ArtifactStorageBackend[]): Capability<never, unknown>;
+}
+
+export function isStorageBackendConsumer(value: unknown): value is StorageBackendConsumer {
+  return typeof value === "object" && value !== null && typeof (value as StorageBackendConsumer).withStorageBackends === "function";
+}
+
+export type PublishArtifactCapability = Capability<PublishArtifactInput, PublishArtifactOutput> & StorageBackendConsumer;
+
+/** Build the `publish-artifact` verb over the storage backends available. */
+export function createPublishArtifactCapability(options: { backends?: readonly ArtifactStorageBackend[] } = {}): PublishArtifactCapability {
+  const backends = options.backends ?? [];
+  return {
+    kind: "publish-artifact",
+    withStorageBackends(next) {
+      return createPublishArtifactCapability({ backends: next });
+    },
+    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;
+      const envBackend = (ctx.vars?.publish as { backend?: unknown } | undefined)?.backend;
+      const backend = selectStorageBackend(backends, uri, input.backend ?? (typeof envBackend === "string" ? envBackend : undefined));
+      await backend.upload({ from: localPath, to: uri });
+      return { uri, digest };
+    },
+  };
+}
+
+/** The starter plugin's `publish-artifact`: storage backends injected from the loaded plugins. */
+export const publishArtifactCapability: PublishArtifactCapability = createPublishArtifactCapability();

package/src/components/verbs/publish-image.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import {
+  RegistryBackendError,
+  createPublishImageCapability,
+  selectRegistryBackend,
+  type RegistryLoginBackend,
+} from "./publish-image";
+import type { DockerClient } from "./cloud-executor";
+import { CapabilityRegistry } from "../capability";
+import { registerCapabilityPlugins, DuplicateCapabilityKindError } from "../capability-plugin-loader";
+import { starterCapabilityPlugin } from "../starter-plugin";
+import type { CapabilityPlugin } from "../capability-plugin";
+
+function backend(name: string, host: RegExp, log: string[] = []): RegistryLoginBackend {
+  return { name, matches: (r) => host.test(r), login: async (r) => void log.push(`${name}:${r}`) };
+}
+
+function fakeDocker(log: string[] = []): DockerClient {
+  return {
+    build: async () => ({ digest: "sha256:b" }),
+    save: async () => {},
+    load: async () => ({ digest: "local:1" }),
+    tag: async () => void log.push("tag"),
+    push: async () => ({ digest: "sha256:abc" }),
+    remoteDigest: async () => "sha256:abc",
+  };
+}
+
+const ctx = { env: "dev", component: "svc" };
+
+describe("selectRegistryBackend", () => {
+  const ecr = backend("ecr", /\.ecr\./);
+  const acr = backend("acr", /azurecr/);
+  it("picks by registry host", () => {
+    expect(selectRegistryBackend([ecr, acr], "x.azurecr.io").name).toBe("acr");
+  });
+  it("an explicit name wins over the host", () => {
+    expect(selectRegistryBackend([ecr, acr], "x.azurecr.io", "ecr").name).toBe("ecr");
+  });
+  it("rejects an unknown name, listing what is available", () => {
+    expect(() => selectRegistryBackend([ecr], "h", "acr")).toThrow(/no registry backend "acr".*ecr/);
+  });
+  it("falls back to the only backend", () => {
+    expect(selectRegistryBackend([ecr], "registry.example.com").name).toBe("ecr");
+  });
+  it("is ambiguous with several backends and no match", () => {
+    expect(() => selectRegistryBackend([ecr, acr], "registry.example.com")).toThrow(RegistryBackendError);
+  });
+});
+
+describe("core publish-image", () => {
+  it("logs in through the backend the environment names", async () => {
+    const log: string[] = [];
+    const cap = createPublishImageCapability({
+      docker: fakeDocker(),
+      backends: [backend("ecr", /\.ecr\./, log), backend("acr", /azurecr/, log)],
+    });
+    const out = await cap.run({ ...ctx, vars: { publish: { backend: "acr" } } }, { from: "a.tar", to: "reg.example.com/app/" });
+    expect(log).toEqual(["acr:reg.example.com"]);
+    expect(out).toMatchObject({ digest: "sha256:abc", uri: "reg.example.com/app@sha256:abc" });
+  });
+
+  it("the registry rebinds the verb to the backends of every loaded plugin", () => {
+    const seen: string[][] = [];
+    const consumer = {
+      kind: "publish-image",
+      run: async () => ({}),
+      withRegistryBackends(bs: readonly RegistryLoginBackend[]) {
+        seen.push(bs.map((b) => b.name));
+        return { kind: "publish-image", run: async () => ({}) };
+      },
+    };
+    const plugin = (name: string, b?: RegistryLoginBackend): CapabilityPlugin => ({
+      name,
+      version: "0",
+      capabilities: () => (name === "core" ? ([consumer] as never) : []),
+      ...(b ? { registryBackends: () => [b] } : {}),
+    });
+    registerCapabilityPlugins(new CapabilityRegistry(), [
+      plugin("core"),
+      plugin("aws", backend("ecr", /\.ecr\./)),
+      plugin("azure", backend("acr", /azurecr/)),
+    ]);
+    expect(seen).toEqual([["ecr", "acr"]]);
+  });
+
+  it("the starter plugin carries the real publish-image verb", () => {
+    expect(starterCapabilityPlugin.capabilities().map((c) => c.kind)).toContain("publish-image");
+  });
+
+  it("a plugin that registers publish-image itself still collides", () => {
+    const dup: CapabilityPlugin = {
+      name: "dup",
+      version: "0",
+      capabilities: () => [{ kind: "publish-image", run: async () => ({}) }] as never,
+    };
+    expect(() => registerCapabilityPlugins(new CapabilityRegistry(), [starterCapabilityPlugin, dup])).toThrow(
+      DuplicateCapabilityKindError,
+    );
+  });
+});

package/src/components/verbs/publish-image.ts

@@ -0,0 +1,265 @@
+/**
+ * `publish-image`: the registry half of the publish family, owned by core
+ * (#3142, #3143). "Make the image available at the deploy target" is one
+ * agnostic verb; what differs per cloud is how the local docker client logs in
+ * to the registry. Each cloud lexicon contributes that as a
+ * {@link RegistryLoginBackend} through `CapabilityPlugin.registryBackends()`
+ * (aws: ECR, azure: ACR, gcp: Artifact Registry), and the environment picks
+ * one (see {@link selectRegistryBackend}). So a project may declare several
+ * clouds without two plugins registering the same verb.
+ *
+ * Promotion is by digest and unchanged from the aws-only implementation: load
+ * the archived tarball, tag for the destination, log in, push, read the digest
+ * back from the push. Optional SBOM/BOM referrers attach via `oras`, best
+ * effort. No rollback: a pushed, content-addressed image is not something to
+ * undo. See docs/components/build-archive.mdx.
+ */
+
+import type { Capability } from "../capability";
+import { archiveRelativePath } from "./build-archive";
+import { realDocker, type DockerClient } from "./cloud-executor";
+import { defaultProcessRunner, q, type ProcessRunner } from "./process-runner";
+
+/**
+ * Common input shape both image-publish backends accept (`publish-image` here, `load-image-on-host` in the aws lexicon): 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;
+  /**
+   * Which registry login backend to use ("ecr", "acr", "artifact-registry").
+   * Normally left out: the environment config (`ctx.vars.publish.backend`) or
+   * the registry host picks it.
+   */
+  backend?: 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>;
+
+// ── registry login backends ──────────────────────────────────────────────────
+
+/** A cloud's way of authenticating the local docker client to its registry. */
+export interface RegistryLoginBackend {
+  /** Stable name an environment selects by: "ecr", "acr", "artifact-registry". */
+  readonly name: string;
+  /** True when this backend owns the registry host (used when the environment does not name one). */
+  matches(registry: string): boolean;
+  /** Authenticate docker against `registry` (host part of the destination). */
+  login(registry: string): Promise<void>;
+}
+
+export class RegistryBackendError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RegistryBackendError";
+  }
+}
+
+/**
+ * Pick the login backend for one publish. Order: the step's `backend`, then the
+ * environment's `ctx.vars.publish.backend`, then the single backend whose
+ * `matches` claims the registry host, then the only backend there is.
+ */
+export function selectRegistryBackend(
+  backends: readonly RegistryLoginBackend[],
+  registry: string,
+  named?: string,
+): RegistryLoginBackend {
+  const names = backends.map((b) => b.name).sort().join(", ") || "none";
+  if (named) {
+    const found = backends.find((b) => b.name === named);
+    if (!found) {
+      throw new RegistryBackendError(
+        `publish-image: no registry backend "${named}" is registered (available: ${names}); declare the lexicon that contributes it in chant.config.ts`,
+      );
+    }
+    return found;
+  }
+  const matched = backends.filter((b) => b.matches(registry));
+  if (matched.length === 1) return matched[0]!;
+  if (matched.length > 1) {
+    throw new RegistryBackendError(
+      `publish-image: registry "${registry}" matches several backends (${matched.map((b) => b.name).join(", ")}); set $env.publish.backend`,
+    );
+  }
+  if (backends.length === 1) return backends[0]!;
+  throw new RegistryBackendError(
+    `publish-image: cannot tell which registry backend serves "${registry}" (available: ${names}); set $env.publish.backend`,
+  );
+}
+
+/** Implemented by a capability that wants the plugins' registry backends injected when a registry is built. */
+export interface RegistryBackendConsumer {
+  withRegistryBackends(backends: readonly RegistryLoginBackend[]): Capability<never, unknown>;
+}
+
+export function isRegistryBackendConsumer(value: unknown): value is RegistryBackendConsumer {
+  return typeof value === "object" && value !== null && typeof (value as RegistryBackendConsumer).withRegistryBackends === "function";
+}
+
+// ── publish-image ────────────────────────────────────────────────────────────
+
+/**
+ * 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 };
+}
+
+export interface PublishImageOptions {
+  docker: DockerClient;
+  backends?: readonly RegistryLoginBackend[];
+  processRunner?: ProcessRunner;
+}
+
+export type PublishImageCapability = PublishImageBackend & RegistryBackendConsumer;
+
+/**
+ * Build the `publish-image` verb over a docker client and the registry login
+ * backends available. Load, tag, log in via the selected backend, push, and
+ * return the pushed digest.
+ */
+export function createPublishImageCapability(options: PublishImageOptions): PublishImageCapability {
+  const { docker } = options;
+  const backends = options.backends ?? [];
+  const processRunner = options.processRunner ?? defaultProcessRunner();
+  return {
+    kind: "publish-image",
+    withRegistryBackends(next) {
+      return createPublishImageCapability({ docker, processRunner, backends: next });
+    },
+    async run(ctx, input) {
+      if (!input.to) throw new Error(`publish-image "${input.from}": "to" (destination registry) is required`);
+      const repo = input.to.replace(/\/+$/, "");
+      const registry = repo.split("/")[0]!;
+      const envBackend = (ctx.vars?.publish as { backend?: unknown } | undefined)?.backend;
+      const backend = selectRegistryBackend(backends, registry, input.backend ?? (typeof envBackend === "string" ? envBackend : undefined));
+      // `docker load` reports the archived image's local reference: a name:tag
+      // for a tagged build, or an image id. It is a valid `docker tag` source
+      // but never a registry digest, so the promoted digest is read back from
+      // the push below.
+      const { digest: localRef } = await docker.load({ inFile: archiveRelativePath(input.from) });
+      // Publish under a tag: docker can neither tag nor push a digest-qualified
+      // reference, so the transport is a tag and the stable identifier is the
+      // digest the push returns.
+      const pushRef = `${repo}:latest`;
+      await docker.tag({ source: localRef, target: pushRef });
+      await backend.login(registry);
+      const { digest: pushed } = await docker.push({ image: pushRef });
+      const digest = pushed.includes("@") ? pushed.slice(pushed.indexOf("@") + 1) : pushed;
+      for (const tag of input.tags ?? []) {
+        const tagged = `${repo}:${tag}`;
+        await docker.tag({ source: localRef, target: tagged });
+        await docker.push({ image: tagged });
+      }
+      const referrerAttach = await attachReferrers(processRunner, `${repo}@${digest}`, input);
+      return { digest, uri: `${repo}@${digest}`, ...(referrerAttach ? { referrerAttach } : {}) };
+    },
+  };
+}
+
+/** The starter plugin's `publish-image`: real docker, backends injected from the loaded plugins. */
+export const publishImageCapability: PublishImageCapability = createPublishImageCapability({ docker: realDocker });

package/src/config-environments.ts

@@ -21,8 +21,23 @@ import type { ChantConfig } from "./config";
  * `./workspace/promotion-order.ts`), and `canary: true` marks a step as the
  * canary step of that order. The canary is declared and surfaced; chant does
  * not yet act on it.
+ *
+ * `executor` names the forge and the committed workflow that deploys the
+ * environment (#4402), so a reader such as behold knows a release there runs
+ * through CI rather than a local `chant run`. chant declares and prints it
+ * (`chant workspace graph --composites`); it never dispatches it.
  */
-export type EnvironmentDeclaration = string | { name: string; endpoint?: string; canary?: boolean };
+export type EnvironmentDeclaration = string | { name: string; endpoint?: string; canary?: boolean; executor?: EnvironmentExecutor };
+
+/** The forges an environment's executor can name (#4402). */
+export const EXECUTOR_FORGES = ["github", "gitlab", "forgejo"] as const;
+
+/** The forge workflow that deploys one environment (#4402). */
+export interface EnvironmentExecutor {
+  forge: (typeof EXECUTOR_FORGES)[number];
+  /** The committed workflow file the forge runs, such as `deploy-prod.yml` under `.github/workflows/`, or `.gitlab-ci.yml`. */
+  workflow: string;
+}
 
 /**
  * `ownership.env`: a literal environment identity, or a reference to a
@@ -115,6 +130,18 @@ export function environmentEndpoint(environments: EnvironmentDeclaration[] | und
   return found && typeof found !== "string" ? found.endpoint : undefined;
 }
 
+/**
+ * The executor `name` declares (#4402), resolved like {@link
+ * environmentEndpoint}: a literal entry wins over a pattern, and a literal
+ * entry with no executor does not fall through to a pattern's.
+ */
+export function environmentExecutor(environments: EnvironmentDeclaration[] | undefined, name: string): EnvironmentExecutor | undefined {
+  const found =
+    environments?.find((e) => environmentName(e) === name) ??
+    environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+  return found && typeof found !== "string" ? found.executor : undefined;
+}
+
 /** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
 export function isOwnershipParamRef(env: OwnershipEnv | undefined): env is { param: string } {
   return typeof env === "object" && env !== null && typeof env.param === "string";

package/src/config.ts

@@ -19,7 +19,9 @@ import { PublishDeclarationSchema, type PublishDeclaration } from "./lifecycle/p
 // needs only them stays clear of the loader below (#4356 follow-up).
 export {
   environmentEndpoint,
+  environmentExecutor,
   environmentName,
+  EXECUTOR_FORGES,
   environmentNames,
   isEnvironmentPattern,
   isOwnershipParamRef,
@@ -27,9 +29,10 @@ export {
   matchesEnvironmentPattern,
   resolveOwnershipStack,
   type EnvironmentDeclaration,
+  type EnvironmentExecutor,
   type OwnershipEnv,
 } from "./config-environments";
-import { isOwnershipParamRef, resolveOwnershipStack, type EnvironmentDeclaration, type OwnershipEnv } from "./config-environments";
+import { EXECUTOR_FORGES, isOwnershipParamRef, resolveOwnershipStack, type EnvironmentDeclaration, type OwnershipEnv } from "./config-environments";
 
 /**
  * Zod schema for ChantConfig validation.
@@ -40,6 +43,10 @@ const EnvironmentEntrySchema = z.union([
     name: z.string().min(1),
     endpoint: z.string().min(1).optional(),
     canary: z.boolean().optional(),
+    executor: z.object({
+      forge: z.enum(EXECUTOR_FORGES),
+      workflow: z.string().min(1),
+    }).strict().optional(),
   }),
 ]);
 
@@ -69,6 +76,10 @@ export const ChantConfigSchema = z.object({
   // Strict like `run`: a misspelt `lint` would leave the gate on with nothing said.
   graph: z.object({
     lint: z.enum(["gate", "report"]).optional(),
+    reader: z.object({
+      module: z.string().min(1),
+      config: z.record(z.string(), z.unknown()).optional(),
+    }).strict().optional(),
   }).strict().optional(),
   buildParams: z.record(
     z.string(),
@@ -227,6 +238,18 @@ export interface ChantConfig {
    */
   graph?: {
     lint?: "gate" | "report";
+    /**
+     * A graph reader module (#4413): when set, `chant graph --format ir` loads
+     * `module` (an absolute path to an ES module whose default export is
+     * `(input: { dir, config }) => GraphIR`) and prints what it returns,
+     * instead of discovering lexicon entities. The reader project
+     * `chant workspace graph` writes for a kind whose `graph.reader` names a
+     * module sets it. A chant older than the key ignores it.
+     */
+    reader?: {
+      module: string;
+      config?: Record<string, unknown>;
+    };
   };
 
   /**