@intentius/chant 0.124.13 → 0.124.15

package/dist/lifecycle/build-ledger-store.js

@@ -0,0 +1,160 @@
+/**
+ * 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 { sortedJsonReplacer } from "../utils.js";
+import { flagLegacyDigest, warnOnLegacyDigests, withoutReadFlags } from "./legacy-digest.js";
+import { writeBlobToPath, readBlobFromPath, listFilesInDir } from "./git.js";
+/** Fixed top-level directory on the `chant/lifecycle` orphan branch that holds every persisted build manifest — a peer of the per-env directories, never nested inside one (see module doc for why). */
+const BUILDS_DIR = "_builds";
+/** Turn a `sha256:...`-style digest into a filesystem/git-tree-safe filename stem (`:` is not usable in a git tree entry name the way this plumbing constructs it). */
+function digestToFilenameStem(digest) {
+    return digest.replace(/:/g, "_");
+}
+function manifestFilename(manifestDigest) {
+    return `${digestToFilenameStem(manifestDigest)}.json`;
+}
+/**
+ * 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 async function persistBuildManifest(manifest, opts) {
+    // `flags` are read-side only (#2514); a manifest read back and persisted again never keeps them.
+    const json = JSON.stringify(withoutReadFlags(manifest), sortedJsonReplacer);
+    const commit = await writeBlobToPath(BUILDS_DIR, manifestFilename(manifest.manifestDigest), json, "Build manifest", opts);
+    return { commit };
+}
+/**
+ * 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 async function readBuildManifest(manifestDigest, opts) {
+    const content = await readBlobFromPath(BUILDS_DIR, manifestFilename(manifestDigest), opts);
+    if (!content)
+        return null;
+    let manifest;
+    try {
+        manifest = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    // chant #2514 — a manifest whose digests predate real SHA-256 is flagged
+    // legacy-digest, never re-keyed, and the project is warned once.
+    const digests = [
+        manifest.manifestDigest,
+        ...(Array.isArray(manifest.contents) ? manifest.contents.map((e) => e?.digest) : []),
+    ];
+    warnOnLegacyDigests(digests, "build manifests", opts?.cwd);
+    return flagLegacyDigest(manifest, digests);
+}
+/** List the `manifestDigest` of every build manifest persisted on the orphan branch. */
+export async function listBuildManifestDigests(opts) {
+    const files = await listFilesInDir(BUILDS_DIR, opts);
+    return files
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => f.replace(/\.json$/, "").replace(/_/g, ":"));
+}
+/**
+ * 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 async function readAllBuildManifests(opts) {
+    const digests = await listBuildManifestDigests(opts);
+    const manifests = [];
+    for (const digest of digests) {
+        const manifest = await readBuildManifest(digest, opts);
+        if (manifest)
+            manifests.push(manifest);
+    }
+    return manifests;
+}
+/**
+ * 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 async function findBuildManifestByArtifactDigest(artifactDigest, opts) {
+    const manifests = await readAllBuildManifests(opts);
+    return manifests.find((m) => m.contents.some((entry) => entry.digest === artifactDigest));
+}

package/dist/lifecycle/build-ledger.js

@@ -0,0 +1,155 @@
+/**
+ * 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 { findSbomForSubject, imageEntries, sbomEntries, artifactEntries } from "../components/verbs/build-archive.js";
+/** 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 = {
+    async discover() {
+        return [];
+    },
+};
+/**
+ * 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, lookup = noopReferrerLookup) {
+    const images = imageEntries(manifest);
+    const entries = [];
+    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 = 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, kind) {
+    return referrers.find((r) => r.kind === kind);
+}
+/**
+ * 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) {
+    return artifactEntries(manifest).map((entry) => ({
+        path: entry.path,
+        kind: entry.kind,
+        digest: entry.digest,
+        reproducibility: entry.reproducibility,
+        sourceRef: entry.provenance?.sourceRef,
+    }));
+}
+/**
+ * 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) {
+    const boms = sbomEntries(manifest);
+    if (boms.length === 0)
+        return undefined;
+    const leaves = 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 };
+}

package/dist/lifecycle/change-set.js

@@ -0,0 +1,356 @@
+/**
+ * Change set: a typed, read-only projection of a live diff.
+ *
+ * `chant lifecycle diff --live` computes a three-way comparison — declared now /
+ * last snapshot / live now — and prints it. `buildChangeSet` promotes that
+ * same signal into a classified create/update/delete/adopt/runtime/noop set
+ * that other tooling (reconcile, apply) can act on.
+ *
+ * Strictly read-only and pure: no I/O, no mutation. The classification reads
+ * ownership from the live marker only (populated downstream); until ownership
+ * exists, an undeclared live resource is `adopt`, never `delete`. The snapshot
+ * is evidence, never the basis for a mutation decision — it must never become
+ * load-bearing.
+ */
+import { diffLive } from "./live-diff.js";
+import { unobservedReasonText } from "../observation.js";
+import { renderDisruption, summarizeDisruption } from "./disruption.js";
+export function buildChangeSet(env, input, options) {
+    const diff = diffLive(input);
+    const { declared, observedNow } = input;
+    const observedThen = input.observedThen ?? {};
+    const unobservedInput = input.unobserved ?? {};
+    const driftByName = new Map(diff.driftedSinceSnapshot.map((d) => [d.name, d.changes]));
+    const names = new Set([
+        ...declared,
+        ...Object.keys(observedNow),
+        ...Object.keys(observedThen),
+        ...Object.keys(unobservedInput),
+    ]);
+    const entries = [];
+    for (const name of names) {
+        const isDeclared = declared.has(name);
+        const live = Object.prototype.hasOwnProperty.call(observedNow, name);
+        const inSnapshot = Object.prototype.hasOwnProperty.call(observedThen, name);
+        // A returned resource was observed by definition; `unobserved` only counts
+        // for entities the lexicon did not return.
+        const unobservedEntry = live ? undefined : unobservedInput[name];
+        const type = observedNow[name]?.type ?? observedThen[name]?.type ?? unobservedEntry?.type;
+        const evidence = { declared: isDeclared, inSnapshot, live, observed: !unobservedEntry };
+        // Ownership comes from the LIVE marker only (carried on observedNow), never
+        // from the snapshot. This is the invariant that keeps the snapshot from
+        // becoming load-bearing: a mutation decision (delete) is never made from a
+        // record chant has to host.
+        const ownership = observedNow[name]?.ownership ?? "unknown";
+        // Owner-reference chain (#1077), same live-only provenance as ownership
+        // above. Only a `declared` root changes the classification; `unknown` is
+        // deliberately not escalated (#1168's tri-state precedent — an
+        // unconfirmed chain never earns the more confident verdict).
+        const runtimeOwner = !isDeclared && observedNow[name]?.ownerChain?.root === "declared"
+            ? observedNow[name].ownerChain.entity
+            : undefined;
+        let action;
+        let deltas;
+        if (unobservedEntry) {
+            // The lexicon never looked. Absence is not established, so neither a
+            // create (declared) nor a delete/adopt (undeclared) can be proposed —
+            // the entry exists to say the plan has a hole here.
+            action = "unobserved";
+        }
+        else if (isDeclared && !live) {
+            // Declared in source, and the provider confirmed it absent → create.
+            action = "create";
+        }
+        else if (isDeclared && live) {
+            const drift = driftByName.get(name);
+            if (drift && drift.length > 0) {
+                action = "update";
+                deltas = drift;
+            }
+            else {
+                action = "noop";
+            }
+        }
+        else if (live && runtimeOwner) {
+            // Live, undeclared, and its owner chain reaches a declared entity
+            // (#1077) — expected runtime, never a delete/adopt candidate, checked
+            // ahead of the ownership marker below: even a runtime child that
+            // happens to carry chant's own marker (label propagation from its
+            // owner's template) must never be proposed for deletion.
+            action = "runtime";
+        }
+        else if (live) {
+            // Live but undeclared. Only a chant-owned orphan is a safe delete; a
+            // foreign or unknown orphan can be adopted but never auto-deleted.
+            action = ownership === "owned" ? "delete" : "adopt";
+        }
+        else {
+            // Only in the snapshot: already gone, nothing to reconcile.
+            action = "noop";
+        }
+        // The address the read went to (#1620) — from the unobserved entry when
+        // there is one, else the observation's queried map. Diagnostic only; the
+        // classification above never reads it.
+        const queried = unobservedEntry?.queried ?? input.queried?.[name];
+        const definition = action === "create" ? input.definitions?.[name] : undefined;
+        // The provider's id for the row (#1674). Live first; the snapshot's only
+        // when the resource is no longer live (a snapshot-only noop).
+        const physicalId = observedNow[name]?.physicalId ?? observedThen[name]?.physicalId;
+        entries.push({
+            name,
+            type,
+            ...(options?.lexicon ? { lexicon: options.lexicon } : {}),
+            ...(physicalId ? { physicalId } : {}),
+            action,
+            evidence,
+            deltas,
+            ownership,
+            ...(unobservedEntry
+                ? {
+                    unobservedReason: unobservedEntry.reason,
+                    ...(unobservedEntry.detail ? { unobservedDetail: unobservedEntry.detail } : {}),
+                }
+                : {}),
+            ...(queried ? { queried } : {}),
+            ...(definition ? { definition } : {}),
+            ...(runtimeOwner ? { runtimeOwner } : {}),
+        });
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    return { env, entries };
+}
+const ACTION_ORDER = ["create", "update", "effect", "delete", "adopt", "runtime", "noop", "unobserved"];
+/** Count entries per action. */
+export function summarize(cs) {
+    const counts = {
+        create: 0,
+        update: 0,
+        effect: 0,
+        delete: 0,
+        adopt: 0,
+        runtime: 0,
+        noop: 0,
+        unobserved: 0,
+    };
+    for (const e of cs.entries)
+        counts[e.action]++;
+    return counts;
+}
+/** Project a change set onto the GitLab MR plan widget shape. Pure. */
+export function gitlabMrReport(cs) {
+    const counts = summarize(cs);
+    return { create: counts.create, update: counts.update, delete: counts.delete };
+}
+/**
+ * Warning a plan should print when it carries a hole — a declared entity the
+ * lexicon could not observe (#1089). The `--json` and `--report gitlab-mr`
+ * shapes have no column for `unobserved`, so both the CLI (on stderr) and the
+ * `markdown` report (in the body, since a reviewer never sees a job's stderr)
+ * read this same wording rather than drifting apart. Empty when the plan has
+ * no hole. Same discipline as {@link disruptionNotices} in `./disruption`.
+ */
+export function unobservedPlanNotice(cs) {
+    const count = summarize(cs).unobserved;
+    return count > 0
+        ? [
+            `${count} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
+        ]
+        : [];
+}
+/**
+ * Section heading text for one action group — shared between {@link renderChangeSet}
+ * and {@link renderChangeSetMarkdown} so the wording never drifts between the
+ * terminal render and the reviewer-facing one.
+ */
+function actionSectionLabel(action, hasDisruption) {
+    switch (action) {
+        case "unobserved":
+            return "UNOBSERVED (declared; chant could not read live state — no action proposed)";
+        case "runtime":
+            return "RUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate)";
+        case "effect":
+            return "EFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt)";
+        case "update":
+            return hasDisruption
+                ? "UPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe)"
+                : "UPDATE";
+        default:
+            return action.toUpperCase();
+    }
+}
+/** Human-readable render of a change set. Pure — returns a string. */
+export function renderChangeSet(cs) {
+    const counts = summarize(cs);
+    const header = ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ");
+    const lines = [`Plan for ${cs.env}: ${header}`];
+    // Disruption (#1665) rides the header too, so the one number that says how
+    // much this plan hurts is visible without reading every row.
+    const disruption = summarizeDisruption(cs);
+    const disruptionParts = Object.entries(disruption)
+        .filter(([, n]) => n > 0)
+        .map(([level, n]) => `${n} ${level}`);
+    if (disruptionParts.length > 0) {
+        lines.push(`Disruption: ${disruptionParts.join(", ")}`);
+    }
+    for (const action of ACTION_ORDER) {
+        const group = cs.entries.filter((e) => e.action === action);
+        if (group.length === 0)
+            continue;
+        lines.push(`\n${actionSectionLabel(action, disruptionParts.length > 0)}:`);
+        for (const e of group) {
+            if (e.action === "effect") {
+                lines.push(`  effect will fire: ${e.effect ?? e.name} — receipt ${e.name}${e.type ? ` (${e.type})` : ""}` +
+                    `${e.effectDetail ? ` — ${e.effectDetail}` : ""}`);
+                continue;
+            }
+            const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
+            const why = e.unobservedReason
+                ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+                : "";
+            const owner = e.runtimeOwner ? ` — owned by ${e.runtimeOwner}` : "";
+            lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}${owner}${renderDisruption(e)}`);
+            const forced = new Set(e.disruptionBecause ?? []);
+            for (const d of e.deltas ?? []) {
+                // A path the verdict rests on is marked, so a `replace` row says which
+                // of five changed properties caused it.
+                lines.push(`      ${forced.has(d.path) ? "! " : ""}${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+            }
+        }
+    }
+    if (cs.held && cs.held.length > 0) {
+        lines.push(`\n${heldSectionLabel()}:`);
+        for (const line of heldLines(cs.held))
+            lines.push(line);
+    }
+    return lines.join("\n");
+}
+/**
+ * Section heading for the held set (#2162) — shared between {@link renderChangeSet}
+ * and {@link renderChangeSetMarkdown}.
+ */
+function heldSectionLabel() {
+    return "HELD (declared heldElsewhere(); not drift, never proposed for update)";
+}
+/** One held property's plain-text line, indented under its entity. */
+function heldLines(held) {
+    const lines = [];
+    for (const entity of held) {
+        const lexicon = entity.lexicon ? ` ${entity.lexicon}` : "";
+        lines.push(`  ${entity.name} (${entity.type})${lexicon}`);
+        for (const h of entity.held) {
+            const live = "live" in h ? fmt(h.live) : "<absent>";
+            const suspicious = h.suspicious
+                ? " [SUSPICIOUS: no live value ever showed up here]"
+                : "";
+            lines.push(`      ${h.path}: held by ${h.by} — ${live} (${h.reason})${suspicious}`);
+        }
+    }
+    return lines;
+}
+/** One held property's markdown line, mirroring {@link renderMarkdownEntry}'s formatting. */
+function heldLinesMarkdown(held) {
+    const lines = [];
+    for (const entity of held) {
+        const lexicon = entity.lexicon ? ` \`${entity.lexicon}\`` : "";
+        lines.push(`- \`${entity.name}\` (${entity.type})${lexicon}`);
+        if (entity.held.length > 0) {
+            lines.push("  ```");
+            for (const h of entity.held) {
+                const live = "live" in h ? fmt(h.live) : "<absent>";
+                const suspicious = h.suspicious ? "  SUSPICIOUS: no live value ever showed up here" : "";
+                lines.push(`  ${h.path}: held by ${h.by} — ${live} (${h.reason})${suspicious}`);
+            }
+            lines.push("  ```");
+        }
+    }
+    return lines;
+}
+/**
+ * Entries beyond this in one action group are collapsed into a `<details>`
+ * block in {@link renderChangeSetMarkdown} — a group's worth of rows is fine
+ * to read inline, a hundred-entry plan is not (#1983).
+ */
+const MARKDOWN_FOLD_THRESHOLD = 20;
+/** One entry's markdown, mirroring the rows {@link renderChangeSet} prints. */
+function renderMarkdownEntry(e) {
+    if (e.action === "effect") {
+        return [
+            `- effect will fire: \`${e.effect ?? e.name}\` — receipt \`${e.name}\`${e.type ? ` (${e.type})` : ""}` +
+                `${e.effectDetail ? ` — ${e.effectDetail}` : ""}`,
+        ];
+    }
+    const lexicon = e.lexicon ? ` \`${e.lexicon}\`` : "";
+    const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
+    const why = e.unobservedReason
+        ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+        : "";
+    const owner = e.runtimeOwner ? ` — owned by \`${e.runtimeOwner}\`` : "";
+    // Bolded rather than the plain-text render's bare " — destroy: ..." — a
+    // reviewer scanning a wall of "update" rows should see disruption without
+    // reading every one (#1665).
+    const disruption = e.disruption
+        ? ` — **${e.disruption}**${e.disruptionDetail ? `: ${e.disruptionDetail}` : ""}`
+        : "";
+    const lines = [`- \`${e.name}\`${e.type ? ` (${e.type})` : ""}${lexicon}${own}${why}${owner}${disruption}`];
+    if (e.deltas && e.deltas.length > 0) {
+        const forced = new Set(e.disruptionBecause ?? []);
+        lines.push("  ```");
+        for (const d of e.deltas) {
+            lines.push(`  ${forced.has(d.path) ? "! " : "  "}${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+        }
+        lines.push("  ```");
+    }
+    return lines;
+}
+/**
+ * Markdown projection of a change set (#1983) — sized for a PR/MR comment
+ * rather than a terminal. A scannable counts header, entries grouped by
+ * action and attributed to their lexicon, deltas in a fenced block, and any
+ * group past {@link MARKDOWN_FOLD_THRESHOLD} folded into a `<details>` so a
+ * large plan doesn't bury the comment. Pure — no ANSI, no I/O — and
+ * deterministic: same entry ordering as {@link renderChangeSet}.
+ *
+ * Both a hole (#1089) and an expensive verdict (#1665) are surfaced IN the
+ * body, not left to stderr the way `--json` and `--report gitlab-mr` leave
+ * them: a reviewer reading a comment never sees the job's log, so a plan
+ * carrying either must not read as clean.
+ */
+export function renderChangeSetMarkdown(cs) {
+    const counts = summarize(cs);
+    const lines = [`## Plan for \`${cs.env}\``, "", ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ")];
+    const disruption = summarizeDisruption(cs);
+    const disruptionParts = Object.entries(disruption)
+        .filter(([, n]) => n > 0)
+        .map(([level, n]) => `${n} ${level}`);
+    if (disruptionParts.length > 0) {
+        lines.push("", `**Disruption:** ${disruptionParts.join(", ")}`);
+    }
+    for (const notice of unobservedPlanNotice(cs)) {
+        lines.push("", `> **${notice}**`);
+    }
+    for (const action of ACTION_ORDER) {
+        const group = cs.entries.filter((e) => e.action === action);
+        if (group.length === 0)
+            continue;
+        lines.push("", `### ${actionSectionLabel(action, disruptionParts.length > 0)}`);
+        const body = group.flatMap((e) => renderMarkdownEntry(e));
+        if (group.length > MARKDOWN_FOLD_THRESHOLD) {
+            lines.push("", `<details><summary>${group.length} entries — click to expand</summary>`, "", ...body, "", "</details>");
+        }
+        else {
+            lines.push("", ...body);
+        }
+    }
+    if (cs.held && cs.held.length > 0) {
+        lines.push("", `### ${heldSectionLabel()}`, "", ...heldLinesMarkdown(cs.held));
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+function fmt(v) {
+    if (v === undefined)
+        return "<unset>";
+    if (typeof v === "string")
+        return v.length > 60 ? v.slice(0, 57) + "..." : v;
+    const json = JSON.stringify(v);
+    return json.length > 60 ? json.slice(0, 57) + "..." : json;
+}