@intentius/chant 0.13.1 → 0.15.1

package/src/lifecycle/build-ledger.test.ts

@@ -0,0 +1,349 @@
+import { describe, test, expect } from "vitest";
+import {
+  buildLedgerEntries,
+  findReferrer,
+  noopReferrerLookup,
+  artifactReproducibilitySummary,
+  componentBomSummary,
+  type Referrer,
+  type ReferrerLookup,
+} from "./build-ledger";
+import {
+  createBuildArchiveManifest,
+  addArchiveEntry,
+  findSbomForSubject,
+} from "../components/verbs/build-archive";
+
+describe("build-ledger", () => {
+  describe("buildLedgerEntries", () => {
+    test("returns one entry per image-kind manifest entry", async () => {
+      let manifest = createBuildArchiveManifest("search-service", { now: () => new Date("2026-01-01T00:00:00.000Z") });
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      manifest = addArchiveEntry(manifest, { kind: "template", path: "search.template.json", digest: "sha256:tmpl1" });
+
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries).toHaveLength(1);
+      expect(entries[0]).toMatchObject({
+        component: "search-service",
+        path: "image.tar",
+        digest: "sha256:image1",
+        manifestDigest: manifest.manifestDigest,
+      });
+    });
+
+    test("noop lookup (default) attaches no referrers", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries[0].referrers).toEqual([]);
+    });
+
+    test("injected lookup attaches referrers keyed by digest", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+
+      const sbom: Referrer = { kind: "sbom", mediaType: "application/vnd.cyclonedx+json", digest: "sha256:sbom1" };
+      const provenance: Referrer = { kind: "provenance", mediaType: "application/vnd.in-toto+json", digest: "sha256:prov1" };
+      const lookup: ReferrerLookup = {
+        async discover(digest) {
+          if (digest !== "sha256:image1") return [];
+          return [sbom, provenance];
+        },
+      };
+
+      const entries = await buildLedgerEntries(manifest, lookup);
+      expect(entries[0].referrers).toEqual([sbom, provenance]);
+    });
+
+    test("multiple image entries each get their own referrer lookup", async () => {
+      let manifest = createBuildArchiveManifest("multi-image");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "a.tar", digest: "sha256:a" });
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "b.tar", digest: "sha256:b" });
+
+      const lookup: ReferrerLookup = {
+        async discover(digest) {
+          return [{ kind: "signature", mediaType: "application/vnd.dev.cosign.simplesigning.v1+json", digest: `${digest}-sig` }];
+        },
+      };
+
+      const entries = await buildLedgerEntries(manifest, lookup);
+      expect(entries.map((e) => e.path).sort()).toEqual(["a.tar", "b.tar"]);
+      const byDigest = new Map(entries.map((e) => [e.digest, e]));
+      expect(byDigest.get("sha256:a")?.referrers[0].digest).toBe("sha256:a-sig");
+      expect(byDigest.get("sha256:b")?.referrers[0].digest).toBe("sha256:b-sig");
+    });
+
+    test("no image entries -> no build ledger entries", async () => {
+      let manifest = createBuildArchiveManifest("infra-only");
+      manifest = addArchiveEntry(manifest, { kind: "template", path: "t.json", digest: "sha256:t" });
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries).toEqual([]);
+    });
+  });
+
+  describe("findReferrer", () => {
+    test("finds a referrer by kind", () => {
+      const referrers: Referrer[] = [
+        { kind: "sbom", mediaType: "x", digest: "sha256:1" },
+        { kind: "signature", mediaType: "y", digest: "sha256:2" },
+      ];
+      expect(findReferrer(referrers, "signature")?.digest).toBe("sha256:2");
+      expect(findReferrer(referrers, "provenance")).toBeUndefined();
+    });
+  });
+
+  describe("noopReferrerLookup", () => {
+    test("always returns an empty list", async () => {
+      expect(await noopReferrerLookup.discover("sha256:anything")).toEqual([]);
+    });
+  });
+
+  describe("sbom summary (#606) — archive-carried vs referrer-projected", () => {
+    test("no sbom entry and no sbom referrer -> sbom is undefined (component opted out / no SBOM generated)", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries[0].sbom).toBeUndefined();
+    });
+
+    test("archive-carried sbom entry is surfaced with format/package count/generator, source 'archive'", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        path: "image.tar.sbom.json",
+        digest: "sha256:sbomdoc",
+        mediaType: "application/spdx+json",
+        subjectDigest: "sha256:image1",
+        packageCount: 17,
+        generator: "syft",
+      });
+
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries[0].sbom).toEqual({
+        mediaType: "application/spdx+json",
+        packageCount: 17,
+        generator: "syft",
+        source: "archive",
+      });
+    });
+
+    test("referrer-projected sbom is surfaced when no archive-carried entry exists, source 'referrer'", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+
+      const lookup: ReferrerLookup = {
+        async discover(digest) {
+          if (digest !== "sha256:image1") return [];
+          return [{ kind: "sbom", mediaType: "application/vnd.cyclonedx+json", digest: "sha256:sbomref" }];
+        },
+      };
+
+      const entries = await buildLedgerEntries(manifest, lookup);
+      expect(entries[0].sbom).toEqual({
+        mediaType: "application/vnd.cyclonedx+json",
+        source: "referrer",
+      });
+    });
+
+    test("archive-carried sbom is preferred over a referrer-projected one when both exist", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        path: "image.tar.sbom.json",
+        digest: "sha256:sbomdoc",
+        mediaType: "application/spdx+json",
+        subjectDigest: "sha256:image1",
+        packageCount: 9,
+        generator: "buildkit",
+      });
+
+      const lookup: ReferrerLookup = {
+        async discover() {
+          return [{ kind: "sbom", mediaType: "application/vnd.cyclonedx+json", digest: "sha256:sbomref" }];
+        },
+      };
+
+      const entries = await buildLedgerEntries(manifest, lookup);
+      expect(entries[0].sbom).toEqual({
+        mediaType: "application/spdx+json",
+        packageCount: 9,
+        generator: "buildkit",
+        source: "archive",
+      });
+    });
+
+    test("format-agnostic: CycloneDX archive-carried sbom is surfaced the same way SPDX is", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        path: "image.tar.sbom.json",
+        digest: "sha256:sbomdoc",
+        mediaType: "application/vnd.cyclonedx+json",
+        subjectDigest: "sha256:image1",
+        packageCount: 5,
+        generator: "syft",
+      });
+
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries[0].sbom?.mediaType).toBe("application/vnd.cyclonedx+json");
+    });
+
+    test("non-image artifact (jar/zip, no image entry) still carries its sbom in the manifest, findable independent of buildLedgerEntries (which is image-scoped)", async () => {
+      let manifest = createBuildArchiveManifest("jar-lib");
+      manifest = addArchiveEntry(manifest, { kind: "asset", path: "lib.jar", digest: "sha256:jar1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        path: "lib.jar.sbom.json",
+        digest: "sha256:sbomdoc",
+        mediaType: "application/spdx+json",
+        subjectDigest: "sha256:jar1",
+      });
+
+      // buildLedgerEntries only enumerates image-kind entries (the build
+      // ledger's historical scope, #568) — a jar's SBOM is still readable
+      // straight from the archive via findSbomForSubject, the same
+      // artifact-type-agnostic accessor ./build-ledger.ts uses internally.
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries).toEqual([]);
+      expect(findSbomForSubject(manifest, "sha256:jar1")).toMatchObject({ mediaType: "application/spdx+json" });
+    });
+
+    test("image entries surface their own reproducibility record (#614)", async () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:image1" });
+      const entries = await buildLedgerEntries(manifest);
+      expect(entries[0].reproducibility).toEqual({ basis: "best-effort" });
+    });
+  });
+
+  describe("artifactReproducibilitySummary (#614)", () => {
+    test("reports every image/template/asset entry's own reproducibility, honestly per artifact type", () => {
+      let manifest = createBuildArchiveManifest("search-service");
+      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: "asset", path: "lib.jar", digest: "sha256:jar1" });
+
+      const summary = artifactReproducibilitySummary(manifest);
+      const byPath = new Map(summary.map((s) => [s.path, s]));
+      expect(byPath.get("image.tar")?.reproducibility).toEqual({ basis: "best-effort" });
+      expect(byPath.get("search.template.json")?.reproducibility).toEqual({
+        basis: "deterministic-synthesis",
+        verifyBy: "re-synth",
+      });
+      expect(byPath.get("lib.jar")?.reproducibility).toEqual({ basis: "best-effort" });
+    });
+
+    test("excludes sbom-kind entries — they describe another artifact, they aren't one themselves", () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:img1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        path: "image.tar.sbom.json",
+        digest: "sha256:sbom1",
+        subjectDigest: "sha256:img1",
+      });
+      const summary = artifactReproducibilitySummary(manifest);
+      expect(summary.map((s) => s.path)).toEqual(["image.tar"]);
+    });
+
+    test("surfaces the recorded provenance sourceRef when present", () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, {
+        kind: "template",
+        path: "t.json",
+        digest: "sha256:t1",
+        provenance: { sourceRef: "abc123", artifactDigest: "sha256:t1" },
+      });
+      const summary = artifactReproducibilitySummary(manifest);
+      expect(summary[0]!.sourceRef).toBe("abc123");
+    });
+
+    test("no artifact entries -> empty summary", () => {
+      const manifest = createBuildArchiveManifest("empty");
+      expect(artifactReproducibilitySummary(manifest)).toEqual([]);
+    });
+  });
+
+  describe("componentBomSummary (#614)", () => {
+    test("undefined when the manifest carries no BOM at all", () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, { kind: "image", path: "image.tar", digest: "sha256:img1" });
+      expect(componentBomSummary(manifest)).toBeUndefined();
+    });
+
+    test("single leaf: isAssembly is false — a 1:1 component BOM", () => {
+      let manifest = createBuildArchiveManifest("infra-only");
+      manifest = addArchiveEntry(manifest, { kind: "template", path: "t.json", digest: "sha256:t1" });
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        bomKind: "config",
+        path: "t.json.config-bom.json",
+        digest: "sha256:sbom1",
+        subjectDigest: "sha256:t1",
+        mediaType: "application/spdx+json",
+        packageCount: 3,
+        generator: "chant-config-bom-extractor",
+      });
+
+      const summary = componentBomSummary(manifest);
+      expect(summary?.isAssembly).toBe(false);
+      expect(summary?.leaves).toHaveLength(1);
+      expect(summary?.leaves[0]).toEqual({
+        path: "t.json.config-bom.json",
+        bomKind: "config",
+        subjectDigest: "sha256:t1",
+        mediaType: "application/spdx+json",
+        packageCount: 3,
+        generator: "chant-config-bom-extractor",
+      });
+      expect(summary?.totalPackageCount).toBe(3);
+    });
+
+    test("multi leaf (software SBOM + config-BOM): isAssembly is true, totalPackageCount sums both leaves", () => {
+      let manifest = createBuildArchiveManifest("search-service");
+      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: 17,
+        generator: "syft",
+      });
+      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: 5,
+        generator: "chant-config-bom-extractor",
+      });
+
+      const summary = componentBomSummary(manifest);
+      expect(summary?.isAssembly).toBe(true);
+      expect(summary?.leaves).toHaveLength(2);
+      expect(summary?.totalPackageCount).toBe(22);
+      expect(summary?.leaves.map((l) => l.bomKind).sort()).toEqual(["config", "software"]);
+    });
+
+    test("bomKind defaults to 'software' when a leaf entry omits it, matching BuildArchiveEntry's own default", () => {
+      let manifest = createBuildArchiveManifest("svc");
+      manifest = addArchiveEntry(manifest, {
+        kind: "sbom",
+        path: "a.sbom.json",
+        digest: "sha256:s1",
+        subjectDigest: "sha256:img1",
+      });
+      const summary = componentBomSummary(manifest);
+      expect(summary?.leaves[0]?.bomKind).toBe("software");
+    });
+  });
+});

