@intentius/chant 0.13.0 → 0.15.0

package/dist/lifecycle/build-ledger-store.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Build-archive manifest store (#609, epic #551 follow-up to #564/#568/#606/
+ * #613/#614): persists a `BuildArchiveManifest`
+ * (../components/verbs/build-archive.ts) to a durable, content-addressed
+ * location so it survives past the in-process build/run that assembled it.
+ *
+ * **The gap this closes.** `docker-build` (../components/verbs/build.ts) and
+ * friends assemble a real `BuildArchiveManifest` in memory — complete with
+ * `sbom`/config-BOM entries (#606/#613) and per-artifact
+ * `reproducibility`/`provenance` (#614) — but nothing ever wrote it anywhere
+ * durable. `build-ledger.ts`'s `buildLedgerEntries`/`componentBomSummary` are
+ * unit-tested against a manifest handed to them directly, but
+ * `chant components status` (../cli/handlers/components.ts) had no manifest
+ * to hand them at all: `componentBom` and `build.reproducibility` were always
+ * `null` in that CLI path. This module is the missing durable layer — write
+ * once at build time, read back by digest at status time.
+ *
+ * **Storage choice: the `chant/lifecycle` orphan branch, a sibling namespace
+ * to the release ledger.** Reuses the exact git-plumbing
+ * `writeBlobToPath`/`readBlobFromPath`/`listFilesInDir` (./git.ts) that
+ * `writeSnapshot`/`appendReleaseRecordLine` already use — same hash-object →
+ * mktree → commit-tree → update-ref pipeline, same `--force-with-lease` push
+ * discipline (`pushLifecycle`), same "no checkout, no working tree changes"
+ * property. Rejected alternatives:
+ *  - **A new on-disk directory in the working tree** — would need its own
+ *    persistence/sync story (commit it? gitignore it? sync across CI
+ *    runners?) that the orphan branch already solves for the release ledger;
+ *    introducing a second mechanism for a manifest that is conceptually the
+ *    same kind of durable, git-native record would be needless divergence.
+ *  - **A path under `<env>/`** — a build archive is *not* env-scoped. The
+ *    whole point of promote-by-digest (epic #551 "4. Build archive +
+ *    deferred publish") is that one build's manifest is referenced from
+ *    every environment it gets promoted to; writing it under a single env
+ *    directory would either duplicate it per env (defeating "byte-identical
+ *    across envs") or arbitrarily pick one env as "the" owner. Manifests
+ *    instead live under a fixed top-level `_builds/` directory on the same
+ *    orphan branch, keyed by `manifestDigest` — a peer of the per-env
+ *    directories `writeSnapshot`/the release ledger already create there,
+ *    never nested inside one.
+ *
+ * **Content-addressed, keyed by `manifestDigest`.** One file per manifest,
+ * `_builds/<manifestDigest-with-":"->"_">.json`, so a rebuild of
+ * byte-identical inputs (same `manifestDigest`, per
+ * ../components/verbs/build-archive.ts's module doc) overwrites its own
+ * entry with identical content rather than accumulating duplicates —
+ * `writeBlobToPath` already replaces-by-path, so this falls out for free.
+ * `findBuildManifestByArtifactDigest` additionally resolves "the manifest
+ * that produced artifact digest X" (the join key `chant components status`
+ * actually has on hand — a `ReleaseRecord.digest` is an *artifact* digest,
+ * not a manifest digest) by scanning every stored manifest's `contents` for
+ * a matching entry. This is a linear scan over however many manifests have
+ * been persisted; fine for the ledger's expected scale (one manifest per
+ * build), and avoids maintaining a second reverse-index file that could get
+ * out of sync with the manifests themselves.
+ */
+import type { BuildArchiveManifest } from "../components/verbs/build-archive.js";
+/**
+ * Persist a `BuildArchiveManifest` to the orphan branch, keyed by its own
+ * `manifestDigest`. Does not push to the remote — call `pushLifecycle`
+ * (./git.ts) afterward, the same two-step (`write` then `push`) shape
+ * `appendReleaseRecord`/`takeSnapshot` use, so a caller persisting several
+ * manifests (or a manifest plus a release record) in one run can batch the
+ * push into one network round-trip.
+ *
+ * Idempotent: persisting the same manifest twice (identical `manifestDigest`)
+ * overwrites the same path with identical bytes — safe to call more than
+ * once for the same build.
+ */
+export declare function persistBuildManifest(manifest: BuildArchiveManifest, opts?: {
+    cwd?: string;
+}): Promise<{
+    commit: string;
+}>;
+/**
+ * Read a persisted `BuildArchiveManifest` back by its own `manifestDigest`.
+ * Returns `null` when no manifest was ever persisted under that digest
+ * (never throws — a status query for a digest with no recorded build is a
+ * normal, expected state, matching `readSnapshot`'s null-on-missing
+ * convention).
+ */
+export declare function readBuildManifest(manifestDigest: string, opts?: {
+    cwd?: string;
+}): Promise<BuildArchiveManifest | null>;
+/** List the `manifestDigest` of every build manifest persisted on the orphan branch. */
+export declare function listBuildManifestDigests(opts?: {
+    cwd?: string;
+}): Promise<string[]>;
+/**
+ * Read every persisted build manifest. Best-effort: a manifest file that
+ * fails to parse is skipped rather than failing the whole read (mirrors
+ * `readReleaseLedger`'s "skip malformed lines" degrade-gracefully
+ * convention) — the caller only gets the count implicitly via array length,
+ * since a corrupted manifest blob is a much rarer/more surprising event than
+ * a hand-edited ledger line and not expected to need the same "surfaced
+ * count" treatment.
+ */
+export declare function readAllBuildManifests(opts?: {
+    cwd?: string;
+}): Promise<BuildArchiveManifest[]>;
+/**
+ * Find the persisted manifest that carries an entry (any kind — image,
+ * template, asset, or sbom) whose `digest` equals `artifactDigest`. This is
+ * the lookup `chant components status` actually needs: a `ReleaseRecord`
+ * (../lifecycle/release-ledger.ts) records the *artifact* digest that was
+ * promoted/deployed, not the manifest's own aggregate `manifestDigest` — so
+ * resolving "the build behind this deployed digest" means searching
+ * manifest contents, not a direct keyed lookup. Returns `undefined` when no
+ * persisted manifest contains a matching entry (no build was ever persisted
+ * for that artifact digest — e.g. it predates #609, or was recorded via the
+ * standalone `chant components release` command with no corresponding
+ * `chant build`/`run` in this checkout).
+ *
+ * A `ReleaseRecord.manifestDigest`, when present (an optional field a caller
+ * may have supplied at record time), lets a caller skip this scan entirely
+ * via `readBuildManifest` directly — this function is the fallback for the
+ * common case where only the artifact digest is known.
+ */
+export declare function findBuildManifestByArtifactDigest(artifactDigest: string, opts?: {
+    cwd?: string;
+}): Promise<BuildArchiveManifest | undefined>;
+//# sourceMappingURL=build-ledger-store.d.ts.map

package/dist/lifecycle/build-ledger-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-ledger-store.d.ts","sourceRoot":"","sources":["../../src/lifecycle/build-ledger-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAc9E;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,oBAAoB,EAC9B,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAI7B;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAQtC;AAED,wFAAwF;AACxF,wBAAsB,wBAAwB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAKzF;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAQpG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iCAAiC,CACrD,cAAc,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAG3C"}

package/dist/lifecycle/build-ledger.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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.js";
+import type { ArtifactReproducibility } from "../components/verbs/reproducibility.js";
+/** 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 declare const noopReferrerLookup: ReferrerLookup;
+/**
+ * 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 declare function buildLedgerEntries(manifest: BuildArchiveManifest, lookup?: ReferrerLookup): Promise<BuildLedgerEntry[]>;
+/** Find the referrer of a given kind for a digest, if any (a convenience for "does this build have a signature/SBOM/provenance"). */
+export declare function findReferrer(referrers: Referrer[], kind: ReferrerKind): Referrer | undefined;
+/** 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 declare function artifactReproducibilitySummary(manifest: BuildArchiveManifest): ArtifactReproducibilitySummary[];
+/** 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 declare function componentBomSummary(manifest: BuildArchiveManifest): ComponentBomSummary | undefined;
+//# sourceMappingURL=build-ledger.d.ts.map

package/dist/lifecycle/build-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-ledger.d.ts","sourceRoot":"","sources":["../../src/lifecycle/build-ledger.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/git.d.ts

@@ -1,3 +1,37 @@
+/**
+ * Write a blob to an arbitrary `<environment>/<filename>` path on the orphan
+ * branch, preserving every other env/file entry already on the branch.
+ *
+ * Pipeline: hash-object → mktree → commit-tree → update-ref. Factored out of
+ * `writeSnapshot` so the release ledger (#568, epic #551 "Build & deploy
+ * observability") can reuse the identical git-plumbing path for a different
+ * filename (`releases.jsonl`) under the same env directory, rather than a
+ * parallel storage mechanism.
+ *
+ * Exported (not just used internally) so ./build-ledger-store.ts (#609) can
+ * reuse this exact plumbing for a top-level directory that isn't really an
+ * "environment" (`_builds`, keyed by manifest digest rather than env name) —
+ * a build archive is promoted by digest across environments, never owned by
+ * one, so it belongs in its own digest-keyed namespace on the same orphan
+ * branch rather than duplicated per env. The parameter is still named
+ * `environment` because it is literally the first path segment / root-tree
+ * entry name this function's tree-building logic groups by; callers outside
+ * this module that pass a non-env value (like `_builds`) are relying on that
+ * generic behavior, not on any env-specific semantics.
+ */
+export declare function writeBlobToPath(environment: string, filename: string, content: string, commitMessage: string, opts?: {
+    cwd?: string;
+}): Promise<string>;
+/**
+ * Read a blob from an arbitrary `<environment>/<filename>` path on the orphan
+ * branch. Returns null when the path doesn't exist (missing branch, env, or
+ * file). Sibling of `writeBlobToPath`. Exported for the same reason
+ * `writeBlobToPath` is — ./build-ledger-store.ts (#609) reads manifests back
+ * from the `_builds` namespace through this identical helper.
+ */
+export declare function readBlobFromPath(environment: string, filename: string, opts?: {
+    cwd?: string;
+}): Promise<string | null>;
 /**
  * Write a state snapshot JSON to the orphan branch.
  *
@@ -12,6 +46,56 @@ export declare function writeSnapshot(environment: string, lexicon: string, json
 export declare function readSnapshot(environment: string, lexicon: string, opts?: {
     cwd?: string;
 }): Promise<string | null>;
+/**
+ * Append one immutable release record line to `<environment>/releases.jsonl`
+ * on the orphan branch (#568, epic #551 "Build & deploy observability"). Same
+ * git-plumbing path `writeSnapshot` uses, just a different filename under the
+ * env directory and append-only (JSON Lines) instead of replace-whole-file:
+ * each deploy adds one line, never rewrites a previous one, so the ledger
+ * stays a durable, append-only history rather than a point-in-time snapshot.
+ *
+ * Low-level plumbing over an already-serialized line; ../release-ledger.ts's
+ * `appendReleaseRecord` is the typed, validated public API most callers want
+ * — named distinctly here (`ReleaseRecordLine`) to avoid re-export ambiguity
+ * between the two modules.
+ *
+ * Returns the new orphan-branch commit SHA — the caller still owns pushing
+ * via `pushLifecycle` under the same concurrent-write lease `writeSnapshot`
+ * uses.
+ */
+export declare function appendReleaseRecordLine(environment: string, recordJson: string, opts?: {
+    cwd?: string;
+}): Promise<string>;
+/**
+ * Read every release record line for `environment` from the orphan branch,
+ * oldest first, as raw JSON strings. Returns `[]` when no ledger exists yet
+ * for that env (never throws — a component that has never recorded a deploy
+ * is a normal, expected state). ../release-ledger.ts's `readReleaseLedger`
+ * parses/validates these lines into typed `ReleaseRecord`s.
+ */
+export declare function readReleaseLedgerLines(environment: string, opts?: {
+    cwd?: string;
+}): Promise<string[]>;
+/**
+ * List every environment that has a release ledger on the orphan branch —
+ * the root-level directories under `chant/lifecycle` that carry a
+ * `releases.jsonl` entry. Used by `chant components status` (no env arg) to
+ * discover which environments to report on.
+ */
+export declare function listLedgerEnvironments(opts?: {
+    cwd?: string;
+}): Promise<string[]>;
+/**
+ * List every filename directly under `<dir>/` on the orphan branch (no
+ * recursion), or `[]` when the branch/directory doesn't exist yet. Generic
+ * sibling of `readEnvironmentSnapshots`'s inline file listing, factored out
+ * so ./build-ledger-store.ts (#609) can enumerate every persisted build
+ * manifest (`_builds/<digest>.json`) without duplicating this `git ls-tree
+ * --name-only` call.
+ */
+export declare function listFilesInDir(dir: string, opts?: {
+    cwd?: string;
+}): Promise<string[]>;
 /**
  * Read all snapshots for an environment (all lexicons).
  */

package/dist/lifecycle/git.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/lifecycle/git.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,MAAM,CAAC,CAoFjB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxB;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqB9B;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C,OAAO,CAAC,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAgBnE;AAED;;;;GAIG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;gBACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM;CASpD;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CA8B7E;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAW9E;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5E"}
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../../src/lifecycle/git.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/index.d.ts

@@ -5,4 +5,9 @@ export * from "./snapshot.js";
 export * from "./live-diff.js";
 export * from "./change-set.js";
 export * from "./affected.js";
+export * from "./release-ledger.js";
+export * from "./build-ledger.js";
+export * from "./build-ledger-store.js";
+export * from "./oras-referrer-lookup.js";
+export * from "./status.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC"}

package/dist/lifecycle/oras-referrer-lookup.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Real `ReferrerLookup` backend (#610, epic #551 follow-up to #568's
+ * `ReferrerLookup` interface). Shells out to `oras discover --format json
+ * <digest>` — the OCI distribution spec's referrers API, as exposed by the
+ * `oras` CLI — through the same injectable `ProcessRunner`
+ * (../components/verbs/process-runner.ts) the deep-scan `SbomGenerator`
+ * backend (../components/verbs/tool-sbom-generator.ts) and `publish-image`'s
+ * referrer-attach step share, mirroring ../components/verbs/cloud-executor.ts's
+ * `CloudExecutor` pattern once more: production code shells out, tests inject
+ * a `MockProcessRunner` and never touch a real registry/`oras` binary.
+ *
+ * Not the process-wide default: ./build-ledger.ts's `noopReferrerLookup`
+ * remains that (reports no referrers, no network, no registry credentials
+ * required) for exactly the reason `notImplementedSbomGenerator` and
+ * `SbomGenerator`'s hermetic backend aren't `sbom-generator.ts`'s default
+ * either — a project opts into the real registry-backed lookup explicitly
+ * (`buildLedgerEntries(manifest, createOrasReferrerLookup())`) rather than
+ * every previously-network-free build-ledger query silently starting to hit
+ * a registry.
+ */
+import { type ProcessRunner } from "../components/verbs/process-runner.js";
+import type { ReferrerLookup } from "./build-ledger.js";
+export interface OrasReferrerLookupOptions {
+    /** Injected process boundary. Defaults to the real, `child_process`-backed runner. */
+    runner?: ProcessRunner;
+    /** Registry/repo prefix `digest` is resolved against (e.g. `123.dkr.ecr.us-east-1.amazonaws.com/search`) — `oras discover` needs a full `repo@digest` reference, not a bare digest. Required; a `ReferrerLookup.discover(digest)` call with no repo context has nothing to query. */
+    repo: string;
+}
+/**
+ * Build a real `ReferrerLookup` backed by `oras discover`. `discover(digest)`
+ * runs `oras discover --format json <repo>@<digest>` and maps every returned
+ * manifest into a `Referrer`, classified by `classify` above. Returns `[]`
+ * (never throws) when `oras` reports no referrers for a digest — an image
+ * with no attached SBOM/provenance/signature is a normal outcome, not an
+ * error. Throws `ToolNotAvailableError`
+ * (../components/verbs/process-runner.ts) if `oras` itself is not installed,
+ * so a misconfigured environment fails loudly rather than silently reporting
+ * "no referrers" for every digest.
+ */
+export declare function createOrasReferrerLookup(options: OrasReferrerLookupOptions): ReferrerLookup;
+//# sourceMappingURL=oras-referrer-lookup.d.ts.map

package/dist/lifecycle/oras-referrer-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oras-referrer-lookup.d.ts","sourceRoot":"","sources":["../../src/lifecycle/oras-referrer-lookup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAA0B,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAkC7E,MAAM,WAAW,yBAAyB;IACxC,sFAAsF;IACtF,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,qRAAqR;IACrR,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,cAAc,CA8B3F"}

package/dist/lifecycle/release-ledger.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Release ledger — the recorded half of build & deploy observability (#568,
+ * epic #551 "Build & deploy observability").
+ *
+ * chant already has the *live-truth* half: ownership markers stamp stack/env
+ * identity on live resources, `lifecycle diff --live` / `lifecycle plan`
+ * compare declared vs live, and snapshots on `chant/lifecycle` give a
+ * forensic timeline (see ./snapshot.ts, ./live-diff.ts, ./change-set.ts).
+ * What was missing is the *record* half: "what we recorded deploying",
+ * independent of whether the thing is still running.
+ *
+ * A release record is immutable and append-only: each deploy appends one line
+ * to `<env>/releases.jsonl` on the `chant/lifecycle` orphan branch (see
+ * ./git.ts's `appendReleaseRecord`/`readReleaseLedger`) — never rewritten,
+ * never replaced in place, mirroring how the snapshot branch itself is
+ * treated as observational evidence rather than a mutable state file. The
+ * append-only property is what makes "which build was in staging on
+ * Tuesday" answerable months later even after staging has moved on to a
+ * dozen newer digests.
+ *
+ * The binding key is the artifact **digest** (`sha256:...`), the same
+ * identity `BuildArchive` manifests and `publish-image`/`load-image-on-host`
+ * promote by (see ../components/verbs/build-archive.ts,
+ * ../components/verbs/publish.ts). Because publish promotes by digest never
+ * rebuilding, the same identity threads build → dev → staging → prod, so
+ * "which build is in prod, and is it the one tested in staging" is a
+ * straightforward digest comparison over this ledger — never a guess through
+ * CI logs.
+ */
+/**
+ * One immutable deploy record: `(component, env, artifact digest, git sha,
+ * run id, timestamp, actor)`, referencing the build archive by digest — the
+ * exact shape epic #551 "Build & deploy observability" asks for.
+ */
+export interface ReleaseRecord {
+    /** Schema version, so an incompatible future shape can be detected before being misread. */
+    version: 1;
+    /** Component this deploy released (matches `Component.name`, ../components/component.ts). */
+    component: string;
+    /** Environment this deploy targeted. */
+    env: string;
+    /**
+     * Content-addressed digest of the promoted artifact (`sha256:...`) — the
+     * same digest `publish-image`/`load-image-on-host` return
+     * (`PublishImageOutput.digest`, ../components/verbs/publish.ts) and the
+     * one `BuildArchiveManifest` entries carry
+     * (../components/verbs/build-archive.ts). The join key for every query
+     * this ledger answers.
+     */
+    digest: string;
+    /** Git commit SHA the deploy was built from. */
+    gitSha: string;
+    /** Orchestrator run identifier (a `DriverRunResult`/Op run id, or a CI run id in generate mode) — the pointer back into the deploy event log. */
+    runId: string;
+    /**
+     * When this record was written. The caller supplies this — the session
+     * cannot call `Date.now()` reliably in every context, so the CLI resolves
+     * a real `new Date()` at record time and passes it in as an ISO-8601
+     * string; library code never defaults this internally.
+     */
+    timestamp: string;
+    /** Who/what triggered the deploy (a username, a CI actor, a service account). */
+    actor: string;
+    /** Optional: the archive's own manifest digest (../components/verbs/build-archive.ts's `manifestDigest`), when the caller has it — lets a reader recover full build contents/provenance, not just the promoted image digest. */
+    manifestDigest?: string;
+}
+/** Thrown by `appendReleaseRecord` when the record is missing a required field — a release record can never be recorded partially, since it is never editable afterward. */
+export declare class InvalidReleaseRecordError extends Error {
+    readonly missing: string[];
+    constructor(missing: string[]);
+}
+/** Validate that a release record carries every required field as a non-empty string. */
+export declare function validateReleaseRecord(record: Partial<ReleaseRecord>): string[];
+/** Input a caller supplies to record one deploy — `version` is filled in, everything else is required (see `ReleaseRecord`). */
+export type ReleaseRecordInput = Omit<ReleaseRecord, "version">;
+/**
+ * Append one immutable release record to the `<env>` ledger on the
+ * `chant/lifecycle` orphan branch. Throws `InvalidReleaseRecordError` before
+ * any git operation runs if a required field is missing — never partially
+ * records, since nothing about a release record is editable after the fact.
+ *
+ * Does not push to the remote; call `pushLifecycle` (./git.ts) afterward, the
+ * same two-step (`write` then `push`) shape `takeSnapshot` (./snapshot.ts)
+ * uses, so a caller recording several releases in one run can batch the push.
+ */
+export declare function appendReleaseRecord(input: ReleaseRecordInput, opts?: {
+    cwd?: string;
+}): Promise<{
+    commit: string;
+    record: ReleaseRecord;
+}>;
+/**
+ * Read every release record for `environment`, oldest first. Malformed lines
+ * (a hand-edited or corrupted ledger) are skipped rather than throwing, since
+ * a status query should degrade gracefully rather than fail outright on one
+ * bad line — but each skip is reported so callers/tests can surface it.
+ */
+export declare function readReleaseLedger(environment: string, opts?: {
+    cwd?: string;
+}): Promise<{
+    records: ReleaseRecord[];
+    malformed: number;
+}>;
+/** List every environment that has release records on the orphan branch. */
+export declare function listReleaseEnvironments(opts?: {
+    cwd?: string;
+}): Promise<string[]>;
+/**
+ * The latest release record per component in `records` — "what we recorded
+ * deploying" reduces to one row per component by taking the most recent
+ * `timestamp` (ties broken by ledger order, i.e. later append wins), since
+ * a component may have many historical records in one environment's ledger.
+ */
+export declare function latestPerComponent(records: ReleaseRecord[]): Map<string, ReleaseRecord>;
+/**
+ * Find every release record across `records` that references `digest` — the
+ * cross-environment query "is the build in prod the one tested in staging"
+ * reduces to: read both envs' ledgers, then check whether the same digest
+ * appears in each. Sorted oldest first, matching ledger order.
+ */
+export declare function recordsForDigest(records: ReleaseRecord[], digest: string): ReleaseRecord[];
+//# sourceMappingURL=release-ledger.d.ts.map