@intentius/chant 0.13.0 → 0.15.0

package/src/components/verbs/build.ts

@@ -0,0 +1,252 @@
+/**
+ * build family — source -> BuildArchive, keyed by artifact type.
+ * Fully cloud-agnostic (see docs/components/cloud-boundary). `docker-build` is
+ * a real implementation (#557, epic #551) built over the injectable
+ * `CloudExecutor` (./cloud-executor.ts) so tests never shell out to a real
+ * `docker` daemon. `zip-package` (via `zip`) and `jvm-build` (via `mvn`/the
+ * gradle wrapper) are real, run through the injectable `ProcessRunner`.
+ *
+ * `docker-build` also assembles the component's `BuildArchiveManifest`
+ * (#564, epic #551 "4. Build archive + deferred publish" — see
+ * ./build-archive.ts): every build appends an `image`-kind entry recording
+ * the archive path and digest it just produced, so the archive is
+ * self-describing (content-addressed, with a manifest of contents) rather
+ * than a bare tarball. `addArchiveTemplate` lets a caller fold synthesized
+ * deploy templates (e.g. CloudFormation JSON, already written into the
+ * archive by chant's existing synthesis step) into the same manifest, so one
+ * document enumerates every content kind the archive holds.
+ *
+ * Per #614, both entry points accept an optional `sourceRef` (a git sha, or
+ * `"<sha>:<path>"` for a monorepo subpath) that becomes the entry's
+ * `provenance` link. `image`/`template` entries otherwise default to their
+ * kind-appropriate `reproducibility` basis via `addArchiveEntry` — see
+ * ./reproducibility.ts.
+ */
+
+import type { Capability } from "../capability";
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { defaultCloudExecutor, type CloudExecutor } from "./cloud-executor";
+import { defaultProcessRunner, q, type ProcessRunner } from "./process-runner";
+import {
+  addArchiveEntry,
+  contentDigest,
+  createBuildArchiveManifest,
+  type BuildArchiveManifest,
+} from "./build-archive";
+import type { ProvenanceLink } from "./reproducibility";
+
+// ── docker-build ────────────────────────────────────────────────────────────
+
+export interface DockerBuildInput {
+  /** Build context directory. */
+  context: string;
+  /** Path to the Dockerfile, relative to `context`. Default: "Dockerfile". */
+  dockerfile?: string;
+  /** Build args passed to `docker build --build-arg`. */
+  buildArgs?: Record<string, string>;
+  /** Target stage for a multi-stage build. */
+  target?: string;
+  /** Where the produced image tarball is written inside the build archive. */
+  into: string;
+  /**
+   * Manifest to extend with this build's `image` entry, rather than starting
+   * a fresh one. Pass the manifest returned by a prior build/template step in
+   * the same archive (e.g. via `@Build.manifest` wiring) to accumulate one
+   * manifest across a component's whole build phase. Omit to start a new
+   * single-entry manifest for this build alone.
+   */
+  manifest?: BuildArchiveManifest;
+  /** Source ref/commit this build was run against (#614) — recorded as the entry's `provenance.sourceRef`. Omit when unknown (e.g. a build run outside a git checkout); no `provenance` is recorded in that case. */
+  sourceRef?: string;
+}
+
+export interface DockerBuildOutput {
+  /** Path of the produced image tarball (OCI layout) inside the build archive. */
+  archivePath: string;
+  /** Content-addressed digest of the built image (`sha256:...`). */
+  digest: string;
+  /** The build archive's manifest, now including this image's entry — content-addressed via `manifest.manifestDigest`. */
+  manifest: BuildArchiveManifest;
+}
+
+/**
+ * Build a container image from a Dockerfile into the build archive: `docker
+ * build`, tagged with a build-local reference derived from `into`, then
+ * `docker save`d to the archive path (OCI layout, per `docker save`'s output
+ * format). Records the produced tarball as an `image` entry in the archive's
+ * manifest (extending `input.manifest` when the caller threads one through,
+ * so a component with more than one image build accumulates a single
+ * manifest for the whole archive). No rollback — a local build produces no
+ * remote/mutable state to compensate; the archive path is simply not consumed
+ * further if a later step fails.
+ */
+export function createDockerBuildCapability(
+  executor: CloudExecutor = defaultCloudExecutor(),
+): Capability<DockerBuildInput, DockerBuildOutput> {
+  return {
+    kind: "docker-build",
+    async run(ctx, input) {
+      const tag = `chant-build/${input.into.replace(/[^a-zA-Z0-9_.-]/g, "-")}:latest`;
+      const { digest } = await executor.docker.build({
+        context: input.context,
+        dockerfile: input.dockerfile,
+        buildArgs: input.buildArgs,
+        target: input.target,
+        tag,
+      });
+      await executor.docker.save({ image: tag, outFile: input.into });
+      const base = input.manifest ?? createBuildArchiveManifest(ctx.component);
+      const provenance: ProvenanceLink | undefined = input.sourceRef
+        ? { sourceRef: input.sourceRef, artifactDigest: digest }
+        : undefined;
+      const manifest = addArchiveEntry(base, {
+        kind: "image",
+        path: input.into,
+        digest,
+        ...(provenance ? { provenance } : {}),
+      });
+      return { archivePath: input.into, digest, manifest };
+    },
+  };
+}
+
+/** Default `docker-build` capability, backed by the real `CloudExecutor`. */
+export const dockerBuildCapability: Capability<DockerBuildInput, DockerBuildOutput> = createDockerBuildCapability();
+
+// ── archive templates ────────────────────────────────────────────────────────
+
+export interface AddArchiveTemplateInput {
+  /** Where the synthesized template is written inside the build archive (e.g. `"search.template.json"`). */
+  path: string;
+  /** Serialized template content — its digest is computed from these exact bytes, so an unrelated re-synthesis with identical content keeps the same manifest digest. */
+  content: string;
+  /** Manifest to extend. Omit to start a new manifest holding just this template. */
+  manifest?: BuildArchiveManifest;
+  /** Source ref/commit this template was synthesized from (#614) — recorded as the entry's `provenance.sourceRef`. Omit when unknown; no `provenance` is recorded in that case. */
+  sourceRef?: string;
+}
+
+export interface AddArchiveTemplateOutput {
+  /** Content-addressed digest computed over `content`. */
+  digest: string;
+  /** The build archive's manifest, now including this template's entry. */
+  manifest: BuildArchiveManifest;
+}
+
+/**
+ * Fold one synthesized deploy template (e.g. the CloudFormation JSON chant's
+ * existing synthesis already produces) into a build archive's manifest as a
+ * `template`-kind entry, alongside the image(s) `docker-build` recorded. Not
+ * a registered capability — template synthesis is chant's existing `build`
+ * pipeline (see ../../build.ts), not a new deploy-time verb — so this is a
+ * plain function a build orchestration step calls directly to keep one
+ * manifest across every content kind the archive holds (image + templates).
+ * Exported alongside the build-family capabilities since it is the other
+ * half of "what goes in the manifest" `docker-build` documents above.
+ */
+export function addArchiveTemplate(input: AddArchiveTemplateInput): AddArchiveTemplateOutput {
+  const digest = contentDigest(input.content);
+  const base = input.manifest ?? createBuildArchiveManifest("unknown");
+  const provenance: ProvenanceLink | undefined = input.sourceRef
+    ? { sourceRef: input.sourceRef, artifactDigest: digest }
+    : undefined;
+  const manifest = addArchiveEntry(base, {
+    kind: "template",
+    path: input.path,
+    digest,
+    ...(provenance ? { provenance } : {}),
+  });
+  return { digest, manifest };
+}
+
+// ── zip-package ─────────────────────────────────────────────────────────────
+
+export interface ZipPackageInput {
+  /** Directory (or file list) to package. */
+  source: string;
+  /** Glob patterns to exclude from the archive. */
+  exclude?: string[];
+  /** Where the produced zip is written inside the build archive. */
+  into: string;
+}
+
+export interface ZipPackageOutput {
+  /** Path of the produced zip inside the build archive. */
+  archivePath: string;
+  /** Content hash of the zip (for promote-by-digest style referencing). */
+  digest: string;
+}
+
+/**
+ * Package a directory into a zip artifact (e.g. a Lambda deployment package)
+ * inside the build archive, via the `zip` CLI through the injectable
+ * `ProcessRunner`. Removes any prior `into` first so the archive is rebuilt from
+ * scratch (not appended to), then returns its content digest for
+ * promote-by-digest referencing.
+ */
+export function createZipPackageCapability(processRunner: ProcessRunner = defaultProcessRunner()): Capability<ZipPackageInput, ZipPackageOutput> {
+  return {
+    kind: "zip-package",
+    async run(_ctx, input) {
+      const excludes = (input.exclude ?? []).map((p) => `-x ${q(p)}`).join(" ");
+      // `-X` drops extra file attributes; `rm -f` first so a re-run rebuilds rather than updates in place.
+      await processRunner.run(`rm -f ${q(input.into)} && zip -r -X ${q(input.into)} ${q(input.source)}${excludes ? ` ${excludes}` : ""}`);
+      const digest = `sha256:${createHash("sha256").update(readFileSync(input.into)).digest("hex")}`;
+      return { archivePath: input.into, digest };
+    },
+  };
+}
+
+/** Default `zip-package` capability, backed by the real process runner. */
+export const zipPackageCapability: Capability<ZipPackageInput, ZipPackageOutput> = createZipPackageCapability();
+
+// ── jvm-build ────────────────────────────────────────────────────────────────
+
+export interface JvmBuildInput {
+  /** Build tool driving the compile/package step. */
+  tool: "maven" | "gradle";
+  /** Project directory containing the build file. */
+  path: string;
+  /** Build tool goals/tasks to run. Default: tool-appropriate package goal. */
+  goals?: string[];
+  /** Where the produced jar is written inside the build archive. */
+  into: string;
+}
+
+export interface JvmBuildOutput {
+  /** Path of the produced jar inside the build archive. */
+  archivePath: string;
+  /** Content hash of the jar. */
+  digest: string;
+}
+
+/**
+ * Compile and package a JVM project (Maven or Gradle) into a jar in the build
+ * archive, via the build tool through the injectable `ProcessRunner`. Runs the
+ * package goal, copies the produced jar (skipping `-sources`/`-javadoc`
+ * classifiers) to `into`, and returns its content digest.
+ */
+export function createJvmBuildCapability(processRunner: ProcessRunner = defaultProcessRunner()): Capability<JvmBuildInput, JvmBuildOutput> {
+  return {
+    kind: "jvm-build",
+    async run(_ctx, input) {
+      if (input.tool === "gradle") {
+        const tasks = (input.goals ?? ["build"]).join(" ");
+        await processRunner.run(`./gradlew -q ${tasks}`, { cwd: input.path });
+        await processRunner.run(`cp "$(ls ${q(input.path)}/build/libs/*.jar | head -1)" ${q(input.into)}`);
+      } else {
+        const goals = (input.goals ?? ["package"]).join(" ");
+        await processRunner.run(`mvn -q -B -f ${q(`${input.path}/pom.xml`)} ${goals}`);
+        await processRunner.run(
+          `cp "$(ls ${q(`${input.path}/target`)}/*.jar | grep -Ev '(-sources|-javadoc)\\.jar$' | head -1)" ${q(input.into)}`,
+        );
+      }
+      const digest = `sha256:${createHash("sha256").update(readFileSync(input.into)).digest("hex")}`;
+      return { archivePath: input.into, digest };
+    },
+  };
+}
+
+/** Default `jvm-build` capability, backed by the real process runner. */
+export const jvmBuildCapability: Capability<JvmBuildInput, JvmBuildOutput> = createJvmBuildCapability();

