@intentius/chant 0.124.12 → 0.124.14

package/dist/components/verbs/bom-writer.js

@@ -0,0 +1,287 @@
+/**
+ * Native JSON BOM writer (#613, epic #551 follow-up to #606). Pure
+ * TypeScript, no external binaries (no `syft`/`buildx --sbom`/`cyclonedx-maven`/
+ * `oras`/`cosign`), no network — every document below is assembled entirely
+ * from in-memory data and `JSON.stringify`.
+ *
+ * This module is the shared serialization core both real `SbomGenerator`
+ * backends in this directory build on: the software leaf
+ * (./lockfile-sbom-generator.ts, lockfile/manifest-derived package lists) and
+ * the IaC leaf (./config-bom.ts, synthesized-template-derived component
+ * lists). Neither backend hand-rolls its own SPDX/CycloneDX shape — both
+ * call `writeSpdx`/`writeCycloneDx` here so the two document standards have
+ * exactly one writer each in the whole codebase.
+ *
+ * **Why hand-write the JSON instead of a library.** No SPDX/CycloneDX SDK is
+ * a dependency of this package (matching ./cloud-executor.ts's stance on the
+ * AWS SDK: shell out or hand-roll rather than add a heavy dependency for a
+ * narrow need). Both standards' JSON forms are simple enough — a handful of
+ * required top-level fields plus an array of package/component records — that
+ * a ~100-line writer is more auditable than a dependency. Structural
+ * correctness (required fields, enum values) is verified in
+ * ./bom-writer.test.ts against each standard's own published JSON Schema
+ * (vendored as devDep test fixtures, the same convention #553 used for the
+ * Component contract schema — see ./__fixtures__/schemas/).
+ *
+ * **Format decisions, recorded for reviewers:**
+ *  - SPDX **2.3** (not 2.2 or 3.0): 2.3 is what BuildKit's native `--sbom`
+ *    attestation emits (referenced in ./sbom-generator.ts's module doc), so
+ *    matching that version keeps a future BuildKit-backed `forImage` and this
+ *    lockfile-backed backend speaking the same SPDX dialect. SPDX 3.0 is a
+ *    substantially different (JSON-LD/RDF-shaped) model not yet the de facto
+ *    tooling default as of this writing.
+ *  - CycloneDX **1.5** (not 1.4 or 1.6): 1.5 is the version most broadly
+ *    supported by consumer tooling (Dependency-Track, `cyclonedx-cli`) at
+ *    time of writing and has a stable published JSON Schema; 1.6 adds fields
+ *    this writer doesn't need yet.
+ *  - `documentNamespace`/`serialNumber` are deterministic, derived from the
+ *    subject's digest/path rather than a random UUID, so two BOM generations
+ *    of byte-identical inputs produce byte-identical documents — the same
+ *    content-addressing property ./build-archive.ts's `contentDigest`
+ *    depends on for its "identical inputs -> identical manifest digest"
+ *    guarantee (see ./sbom.test.ts's existing test of that property).
+ *
+ * **Assembly (#614).** `BomInput.subDocuments`, when present, projects each
+ * sub-document as a real nested unit rather than flattening its packages into
+ * the root's own list — CycloneDX's `metadata.component.components` +
+ * `compositions` (`aggregate: "incomplete"`, since a component BOM only
+ * composes the leaf BOMs it was given, never a closed-world claim over
+ * everything the artifact might contain), SPDX's `hasFiles`-style `CONTAINS`
+ * relationship from the root package to each sub-document's own root package
+ * plus that sub-document's own `DEPENDS_ON` edges. This is what
+ * ./component-bom.ts's `aggregateComponentBom` uses to compose a component's
+ * leaf BOMs (a software SBOM plus an IaC config-BOM) into one document
+ * without flattening away which packages came from which leaf — still one
+ * writer per standard, extended rather than duplicated.
+ */
+import { SBOM_MEDIA_TYPES } from "./sbom-generator.js";
+/** Deterministic, dependency-free short hash used to derive stable SPDX document namespaces / CycloneDX serial numbers from `BomInput.subjectId`. Not a security hash — just stable and collision-unlikely enough for a namespace suffix. */
+function stableId(input) {
+    let hash = 0;
+    for (let i = 0; i < input.length; i++) {
+        hash = (Math.imul(hash, 31) + input.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(16).padStart(8, "0");
+}
+/** SPDX identifiers may only contain letters, digits, `.`, and `-` (SPDX-2.3 §2.2). */
+function spdxSafeId(name) {
+    return name.replace(/[^a-zA-Z0-9.-]/g, "-");
+}
+// ── SPDX-2.3 JSON ────────────────────────────────────────────────────────────
+/**
+ * Build one SPDX package record + its `DEPENDS_ON` relationship edges for a
+ * flat package list, with SPDX IDs namespaced under `idPrefix` so a
+ * sub-document's packages (#614 assembly) never collide with the root's own
+ * or another sub-document's, even when two leaf BOMs happen to enumerate a
+ * same-named package.
+ */
+function spdxPackagesAndDeps(packages, idPrefix) {
+    const spdxId = (name) => `SPDXRef-Package-${idPrefix}${spdxSafeId(name)}`;
+    const pkgs = packages.map((pkg) => ({
+        name: pkg.name,
+        SPDXID: spdxId(pkg.name),
+        versionInfo: pkg.version ?? "NOASSERTION",
+        downloadLocation: pkg.downloadLocation ?? "NOASSERTION",
+        filesAnalyzed: false,
+        licenseConcluded: "NOASSERTION",
+        licenseDeclared: "NOASSERTION",
+        copyrightText: "NOASSERTION",
+        ...(pkg.purl
+            ? {
+                externalRefs: [
+                    { referenceCategory: "PACKAGE-MANAGER", referenceType: "purl", referenceLocator: pkg.purl },
+                ],
+            }
+            : {}),
+    }));
+    const relationships = packages.flatMap((pkg) => (pkg.dependsOn ?? []).map((dep) => ({
+        spdxElementId: spdxId(pkg.name),
+        relationshipType: "DEPENDS_ON",
+        relatedSpdxElement: spdxId(dep),
+    })));
+    return { packages: pkgs, relationships };
+}
+/**
+ * Native SPDX-2.3 JSON writer. Emits the required top-level fields
+ * (`spdxVersion`, `dataLicense`, `SPDXID`, `name`, `documentNamespace`,
+ * `creationInfo`, `packages`) plus a `relationships` array recording the
+ * document's `DESCRIBES` edge to the subject package and each package's
+ * declared `DEPENDS_ON` edges — the "valid relationships section where
+ * applicable" #613 calls for.
+ *
+ * When `input.subDocuments` is present (#614 assembly), each sub-document's
+ * own root package is emitted alongside the top-level subject, linked from
+ * the top-level subject via a `CONTAINS` relationship, with that
+ * sub-document's own packages and `DEPENDS_ON` edges nested under an
+ * SPDX-ID namespace unique to it (`SPDXRef-Package-sub<n>-...`) so packages
+ * from different leaf BOMs never collide even if same-named.
+ */
+export function writeSpdx(input, now = () => new Date()) {
+    const rootId = "SPDXRef-DOCUMENT";
+    const subjectSpdxId = `SPDXRef-Package-${spdxSafeId(input.subjectName)}`;
+    const { packages, relationships: packageRelationships } = spdxPackagesAndDeps(input.packages, "");
+    const relationships = [
+        { spdxElementId: rootId, relationshipType: "DESCRIBES", relatedSpdxElement: subjectSpdxId },
+        ...packageRelationships,
+    ];
+    const subDocumentPackages = [];
+    (input.subDocuments ?? []).forEach((sub, i) => {
+        const subRootId = `SPDXRef-Package-sub${i}-${spdxSafeId(sub.subjectName)}`;
+        subDocumentPackages.push({
+            name: sub.subjectName,
+            SPDXID: subRootId,
+            versionInfo: sub.subjectVersion ?? "NOASSERTION",
+            downloadLocation: "NOASSERTION",
+            filesAnalyzed: false,
+            licenseConcluded: "NOASSERTION",
+            licenseDeclared: "NOASSERTION",
+            copyrightText: "NOASSERTION",
+            comment: `subjectId: ${sub.subjectId}`,
+        });
+        relationships.push({
+            spdxElementId: subjectSpdxId,
+            relationshipType: "CONTAINS",
+            relatedSpdxElement: subRootId,
+        });
+        const { packages: subPkgs, relationships: subRels } = spdxPackagesAndDeps(sub.packages, `sub${i}-`);
+        subDocumentPackages.push(...subPkgs);
+        relationships.push(
+        // CONTAINS (not DEPENDS_ON): membership in this leaf BOM, not a
+        // literal dependency edge — the leaf's own DEPENDS_ON edges (from
+        // BomPackage.dependsOn) are `subRels`, pushed separately below.
+        ...subPkgs.map((p) => ({
+            spdxElementId: subRootId,
+            relationshipType: "CONTAINS",
+            relatedSpdxElement: p.SPDXID,
+        })), ...subRels);
+    });
+    const document = {
+        spdxVersion: "SPDX-2.3",
+        dataLicense: "CC0-1.0",
+        SPDXID: rootId,
+        name: input.subjectName,
+        documentNamespace: `https://chant.dev/spdxdocs/${spdxSafeId(input.subjectName)}-${stableId(input.subjectId)}`,
+        creationInfo: {
+            created: now().toISOString(),
+            creators: [`Tool: ${input.generator}`],
+        },
+        packages: [
+            {
+                name: input.subjectName,
+                SPDXID: subjectSpdxId,
+                versionInfo: input.subjectVersion ?? "NOASSERTION",
+                downloadLocation: "NOASSERTION",
+                filesAnalyzed: false,
+                licenseConcluded: "NOASSERTION",
+                licenseDeclared: "NOASSERTION",
+                copyrightText: "NOASSERTION",
+            },
+            ...packages,
+            ...subDocumentPackages,
+        ],
+        relationships,
+    };
+    return JSON.stringify(document, null, 2);
+}
+// ── CycloneDX-1.5 JSON ───────────────────────────────────────────────────────
+/** Project a flat package list into CycloneDX `components`, with `bom-ref`s namespaced under `refPrefix` so a sub-document's components (#614 assembly) never collide with the root's own or another sub-document's. */
+function cycloneDxComponents(packages, refPrefix) {
+    return packages.map((pkg) => ({
+        type: pkg.type === "config" ? "application" : "library",
+        "bom-ref": `${refPrefix}${pkg.name}`,
+        name: pkg.name,
+        ...(pkg.version ? { version: pkg.version } : {}),
+        ...(pkg.purl ? { purl: pkg.purl } : {}),
+    }));
+}
+/** Project a flat package list's `dependsOn` edges into CycloneDX `dependencies` entries, `bom-ref`s namespaced the same way `cycloneDxComponents` namespaces its components. */
+function cycloneDxDependencies(packages, refPrefix) {
+    return packages
+        .filter((p) => (p.dependsOn?.length ?? 0) > 0)
+        .map((p) => ({ ref: `${refPrefix}${p.name}`, dependsOn: p.dependsOn.map((d) => `${refPrefix}${d}`) }));
+}
+/**
+ * Native CycloneDX-1.5 JSON writer. Emits the required top-level fields
+ * (`bomFormat`, `specVersion`, `serialNumber`, `version`, `metadata`,
+ * `components`) plus a `dependencies` array recording the root subject's
+ * direct dependencies and each component's own declared dependencies.
+ *
+ * When `input.subDocuments` is present (#614 assembly), each sub-document is
+ * projected as a real nested component under `metadata.component.components`
+ * (CycloneDX's own "hierarchical representation of component assemblies,
+ * similar to system -> subsystem -> parts" per its schema doc) — never
+ * flattened into the root's own `components` array — with a `compositions`
+ * entry recording the aggregate as `"incomplete"` (this document composes
+ * exactly the leaf BOMs it was given, not a closed-world claim over
+ * everything the artifact might contain) and a root `dependencies` edge from
+ * the top-level subject to each sub-document's root.
+ */
+export function writeCycloneDx(input, now = () => new Date()) {
+    const rootRef = `subject:${input.subjectName}`;
+    const components = cycloneDxComponents(input.packages, "");
+    const subDocuments = input.subDocuments ?? [];
+    const subComponents = subDocuments.map((sub, i) => {
+        const refPrefix = `sub${i}:`;
+        const subRef = `${refPrefix}subject:${sub.subjectName}`;
+        return {
+            type: "application",
+            "bom-ref": subRef,
+            name: sub.subjectName,
+            ...(sub.subjectVersion ? { version: sub.subjectVersion } : {}),
+            properties: [{ name: "chant:subjectId", value: sub.subjectId }],
+            components: cycloneDxComponents(sub.packages, refPrefix),
+        };
+    });
+    const subDependencies = subDocuments.flatMap((sub, i) => {
+        const refPrefix = `sub${i}:`;
+        const subRef = `${refPrefix}subject:${sub.subjectName}`;
+        return [
+            { ref: subRef, dependsOn: sub.packages.map((p) => `${refPrefix}${p.name}`) },
+            ...cycloneDxDependencies(sub.packages, refPrefix),
+        ];
+    });
+    // Root subject depends on its own flat packages plus, when this is an
+    // assembly (#614), each sub-document's own root — one entry, not two, so
+    // the root ref never appears twice in `dependencies`.
+    const rootDependsOn = [...input.packages.map((p) => p.name), ...subComponents.map((c) => c["bom-ref"])];
+    const dependencies = [
+        { ref: rootRef, dependsOn: rootDependsOn },
+        ...cycloneDxDependencies(input.packages, ""),
+        ...subDependencies,
+    ];
+    const compositions = subDocuments.length > 0
+        ? [{ aggregate: "incomplete", assemblies: [rootRef, ...subComponents.map((c) => c["bom-ref"])] }]
+        : undefined;
+    const document = {
+        bomFormat: "CycloneDX",
+        specVersion: "1.5",
+        serialNumber: `urn:uuid:${toUuidLike(stableId(input.subjectId) + stableId(input.subjectName))}`,
+        version: 1,
+        metadata: {
+            timestamp: now().toISOString(),
+            tools: [{ name: input.generator }],
+            component: {
+                type: "application",
+                "bom-ref": rootRef,
+                name: input.subjectName,
+                ...(input.subjectVersion ? { version: input.subjectVersion } : {}),
+                ...(subComponents.length > 0 ? { components: subComponents } : {}),
+            },
+        },
+        components,
+        dependencies,
+        ...(compositions ? { compositions } : {}),
+    };
+    return JSON.stringify(document, null, 2);
+}
+/** Format an 8-hex-char stable id into a UUID-shaped (but not random/RFC-4122-compliant) string, since CycloneDX only requires `serialNumber` to match `urn:uuid:<uuid-form>` syntactically, not to be a real random UUID — determinism matters more here than entropy. */
+function toUuidLike(seed) {
+    const padded = (seed + seed + seed + seed).slice(0, 32);
+    return `${padded.slice(0, 8)}-${padded.slice(8, 12)}-4${padded.slice(13, 16)}-8${padded.slice(17, 20)}-${padded.slice(20, 32)}`;
+}
+// ── format dispatch ──────────────────────────────────────────────────────────
+/** Serialize `input` in the requested `format` and wrap it as the project-wide `{ format, mediaType, bytes }` doc shape (./sbom-generator.ts's `SbomDocument`, minus `generator`/`packageCount` which the caller fills in). */
+export function writeBom(format, input, now) {
+    const bytes = format === "spdx" ? writeSpdx(input, now) : writeCycloneDx(input, now);
+    return { format, mediaType: SBOM_MEDIA_TYPES[format], bytes };
+}

package/dist/components/verbs/build-archive.js

@@ -0,0 +1,188 @@
+/**
+ * BuildArchive format — the self-contained bundle `docker-build` (and the
+ * other build-family verbs) write into (#564, epic #551 "4. Build archive +
+ * deferred publish"). See docs/components/build-archive.mdx.
+ *
+ * A build archive holds four kinds of contents, enumerated by one manifest:
+ *  - `image` — an image tarball in OCI layout (as `docker save` produces),
+ *    content-addressed by its digest.
+ *  - `template` — a synthesized deploy template (e.g. a CloudFormation
+ *    document) referenced by `cfn-deploy`'s `archive:<name>` convention
+ *    (see ../verbs/apply.ts's `CfnDeployInput.template`). Per #613, a
+ *    `template` entry is a first-class artifact with its own content
+ *    digest — peer to `image`/`asset` — so it can itself be the
+ *    `subjectDigest` a `sbom`-kind entry (specifically a config-BOM,
+ *    `bomKind: "config"`) is attached to.
+ *  - `asset` — any other published artifact (a jar, a zip) the `publish`
+ *    family's non-image backends (`publish-artifact`) promote.
+ *  - `sbom` — a Bill of Materials attached to another entry's digest (#606,
+ *    #613, epic #551 follow-up to #564/#568), written by either the
+ *    `generate-sbom` capability (./sbom.ts, a **software** BOM over an
+ *    image/jar/zip/dir) or the `extract-config-bom` capability
+ *    (./config-bom.ts, a **config-BOM** over a synthesized IaC template's
+ *    declared resources/nested stacks/external references). `bomKind`
+ *    distinguishes the two without introducing a separate entry kind — both
+ *    are content-addressed, digest-linked BOM documents, and every existing
+ *    `sbom`-kind consumer (`findSbomForSubject`, the build ledger) keeps
+ *    working unmodified for either kind. The archive is the **universal
+ *    home** for both: an image's SBOM may also be projected as an OCI
+ *    referrer at publish time (a registry-side convenience for `oras
+ *    discover`/`cosign tree`), but the archive-carried copy is what makes
+ *    non-image artifacts (a jar in S3, a zip, a template) and registry-less
+ *    deploys (`load-image-on-host`) work identically — no registry required
+ *    to read a build's BOM back.
+ *
+ * The manifest is itself content-addressed (`manifestDigest`, a stable hash
+ * over its entries) so two builds of the same inputs produce the same
+ * archive identity, and so a promoted digest can be traced back to exactly
+ * the manifest that produced it. Nothing here shells out or touches a real
+ * filesystem/docker daemon — manifest assembly is pure data, which is what
+ * lets `docker-build` (./build.ts) and `publish-image`/`load-image-on-host`
+ * (./publish.ts) build and promote an archive entirely through the injectable
+ * `CloudExecutor`, exercised in tests via `MockCloudExecutor` with no real
+ * disk/docker/AWS involved. The same is true of `generate-sbom` (./sbom.ts)
+ * and the injectable `SbomGenerator` (./sbom-generator.ts).
+ *
+ * Per #614, every `image`/`template`/`asset` entry also carries an honest,
+ * per-artifact `reproducibility` record and an optional `provenance`
+ * source->output link (see ./reproducibility.ts) — never a single blanket
+ * flag hoisted to the component, since a component that builds more than one
+ * artifact type (an image plus a synthesized template, say) has a different
+ * true answer for each.
+ */
+import { defaultReproducibility } from "./reproducibility.js";
+import { contentDigest } from "../../content-digest.js";
+import { canonicalJson } from "../../effect-receipt.js";
+/**
+ * Fallback media type per entry `kind`, used only when a caller omits
+ * `mediaType` on `addArchiveEntry`. `sbom` has no single default here by
+ * design — SPDX and CycloneDX are both first-class (#606) and the actual
+ * media type always comes from the `SbomDocument` the `generate-sbom`
+ * capability produced (./sbom-generator.ts); this fallback exists only so a
+ * malformed/omitted call doesn't produce an entry with no media type at all.
+ */
+const DEFAULT_MEDIA_TYPES = {
+    image: "application/vnd.oci.image.layout.v1.tar",
+    template: "application/json",
+    asset: "application/octet-stream",
+    sbom: "application/spdx+json",
+};
+/**
+ * The content digest every entry chant computes itself carries: real
+ * SHA-256 over the UTF-8 bytes of its input (../../content-digest.ts,
+ * chant #2514). Callers that digest content that never goes through the
+ * `CloudExecutor` (a synthesized template's serialized bytes, see ./build.ts's
+ * `addArchiveTemplate`, or an SBOM) use it. Production `image`/`asset`
+ * entries instead carry the digest their producing capability already
+ * computed (e.g. `docker-build`'s `executor.docker.build` digest).
+ */
+export { contentDigest };
+/**
+ * Compute the aggregate `manifestDigest` over a set of entries. Each entry
+ * contributes its `kind`, `path` and `digest`; entries are sorted by path
+ * (UTF-16 code units, the order `canonicalJson` sorts keys in) so entry order
+ * never changes the digest, only content does. The list is hashed as
+ * `canonicalJson`, so no path or digest can be read as a field separator.
+ */
+export function computeManifestDigest(contents) {
+    const sorted = contents
+        .map((e) => ({ kind: e.kind, path: e.path, digest: e.digest }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return contentDigest(canonicalJson(sorted));
+}
+/** Start a new, empty manifest for `component`. Entries are added with `addArchiveEntry`. */
+export function createBuildArchiveManifest(component, opts) {
+    const createdAt = (opts?.now ?? (() => new Date()))().toISOString();
+    return { version: 1, component, createdAt, contents: [], manifestDigest: computeManifestDigest([]) };
+}
+/**
+ * Add (or replace, by `path`) one entry and return a new manifest with
+ * `manifestDigest` recomputed. Pure/immutable so callers (and tests) can hold
+ * onto a manifest snapshot before/after a step without aliasing surprises.
+ *
+ * Assigns a kind-appropriate default `reproducibility` (#614,
+ * `defaultReproducibility`) when the caller omits one — `template` entries
+ * default to `deterministic-synthesis`, `image`/`asset` entries default to
+ * `best-effort`, and `sbom` entries get none. An explicit `entry.reproducibility`
+ * (e.g. a future reproducible-build-attested image) always wins over the
+ * default. `reproducibility`/`provenance` are never part of
+ * `computeManifestDigest`'s input — they describe the artifact, they are not
+ * content the artifact's identity depends on, so recording/correcting them
+ * later never perturbs `manifestDigest`.
+ */
+export function addArchiveEntry(manifest, entry) {
+    const reproducibility = entry.reproducibility ??
+        (entry.kind === "image" || entry.kind === "template" || entry.kind === "asset" || entry.kind === "sbom"
+            ? defaultReproducibility(entry.kind)
+            : undefined);
+    const resolved = {
+        mediaType: DEFAULT_MEDIA_TYPES[entry.kind],
+        ...entry,
+        ...(reproducibility ? { reproducibility } : {}),
+    };
+    const contents = [...manifest.contents.filter((e) => e.path !== resolved.path), resolved];
+    return { ...manifest, contents, manifestDigest: computeManifestDigest(contents) };
+}
+/** Look up one entry by archive-relative path (the same path form `cfn-deploy`'s `archive:<path>` and `publish-image`'s `from` use). */
+export function findArchiveEntry(manifest, path) {
+    return manifest.contents.find((e) => e.path === path);
+}
+/**
+ * Strip the `archive:` prefix chant's step wiring uses
+ * (e.g. `cfn-deploy`'s `template: "archive:search.template.json"`) down to
+ * the manifest-relative path. Returns the input unchanged when it carries no
+ * such prefix (a plain filesystem path outside the archive).
+ */
+export function archiveRelativePath(ref) {
+    return ref.startsWith("archive:") ? ref.slice("archive:".length) : ref;
+}
+/** All `image`-kind entries in a manifest — what a publish backend has to choose from when `from` is ambiguous/omitted. */
+export function imageEntries(manifest) {
+    return manifest.contents.filter((e) => e.kind === "image");
+}
+/** All `sbom`-kind entries in a manifest, regardless of which artifact they describe (#606). */
+export function sbomEntries(manifest) {
+    return manifest.contents.filter((e) => e.kind === "sbom");
+}
+/**
+ * Find the archive-carried SBOM entry attached to a given artifact digest
+ * (an `image`/`asset` entry's `digest` elsewhere in the same manifest). This
+ * is the archive-native lookup ../../lifecycle/build-ledger.ts's
+ * `buildLedgerEntries` uses to surface "SBOM by digest" without any registry
+ * or `oras`/network access — the archive is the universal home for the SBOM
+ * regardless of artifact type (#606).
+ */
+export function findSbomForSubject(manifest, subjectDigest) {
+    return manifest.contents.find((e) => e.kind === "sbom" && e.subjectDigest === subjectDigest);
+}
+/**
+ * Find the archive-carried **config-BOM** entry (`bomKind: "config"`)
+ * attached to a given template digest — the config-BOM analogue of
+ * `findSbomForSubject` (#613). A `template` entry's digest is computed the
+ * same way an `image`/`asset` entry's is (`contentDigest` over its bytes,
+ * see `addArchiveTemplate` in ./build.ts), so config-only/infra components
+ * with no software artifact still resolve a BOM by digest through the same
+ * lookup shape as every other artifact kind.
+ */
+export function findConfigBomForSubject(manifest, subjectDigest) {
+    return manifest.contents.find((e) => e.kind === "sbom" && e.bomKind === "config" && e.subjectDigest === subjectDigest);
+}
+/** All `template`-kind entries in a manifest — every synthesized IaC document the archive carries, each a first-class artifact with its own content digest (#613). */
+export function templateEntries(manifest) {
+    return manifest.contents.filter((e) => e.kind === "template");
+}
+/** All `asset`-kind entries in a manifest (non-image published artifacts — a jar, a zip). */
+export function assetEntries(manifest) {
+    return manifest.contents.filter((e) => e.kind === "asset");
+}
+/**
+ * Every artifact entry in a manifest — `image`, `template`, and `asset`
+ * kinds, excluding `sbom` entries (which describe an artifact rather than
+ * being one) — the set #614's per-artifact reproducibility surface iterates
+ * over. Order is manifest insertion order; callers that need a stable order
+ * for display/JSON output sort by `path` themselves (mirroring
+ * `computeManifestDigest`'s own path-sort convention).
+ */
+export function artifactEntries(manifest) {
+    return manifest.contents.filter((e) => e.kind !== "sbom");
+}

package/dist/components/verbs/build.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { defaultCloudExecutor } from "./cloud-executor.js";
+import { defaultProcessRunner, q } from "./process-runner.js";
+import { addArchiveEntry, contentDigest, createBuildArchiveManifest, } from "./build-archive.js";
+/**
+ * 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 = defaultCloudExecutor()) {
+    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 = 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 = createDockerBuildCapability();
+/**
+ * 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) {
+    const digest = contentDigest(input.content);
+    const base = input.manifest ?? createBuildArchiveManifest("unknown");
+    const provenance = input.sourceRef
+        ? { sourceRef: input.sourceRef, artifactDigest: digest }
+        : undefined;
+    const manifest = addArchiveEntry(base, {
+        kind: "template",
+        path: input.path,
+        digest,
+        ...(provenance ? { provenance } : {}),
+    });
+    return { digest, manifest };
+}
+/**
+ * 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 = defaultProcessRunner()) {
+    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 = createZipPackageCapability();
+/**
+ * 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 = defaultProcessRunner()) {
+    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 = createJvmBuildCapability();