package/src/lifecycle/build-ledger.ts

@@ -0,0 +1,305 @@
+/**
+ * Build ledger — the "what's been built" half of build & deploy observability
+ * (#568, epic #551 "Build & deploy observability" / "4. Build archive +
+ * deferred publish"; SBOM consume/surface added in #606).
+ *
+ * The `BuildArchive` manifest (../components/verbs/build-archive.ts) is
+ * itself the build ledger: it is content-addressed by digest and enumerates
+ * every image/template/asset/sbom a build produced. What #568 adds on top is
+ * discovery of an image's **referrers** — the SBOM, SLSA provenance, and
+ * signature attached to the same digest by tooling like `oras discover
+ * <digest>` / `cosign tree` (epic #551's phrasing).
+ *
+ * This module only *surfaces and consumes* SBOM/provenance/signature
+ * evidence — generation is ../components/verbs/sbom.ts's `generate-sbom`
+ * capability (#606; SLSA provenance + signing remain out of scope, noted as
+ * fast-follow siblings). Two sources feed the same `sbom` summary below, and
+ * a caller gets *both* without special-casing which one exists:
+ *
+ *  - **archive-carried** — an `sbom`-kind entry in the same
+ *    `BuildArchiveManifest`, written directly by `generate-sbom`. This is
+ *    the **universal home**: it works for every artifact type (image, jar,
+ *    zip) and every publish backend, including the registry-less
+ *    `load-image-on-host` path, with no registry/network access required to
+ *    read it back.
+ *  - **referrer-projected** — an OCI referrer of `kind: "sbom"` discovered
+ *    via `ReferrerLookup`, the registry-side convenience for image
+ *    artifacts (`oras discover <digest>`/`cosign tree`) that #568 already
+ *    modeled. Not every artifact type has this projection (only images
+ *    published to a registry do), and not every environment can query it
+ *    (`ReferrerLookup` defaults to `noopReferrerLookup`, no network).
+ *
+ * `buildLedgerEntries` prefers the archive-carried copy when both exist
+ * (same digest either way, since both trace back to the same
+ * `generate-sbom` run — the archive is the source of truth; the referrer is
+ * a projection of it) and falls back to the referrer when only that is
+ * available (e.g. a manifest read that predates #606, or a third-party tool
+ * attached an SBOM directly to the registry outside chant's own build). The
+ * `ReferrerLookup` interface remains injectable for exactly the reason
+ * `CloudExecutor` is injectable elsewhere in ../components/verbs: no test and
+ * no default implementation shells out to a real `oras`/`cosign`/registry
+ * call.
+ *
+ * **#614 additions.** Two more things get surfaced per manifest, both
+ * derived from data the manifest already carries (no new generation, no
+ * re-parsing of BOM bytes):
+ *
+ *  - Each `BuildLedgerEntry` (still one per image, matching this module's
+ *    existing scope) now carries that image's own `reproducibility` — read
+ *    straight off its `BuildArchiveEntry`, never inferred from a sibling
+ *    artifact (see ../components/verbs/reproducibility.ts's module doc for
+ *    why a blanket flag would misrepresent a multi-artifact component).
+ *    `artifactReproducibilitySummary` below reports the same per-artifact
+ *    honesty for *every* artifact entry in a manifest (image, template,
+ *    asset alike) — the full per-artifact picture #614 asks for, not just
+ *    the image-scoped slice `buildLedgerEntries` has always covered.
+ *  - `componentBomSummary` reports the component-level BOM aggregation
+ *    picture (../components/verbs/component-bom.ts): how many leaf BOMs
+ *    (software SBOM + IaC config-BOM) the manifest carries, each one's
+ *    `bomKind`/format/package count, and whether they'd compose into a
+ *    single-artifact (1:1) or real multi-artifact assembly. This is a
+ *    summary read off the manifest's existing `sbom`-kind entries — it does
+ *    not regenerate or re-validate the aggregate document (that stays
+ *    `aggregateComponentBom`'s job, given each leaf's `BomPackage[]`, which
+ *    the manifest alone does not carry).
+ */
+
+import type { BuildArchiveManifest, BuildArchiveEntry } from "../components/verbs/build-archive";
+import { findSbomForSubject, imageEntries, sbomEntries, artifactEntries } from "../components/verbs/build-archive";
+import type { ArtifactReproducibility } from "../components/verbs/reproducibility";
+
+/** The kind of referrer artifact attached to an image digest (mirrors the OCI referrers API / `oras discover` output). */
+export type ReferrerKind = "sbom" | "provenance" | "signature";
+
+/** One referrer attached to an image digest. */
+export interface Referrer {
+  kind: ReferrerKind;
+  /** Media type of the referrer artifact itself (e.g. `application/vnd.cyclonedx+json`, `application/vnd.in-toto+json`). */
+  mediaType: string;
+  /** Content-addressed digest of the referrer artifact (`sha256:...`) — distinct from the subject digest it refers to. */
+  digest: string;
+  /** Where to fetch the referrer's content, when known (a registry blob ref, a file path, ...). Opaque to this module. */
+  location?: string;
+}
+
+/**
+ * Injectable lookup for an image digest's referrers — the seam a real
+ * `oras`/`cosign`/registry-API implementation plugs into. Defaults to
+ * `NoopReferrerLookup` (below) so build ledger queries degrade to "no
+ * referrers known" rather than requiring network/registry access, matching
+ * how ../components/verbs/cloud-executor.ts's real implementations are
+ * optional and mockable.
+ */
+export interface ReferrerLookup {
+  /** List every referrer attached to `digest`, or `[]` if none / lookup unsupported. */
+  discover(digest: string): Promise<Referrer[]>;
+}
+
+/** Default `ReferrerLookup`: reports no referrers. A real registry/`oras`-backed implementation is out of scope here (belongs with #564's signing follow-up) — this keeps build-ledger queries safe to run with no cloud/network access. */
+export const noopReferrerLookup: ReferrerLookup = {
+  async discover() {
+    return [];
+  },
+};
+
+/**
+ * Where a build-ledger entry's `sbom` summary was read from — surfaced so
+ * `chant components status` can report SBOM *source*, not just presence
+ * (#606). "avoid drift": whichever source answers, it traces back to the
+ * same `generate-sbom` run for a given digest, since promote-by-digest never
+ * rebuilds — see docs/components/build-archive.mdx.
+ */
+export type SbomSource = "archive" | "referrer";
+
+/**
+ * The SBOM summary `chant components status` surfaces for one build-ledger
+ * entry (#606): format, package count, and where it was read from — never
+ * the raw SBOM bytes (chant's job is to generate/store/surface, not to
+ * interpret SBOM content; that is the scan-result/VEX policy-gate
+ * fast-follow, out of scope here).
+ */
+export interface SbomSummary {
+  /** Media type of the SBOM document (`application/spdx+json` or `application/vnd.cyclonedx+json`) — the format-agnostic key, never a hardcoded format. */
+  mediaType: string;
+  /** Number of packages/components enumerated, when known. */
+  packageCount?: number;
+  /** Which tool produced it (e.g. "syft", "buildkit"), when known. */
+  generator?: string;
+  /** Whether this summary was read from the archive-carried entry or a registry-discovered OCI referrer. */
+  source: SbomSource;
+}
+
+/** One build-ledger entry: an archive's image entry plus whatever referrers are attached to its digest. */
+export interface BuildLedgerEntry {
+  /** Component the archive was built for. */
+  component: string;
+  /** Archive-relative path of the image entry (see `BuildArchiveEntry.path`). */
+  path: string;
+  /** Content-addressed digest of the image (`sha256:...`) — the join key with the release ledger. */
+  digest: string;
+  /** When the archive manifest was assembled. */
+  createdAt: string;
+  /** The manifest's own aggregate digest — traces a promoted image digest back to the exact manifest that produced it. */
+  manifestDigest: string;
+  /** SBOM/provenance/signature referrers attached to this image's digest, if any were discoverable. */
+  referrers: Referrer[];
+  /**
+   * SBOM summary for this digest, read from whichever source is available —
+   * the archive-carried `sbom`-kind manifest entry (preferred; works for
+   * every artifact type and every publish backend, registry or not) or a
+   * registry-discovered `sbom`-kind referrer (image artifacts only, when
+   * `lookup` can reach a registry). `undefined` when neither source has one
+   * — including when the component opted out of `generate-sbom` entirely.
+   */
+  sbom?: SbomSummary;
+  /**
+   * This image's own honest, per-artifact reproducibility record (#614) —
+   * read from its `BuildArchiveEntry.reproducibility`. An `image` entry
+   * defaults to `{ basis: "best-effort" }` (see
+   * ../components/verbs/reproducibility.ts's `defaultReproducibility`)
+   * absent a real reproducible-build attestation; never inferred from a
+   * sibling `template`/`asset` entry's basis.
+   */
+  reproducibility?: ArtifactReproducibility;
+}
+
+/**
+ * Build the ledger view for one archive manifest: every `image`-kind entry,
+ * each paired with its OCI referrers via `lookup` and its SBOM summary (read
+ * from the archive-carried entry first, the referrer projection otherwise —
+ * see this module's doc comment). "What's built" becomes "what's built, from
+ * which commit, by what, when" once a release record (./release-ledger.ts)
+ * is joined onto this by `digest` — this function only produces the build
+ * side of that join.
+ */
+export async function buildLedgerEntries(
+  manifest: BuildArchiveManifest,
+  lookup: ReferrerLookup = noopReferrerLookup,
+): Promise<BuildLedgerEntry[]> {
+  const images = imageEntries(manifest);
+  const entries: BuildLedgerEntry[] = [];
+  for (const image of images) {
+    const referrers = await lookup.discover(image.digest);
+
+    const archiveSbom = findSbomForSubject(manifest, image.digest);
+    const referrerSbom = findReferrer(referrers, "sbom");
+    const sbom: SbomSummary | undefined = archiveSbom
+      ? {
+          mediaType: archiveSbom.mediaType ?? "application/octet-stream",
+          packageCount: archiveSbom.packageCount,
+          generator: archiveSbom.generator,
+          source: "archive",
+        }
+      : referrerSbom
+        ? { mediaType: referrerSbom.mediaType, source: "referrer" }
+        : undefined;
+
+    entries.push({
+      component: manifest.component,
+      path: image.path,
+      digest: image.digest,
+      createdAt: manifest.createdAt,
+      manifestDigest: manifest.manifestDigest,
+      referrers,
+      sbom,
+      reproducibility: image.reproducibility,
+    });
+  }
+  return entries;
+}
+
+/** Find the referrer of a given kind for a digest, if any (a convenience for "does this build have a signature/SBOM/provenance"). */
+export function findReferrer(referrers: Referrer[], kind: ReferrerKind): Referrer | undefined {
+  return referrers.find((r) => r.kind === kind);
+}
+
+// ── #614: per-artifact reproducibility + component BOM summary ─────────────
+
+/** One artifact's reproducibility, named for display (`chant components status`) rather than just keyed by digest. */
+export interface ArtifactReproducibilitySummary {
+  /** Archive-relative path of the artifact (`BuildArchiveEntry.path`). */
+  path: string;
+  /** Which kind of artifact this is. */
+  kind: BuildArchiveEntry["kind"];
+  /** Content-addressed digest of the artifact. */
+  digest: string;
+  /** The artifact's own reproducibility record, when one is recorded (absent only for `sbom`-kind entries, which describe another artifact rather than being one). */
+  reproducibility?: ArtifactReproducibility;
+  /** Source ref/commit that produced this artifact, when recorded (#614's provenance link). */
+  sourceRef?: string;
+}
+
+/**
+ * Report every artifact entry's (`image`/`template`/`asset`) own
+ * reproducibility + provenance, honestly per-artifact — the full picture
+ * #614 asks for, wider than `buildLedgerEntries`'s image-only scope. Order
+ * matches `artifactEntries`' manifest insertion order; sort by `path`
+ * yourself for a stable display order (mirroring
+ * `computeManifestDigest`'s own path-sort convention).
+ */
+export function artifactReproducibilitySummary(manifest: BuildArchiveManifest): ArtifactReproducibilitySummary[] {
+  return artifactEntries(manifest).map((entry) => ({
+    path: entry.path,
+    kind: entry.kind,
+    digest: entry.digest,
+    reproducibility: entry.reproducibility,
+    sourceRef: entry.provenance?.sourceRef,
+  }));
+}
+
+/** One leaf BOM in a component's aggregation picture — the summary form `componentBomSummary` reports, without regenerating or re-validating the aggregate document itself. */
+export interface ComponentBomLeafSummary {
+  /** Archive-relative path of the leaf BOM document. */
+  path: string;
+  /** Software SBOM or IaC config-BOM (#613's `bomKind`, defaulting to `"software"` the same way `BuildArchiveEntry.bomKind` does). */
+  bomKind: "software" | "config";
+  /** Digest of the artifact this leaf describes (`subjectDigest`), when recorded. */
+  subjectDigest?: string;
+  /** Media type of the leaf document (format-agnostic key, per #613's convention). */
+  mediaType: string;
+  /** Package/component count this leaf enumerates, when known. */
+  packageCount?: number;
+  /** Which tool produced this leaf, when known. */
+  generator?: string;
+}
+
+/**
+ * Summary of a component's BOM aggregation picture (#614,
+ * ../components/verbs/component-bom.ts): every leaf BOM the manifest
+ * carries, whether they compose 1:1 (a single-artifact component — the leaf
+ * BOM *is* the component BOM, structurally) or as a real multi-artifact
+ * assembly (2+ leaves), and the combined package count across every leaf.
+ */
+export interface ComponentBomSummary {
+  /** Every leaf BOM (software SBOM + IaC config-BOM) the manifest carries. */
+  leaves: ComponentBomLeafSummary[];
+  /** Sum of every leaf's `packageCount` (0 for a leaf with an unknown count). */
+  totalPackageCount: number;
+  /** `false` when there are 0 or 1 leaves (nothing to assemble, or a 1:1 component BOM); `true` when there are 2+ leaves (a real multi-artifact assembly, per #614's "single-artifact = 1:1, multi-artifact = a real assembly"). */
+  isAssembly: boolean;
+}
+
+/**
+ * Build the component BOM summary for one manifest, straight from its
+ * existing `sbom`-kind entries — no regeneration, no re-parsing of BOM
+ * bytes. `undefined` when the manifest carries no BOM at all (a component
+ * that composed neither `generate-sbom` nor `extract-config-bom` — skipping
+ * is structural, matching every other BOM consumer's convention in this
+ * codebase).
+ */
+export function componentBomSummary(manifest: BuildArchiveManifest): ComponentBomSummary | undefined {
+  const boms = sbomEntries(manifest);
+  if (boms.length === 0) return undefined;
+
+  const leaves: ComponentBomLeafSummary[] = boms.map((entry) => ({
+    path: entry.path,
+    bomKind: entry.bomKind ?? "software",
+    subjectDigest: entry.subjectDigest,
+    mediaType: entry.mediaType ?? "application/octet-stream",
+    packageCount: entry.packageCount,
+    generator: entry.generator,
+  }));
+  const totalPackageCount = leaves.reduce((sum, l) => sum + (l.packageCount ?? 0), 0);
+
+  return { leaves, totalPackageCount, isAssembly: leaves.length > 1 };
+}