package/src/components/verbs/cloud-executor.ts

@@ -0,0 +1,181 @@
+/**
+ * Injectable cloud I/O boundary for the *agnostic* capability implementations
+ * that remain in core: the `docker` build/push client and the Neo4j bolt-port
+ * probe. Every capability here that talks to a real tool goes through a
+ * `CloudExecutor` instead of shelling out directly, so production code gets a
+ * real, `child_process`/`net`-backed executor and tests get a
+ * `MockCloudExecutor` (./__tests__/mock-cloud-executor.ts) that records calls
+ * and returns canned results — no live docker, ever, in a test run.
+ *
+ * The AWS-specific clients (CloudFormation, ECS, Lambda, EMR, CodeDeploy, SSM
+ * host, S3, CloudFront, snapshot, ECR) used to live here too. They now live in
+ * the aws lexicon (`@intentius/chant-lexicon-aws/components`), contributed
+ * through the capability-plugin seam — see docs/components/cloud-boundary. The
+ * `docker` client stays in core because it is genuinely cloud-agnostic and
+ * shared: `docker-build` (agnostic) uses it here, and the aws lexicon's
+ * `publish-image` reuses the exported `realDocker` rather than duplicating it.
+ */
+
+import { exec } from "node:child_process";
+import { createConnection } from "node:net";
+import { promisify } from "node:util";
+
+export const execFileAsync = promisify(exec);
+
+// ── docker ────────────────────────────────────────────────────────────────
+
+export interface DockerBuildArgs {
+  context: string;
+  dockerfile?: string;
+  buildArgs?: Record<string, string>;
+  target?: string;
+  /** Tag applied to the built image so it can be referenced by name (e.g. saved to a tarball). */
+  tag: string;
+}
+
+export interface DockerSaveArgs {
+  /** Image reference to save (tag or digest). */
+  image: string;
+  /** Destination tarball path. */
+  outFile: string;
+}
+
+export interface DockerLoadArgs {
+  /** Tarball path to load. */
+  inFile: string;
+}
+
+export interface DockerTagArgs {
+  source: string;
+  target: string;
+}
+
+export interface DockerPushArgs {
+  /** Fully qualified image reference to push (registry/repo:tag). */
+  image: string;
+}
+
+export interface DockerClient {
+  /** Build an image from a Dockerfile; returns the built image's content digest. */
+  build(args: DockerBuildArgs): Promise<{ digest: string }>;
+  /** Save an image to an OCI/tarball archive on disk. */
+  save(args: DockerSaveArgs): Promise<void>;
+  /** Load an image tarball into the local docker store; returns the loaded image's digest. */
+  load(args: DockerLoadArgs): Promise<{ digest: string }>;
+  /** Tag a local image with an additional reference (e.g. before push). */
+  tag(args: DockerTagArgs): Promise<void>;
+  /** Push a tagged image to its registry; returns the pushed image's registry digest. */
+  push(args: DockerPushArgs): Promise<{ digest: string }>;
+  /** Inspect a remote image's manifest digest without pulling it (used to verify a promoted tag). */
+  remoteDigest(image: string): Promise<string>;
+}
+
+// ── Neo4j cluster probe (bolt) ───────────────────────────────────────────────
+
+export interface Neo4jProbeArgs {
+  /** Cluster identifier — a comma-separated list of `host:port` bolt endpoints. */
+  cluster: string;
+}
+
+export interface Neo4jClusterClient {
+  /** Probe every member's bolt port; returns how many are reachable/healthy. */
+  probe(args: Neo4jProbeArgs): Promise<{ healthyCount: number; total: number }>;
+}
+
+// ── the agnostic executor surface ────────────────────────────────────────────
+
+export interface CloudExecutor {
+  docker: DockerClient;
+  neo4j: Neo4jClusterClient;
+}
+
+// ── Real executor — shells out to `docker`; used outside tests ───────────────
+
+/** Run a shell command, capturing stdout/stderr. Internal to the docker client; the aws lexicon's executor has its own (endpoint-aware) runner. */
+function run(command: string): Promise<{ stdout: string; stderr: string }> {
+  return execFileAsync(command, { maxBuffer: 64 * 1024 * 1024 });
+}
+
+/** Shell-quote a single argument for POSIX shells (wrap in single quotes, escaping embedded ones). Internal; the shared, exported `q` lives in ./process-runner. */
+function q(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export const realDocker: DockerClient = {
+  async build(args) {
+    const parts = [`docker build`, `-t ${q(args.tag)}`];
+    if (args.dockerfile) parts.push(`-f ${q(args.dockerfile)}`);
+    if (args.target) parts.push(`--target ${q(args.target)}`);
+    for (const [k, v] of Object.entries(args.buildArgs ?? {})) parts.push(`--build-arg ${q(`${k}=${v}`)}`);
+    parts.push(q(args.context));
+    await run(parts.join(" "));
+    const { stdout } = await run(`docker image inspect ${q(args.tag)} --format '{{.Id}}'`);
+    return { digest: stdout.trim() };
+  },
+  async save(args) {
+    await run(`docker save ${q(args.image)} -o ${q(args.outFile)}`);
+  },
+  async load(args) {
+    const { stdout } = await run(`docker load -i ${q(args.inFile)}`);
+    const match = stdout.match(/[Ll]oaded image(?: ID)?:\s*(\S+)/);
+    return { digest: match?.[1] ?? stdout.trim() };
+  },
+  async tag(args) {
+    await run(`docker tag ${q(args.source)} ${q(args.target)}`);
+  },
+  async push(args) {
+    await run(`docker push ${q(args.image)}`);
+    const { stdout } = await run(`docker image inspect ${q(args.image)} --format '{{index .RepoDigests 0}}'`);
+    return { digest: stdout.trim() };
+  },
+  async remoteDigest(image) {
+    const { stdout } = await run(`docker manifest inspect -v ${q(image)}`);
+    return stdout.trim();
+  },
+};
+
+const realNeo4j: Neo4jClusterClient = {
+  async probe(args) {
+    const endpoints = args.cluster
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const results = await Promise.all(endpoints.map((endpoint) => probeBoltPort(endpoint)));
+    return { healthyCount: results.filter(Boolean).length, total: endpoints.length };
+  },
+};
+
+/** Probe one `host:port` bolt endpoint by opening (and immediately closing) a TCP socket. */
+function probeBoltPort(endpoint: string, timeoutMs = 5000): Promise<boolean> {
+  const [host, portStr] = endpoint.split(":");
+  const port = Number(portStr ?? 7687);
+  return new Promise((resolve) => {
+    const socket = createConnection({ host, port, timeout: timeoutMs });
+    const finish = (healthy: boolean) => {
+      socket.destroy();
+      resolve(healthy);
+    };
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+
+/** Build a `CloudExecutor` that shells out to the real `docker` CLI and probes real bolt ports. Never used in tests. */
+export function realCloudExecutor(): CloudExecutor {
+  return { docker: realDocker, neo4j: realNeo4j };
+}
+
+/** Lazily-constructed process-wide default so importing a capability module never shells out at import time. */
+let defaultExecutor: CloudExecutor | undefined;
+
+/** The default `CloudExecutor` each capability factory falls back to when none is supplied. */
+export function defaultCloudExecutor(): CloudExecutor {
+  if (!defaultExecutor) defaultExecutor = realCloudExecutor();
+  return defaultExecutor;
+}
+
+/** Sleep for `ms`. Shared by every polling capability (`wait-*`) between attempts. */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/components/verbs/component-bom.test.ts

@@ -0,0 +1,219 @@
+/**
+ * Tests `aggregateComponentBom` (#614) — the component-level BOM aggregation
+ * that composes a component's leaf BOMs (a software SBOM + an IaC
+ * config-BOM) into one component BOM. Structural validation against the
+ * real, vendored SPDX-2.3/CycloneDX-1.5 JSON Schemas, same convention as
+ * ./bom-writer.test.ts.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import Ajv from "ajv";
+import { aggregateComponentBom, componentBomLeavesFromManifest, type ComponentBomLeaf } from "./component-bom";
+import { addArchiveEntry, createBuildArchiveManifest, findArchiveEntry } from "./build-archive";
+import type { BomPackage } from "./bom-writer";
+
+const SCHEMAS_DIR = join(import.meta.dirname, "__fixtures__/schemas");
+function loadSchema(name: string): unknown {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), "utf-8"));
+}
+
+const FIXED_NOW = () => new Date("2026-01-01T00:00:00.000Z");
+
+/** Build a manifest for "search-service": an image + a software SBOM leaf, a template + a config-BOM leaf. */
+function multiArtifactManifest() {
+  let manifest = createBuildArchiveManifest("search-service", { now: FIXED_NOW });
+  manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:img1" });
+  manifest = addArchiveEntry(manifest, { kind: "template", path: "search.template.json", digest: "sha256:tmpl1" });
+  manifest = addArchiveEntry(manifest, {
+    kind: "sbom",
+    bomKind: "software",
+    path: "image.tar.sbom.json",
+    digest: "sha256:sbomsoft",
+    subjectDigest: "sha256:img1",
+    mediaType: "application/spdx+json",
+    packageCount: 1,
+    generator: "chant-lockfile-sbom/package-lock.json",
+  });
+  manifest = addArchiveEntry(manifest, {
+    kind: "sbom",
+    bomKind: "config",
+    path: "search.template.json.config-bom.json",
+    digest: "sha256:sbomconfig",
+    subjectDigest: "sha256:tmpl1",
+    mediaType: "application/spdx+json",
+    packageCount: 1,
+    generator: "chant-config-bom-extractor",
+  });
+  return manifest;
+}
+
+function multiArtifactLeaves(manifest: ReturnType<typeof multiArtifactManifest>): ComponentBomLeaf[] {
+  return [
+    {
+      entry: findArchiveEntry(manifest, "image.tar.sbom.json")!,
+      packages: [{ name: "left-pad", version: "1.3.0", type: "npm" } satisfies BomPackage],
+    },
+    {
+      entry: findArchiveEntry(manifest, "search.template.json.config-bom.json")!,
+      packages: [{ name: "SearchBucket", version: "AWS::S3::Bucket", type: "config" } satisfies BomPackage],
+    },
+  ];
+}
+
+describe("aggregateComponentBom (#614)", () => {
+  describe("multi-artifact component — a real assembly", () => {
+    it("SPDX: composes both leaves into one valid document", () => {
+      const manifest = multiArtifactManifest();
+      const leaves = multiArtifactLeaves(manifest);
+      const result = aggregateComponentBom({ component: "search-service", manifest, leaves, format: "spdx", now: FIXED_NOW });
+
+      expect(result.leafCount).toBe(2);
+      expect(result.totalPackageCount).toBe(2);
+      expect(result.bom.format).toBe("spdx");
+
+      const doc = JSON.parse(result.bom.bytes) as Record<string, unknown>;
+      const schema = loadSchema("spdx-2.3.schema.json");
+      const ajv = new Ajv({ strict: false, allErrors: true });
+      const validate = ajv.compile(schema as object);
+      const valid = validate(doc);
+      if (!valid) throw new Error(ajv.errorsText(validate.errors));
+      expect(valid).toBe(true);
+      expect(doc.name).toBe("search-service");
+    });
+
+    it("CycloneDX: composes both leaves into one valid document with nested components + compositions", () => {
+      const manifest = multiArtifactManifest();
+      const leaves = multiArtifactLeaves(manifest);
+      const result = aggregateComponentBom({ component: "search-service", manifest, leaves, format: "cyclonedx", now: FIXED_NOW });
+
+      const doc = JSON.parse(result.bom.bytes) as {
+        metadata: { component: { name: string; components: unknown[] } };
+        compositions: Array<{ aggregate: string }>;
+      };
+      const cdxSchema = loadSchema("cyclonedx-1.5.schema.json");
+      const jsfSchema = loadSchema("jsf-0.82.schema.json");
+      const spdxLicenseSchema = loadSchema("cyclonedx-spdx-license.schema.json");
+      const ajv = new Ajv({ strict: false, allErrors: true });
+      ajv.addSchema(jsfSchema as object);
+      ajv.addSchema(spdxLicenseSchema as object);
+      const validate = ajv.compile(cdxSchema as object);
+      const valid = validate(doc);
+      if (!valid) throw new Error(ajv.errorsText(validate.errors));
+      expect(valid).toBe(true);
+
+      expect(doc.metadata.component.name).toBe("search-service");
+      expect(doc.metadata.component.components).toHaveLength(2);
+      expect(doc.compositions[0]!.aggregate).toBe("incomplete");
+    });
+
+    it("preserves which packages came from which leaf — never flattens software and config packages into one anonymous list", () => {
+      const manifest = multiArtifactManifest();
+      const leaves = multiArtifactLeaves(manifest);
+      const result = aggregateComponentBom({ component: "search-service", manifest, leaves, format: "cyclonedx", now: FIXED_NOW });
+      const doc = JSON.parse(result.bom.bytes);
+
+      const softwareLeaf = doc.metadata.component.components.find((c: { name: string }) => c.name.startsWith("software:"));
+      const configLeaf = doc.metadata.component.components.find((c: { name: string }) => c.name.startsWith("config:"));
+      expect(softwareLeaf.components.map((c: { name: string }) => c.name)).toEqual(["left-pad"]);
+      expect(configLeaf.components.map((c: { name: string }) => c.name)).toEqual(["SearchBucket"]);
+    });
+
+    it("each sub-document's subjectId traces back to the artifact digest it describes (subjectDigest), not the BOM document's own digest", () => {
+      const manifest = multiArtifactManifest();
+      const leaves = multiArtifactLeaves(manifest);
+      const result = aggregateComponentBom({ component: "search-service", manifest, leaves, format: "cyclonedx", now: FIXED_NOW });
+      const doc = JSON.parse(result.bom.bytes);
+
+      const softwareLeaf = doc.metadata.component.components.find((c: { name: string }) => c.name.startsWith("software:"));
+      const configLeaf = doc.metadata.component.components.find((c: { name: string }) => c.name.startsWith("config:"));
+      const subjectIdOf = (c: { properties: Array<{ name: string; value: string }> }) =>
+        c.properties.find((p) => p.name === "chant:subjectId")!.value;
+      expect(subjectIdOf(softwareLeaf)).toBe("sha256:img1");
+      expect(subjectIdOf(configLeaf)).toBe("sha256:tmpl1");
+    });
+
+    it("is deterministic — identical leaves + manifest produce byte-identical output", () => {
+      const manifest = multiArtifactManifest();
+      const leaves = multiArtifactLeaves(manifest);
+      const a = aggregateComponentBom({ component: "search-service", manifest, leaves, format: "spdx", now: FIXED_NOW });
+      const b = aggregateComponentBom({ component: "search-service", manifest, leaves, format: "spdx", now: FIXED_NOW });
+      expect(a.bom.bytes).toBe(b.bom.bytes);
+    });
+  });
+
+  describe("single-artifact component — 1:1, still a valid standalone document", () => {
+    it("one leaf produces a valid document with no sub-document nesting", () => {
+      let manifest = createBuildArchiveManifest("infra-only", { now: FIXED_NOW });
+      manifest = addArchiveEntry(manifest, { kind: "template", path: "infra.template.json", digest: "sha256:tmpl1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        bomKind: "config",
+        path: "infra.template.json.config-bom.json",
+        digest: "sha256:sbomconfig",
+        subjectDigest: "sha256:tmpl1",
+        mediaType: "application/spdx+json",
+        packageCount: 1,
+      });
+      const leaves: ComponentBomLeaf[] = [
+        {
+          entry: findArchiveEntry(manifest, "infra.template.json.config-bom.json")!,
+          packages: [{ name: "SearchTable", version: "AWS::DynamoDB::Table", type: "config" }],
+        },
+      ];
+
+      const result = aggregateComponentBom({ component: "infra-only", manifest, leaves, format: "spdx", now: FIXED_NOW });
+      expect(result.leafCount).toBe(1);
+      expect(result.totalPackageCount).toBe(1);
+
+      const doc = JSON.parse(result.bom.bytes);
+      const schema = loadSchema("spdx-2.3.schema.json");
+      const ajv = new Ajv({ strict: false, allErrors: true });
+      const validate = ajv.compile(schema as object);
+      expect(validate(doc)).toBe(true);
+      // no CONTAINS relationship — nothing nested, the leaf's packages are
+      // the aggregate's own flat package list directly.
+      expect(doc.relationships.some((r: { relationshipType: string }) => r.relationshipType === "CONTAINS")).toBe(false);
+    });
+  });
+
+  describe("error handling", () => {
+    it("throws when given zero leaves — aggregation over nothing is a caller bug, not a silent no-op", () => {
+      const manifest = createBuildArchiveManifest("empty");
+      expect(() => aggregateComponentBom({ component: "empty", manifest, leaves: [] })).toThrow(/no leaf BOMs/);
+    });
+  });
+
+  describe("defaults", () => {
+    it("defaults to DEFAULT_SBOM_FORMAT (spdx) when format is omitted", () => {
+      const manifest = multiArtifactManifest();
+      const leaves = multiArtifactLeaves(manifest);
+      const result = aggregateComponentBom({ component: "search-service", manifest, leaves, now: FIXED_NOW });
+      expect(result.bom.format).toBe("spdx");
+    });
+  });
+});
+
+describe("componentBomLeavesFromManifest (#614)", () => {
+  it("builds ComponentBomLeaf[] for every sbom-kind entry that has a known package list", () => {
+    const manifest = multiArtifactManifest();
+    const packagesByPath = new Map<string, BomPackage[]>([
+      ["image.tar.sbom.json", [{ name: "left-pad", version: "1.3.0", type: "npm" }]],
+      ["search.template.json.config-bom.json", [{ name: "SearchBucket", version: "AWS::S3::Bucket", type: "config" }]],
+    ]);
+    const leaves = componentBomLeavesFromManifest(manifest, packagesByPath);
+    expect(leaves).toHaveLength(2);
+    expect(leaves.map((l) => l.entry.path).sort()).toEqual(["image.tar.sbom.json", "search.template.json.config-bom.json"]);
+  });
+
+  it("skips sbom entries with no known package list rather than failing", () => {
+    const manifest = multiArtifactManifest();
+    const packagesByPath = new Map<string, BomPackage[]>([
+      ["image.tar.sbom.json", [{ name: "left-pad", version: "1.3.0", type: "npm" }]],
+    ]);
+    const leaves = componentBomLeavesFromManifest(manifest, packagesByPath);
+    expect(leaves).toHaveLength(1);
+    expect(leaves[0]!.entry.path).toBe("image.tar.sbom.json");
+  });
+});