@intentius/chant 0.124.12 → 0.124.14

package/dist/lifecycle/observe.js

@@ -0,0 +1,375 @@
+import { build as buildProject } from "../build.js";
+import { resolve as resolvePath } from "node:path";
+import { mergeObservations, normalizeObservation, unobservedAll, formatUnobserved, } from "../observation.js";
+import { zeroResourcesWarning } from "../live-endpoint.js";
+import { unqualifiedKey } from "./identity.js";
+import { isObservableDeclarable } from "../declarable.js";
+/**
+ * Re-key a normalized observation's entities by `${stack}::${id}` (#1162) so a
+ * bare LogicalResourceId shared across stacks (e.g. `vpc`) stays unambiguous
+ * once the per-stack results are merged. The declared canvas qualifies the same
+ * way (`buildDeclaredPerStack`), so the overlay join lines up. Applies to both
+ * the OBSERVED-PRESENT and NOT-OBSERVED maps of the tri-state (#1089).
+ */
+function qualifyObservation(obs, stackName) {
+    const q = (m) => Object.fromEntries(Object.entries(m).map(([k, v]) => [`${stackName}::${k}`, v]));
+    return {
+        resources: q(obs.resources),
+        unobserved: q(obs.unobserved),
+        queried: q(obs.queried),
+        // Which read answered (#2267) is per entity, so it re-keys with them.
+        sources: q(obs.sources),
+        notes: obs.notes,
+        // Exports are already keyed by stack (#1279); nothing to qualify.
+        ...(obs.stackExports ? { stackExports: obs.stackExports } : {}),
+    };
+}
+/**
+ * Query every plugin that implements `describeResources` for its resources in
+ * `environment`. `owned` (default true for the managed-only diagram, epic #776)
+ * restricts to resources carrying chant's ownership marker; a lexicon with no
+ * marker channel logs and returns everything (its own contract). Plugins that
+ * throw are collected into `errors` — one failing lexicon never sinks the whole
+ * graph — and every entity they were asked about is recorded as NOT-OBSERVED
+ * (`read-failed`, #1089) rather than dropped, so a failed read is visibly a
+ * hole instead of a silent absence.
+ *
+ * `stacks` (#57) is for a multi-stack, per-component project, where there is no
+ * single stack named after the environment — AWS's single-stack convention
+ * (`lexicons/aws/src/plugin.ts`'s `describeResources`, absent an explicit
+ * `stack`) queries a stack that simply doesn't exist there,
+ * so the single-call path always observes zero nodes. When `stacks` is
+ * present and non-empty, each observing plugin's `describeResources` is
+ * called once per stack and the returned observations are merged. A stack entry
+ * may be a bare name or `{ name, region?, src? }` (#1162): `src` is built
+ * SCOPED so the deployed BARE LogicalResourceIds match (the whole-project build
+ * disambiguates colliding names to `UsWest1Src…`, which the live ids never
+ * carry), and a scoped stack's observed ids are qualified `${stack}::${id}` so
+ * the same bare id in two stacks stays distinct. A bare-string stack keeps its
+ * bare ids and the tri-state merge (#57). When `stacks` is absent or empty, behavior is
+ * exactly the single call of before (no `stack` key at all), so a single-stack
+ * project is unaffected.
+ */
+export async function observeResources(environment, plugins, buildResult, opts) {
+    var _a;
+    const owned = opts?.owned ?? true;
+    const stacks = (opts?.stacks ?? []).map((st) => (typeof st === "string" ? { name: st } : st));
+    const includeAmbient = opts?.ambient ?? false;
+    // A stack's `src` (multi-stack, #1162) is built SCOPED to recover that stack's
+    // BARE entity names — the names it actually deploys. Matching deployed bare
+    // LogicalResourceIds against the whole-project build's DISAMBIGUATED names
+    // (UsWest1Src…) misses every colliding resource. Cached per src.
+    const serializers = plugins.map((p) => p.serializer);
+    const scopedBuildCache = new Map();
+    const scopedBuild = async (src) => {
+        const key = resolvePath(src);
+        let r = scopedBuildCache.get(key);
+        if (!r) {
+            r = await buildProject(key, serializers);
+            scopedBuildCache.set(key, r);
+        }
+        return r;
+    };
+    const observations = [];
+    const warnings = [];
+    const errors = [];
+    const notes = [];
+    for (const plugin of plugins) {
+        if (!plugin.describeResources)
+            continue;
+        // Serialized build output + declared entities for this lexicon — the scope
+        // describeResources needs to know what to look for.
+        const rawOutput = buildResult.outputs.get(plugin.name);
+        const buildOutput = rawOutput === undefined
+            ? ""
+            : typeof rawOutput === "string"
+                ? rawOutput
+                : rawOutput.primary;
+        const entityNames = [];
+        const entities = new Map();
+        for (const [name, entity] of buildResult.entities) {
+            if (entity.lexicon !== plugin.name)
+                continue;
+            // Only resource declarables have a live counterpart to observe. Outputs,
+            // parameters and serializer directives (gcp's `defaultAnnotations`) are
+            // build-time inputs — declared, but with nothing in any cloud to compare
+            // against, so keeping them in the universe makes every diff report a
+            // hole (or worse, a deletion) for a resource that cannot exist. A
+            // property-kind declarable is read as part of the resource holding it,
+            // never on its own (#3001).
+            if (!isObservableDeclarable(entity))
+                continue;
+            entityNames.push(name);
+            entities.set(name, {
+                entityType: entity.entityType,
+                props: (entity.props != null ? entity.props : {}),
+            });
+        }
+        try {
+            let observed;
+            if (stacks.length > 0) {
+                const parts = [];
+                for (const stack of stacks) {
+                    // Use this stack's scoped build (bare entity names) when it has a src,
+                    // so describeResources matches the deployed bare LogicalResourceIds.
+                    let stackEntityNames = entityNames;
+                    let stackBuildOutput = buildOutput;
+                    let stackEntities = entities;
+                    if (stack.src) {
+                        const sb = await scopedBuild(stack.src);
+                        stackEntityNames = [];
+                        stackEntities = new Map();
+                        for (const [name, entity] of sb.entities) {
+                            if (entity.lexicon !== plugin.name || !isObservableDeclarable(entity))
+                                continue;
+                            stackEntityNames.push(name);
+                            stackEntities.set(name, {
+                                entityType: entity.entityType,
+                                props: (entity.props != null ? entity.props : {}),
+                            });
+                        }
+                        const raw = sb.outputs.get(plugin.name);
+                        stackBuildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : raw.primary;
+                    }
+                    const norm = normalizeObservation(await plugin.describeResources({
+                        environment,
+                        buildOutput: stackBuildOutput,
+                        entityNames: stackEntityNames,
+                        entities: stackEntities,
+                        owned,
+                        stack: stack.name,
+                        region: stack.region,
+                        ...(opts?.namespace ? { namespace: opts.namespace } : {}),
+                    }));
+                    // Qualify ids by stack ONLY for a scoped (`src`) stack (#1162): that
+                    // is the multi-region case where the SAME bare LogicalResourceId
+                    // (e.g. `vpc`) exists in every stack, so a bare union would collide.
+                    // A bare-string stack (#57) has unique per-component ids and is asked
+                    // the whole-project entity set, so it keeps the bare-id tri-state
+                    // merge (present > not-observed > absent) that behold and other
+                    // consumers read.
+                    parts.push(stack.src ? qualifyObservation(norm, stack.name) : norm);
+                }
+                observed = mergeObservations(parts);
+            }
+            else {
+                observed = normalizeObservation(await plugin.describeResources({
+                    environment,
+                    buildOutput,
+                    entityNames,
+                    entities,
+                    owned,
+                    ...(opts?.namespace ? { namespace: opts.namespace } : {}),
+                }));
+            }
+            // Run-level notices (#1265): one line per distinct note per run,
+            // whatever the stack count. `mergeObservations` already folded the
+            // per-stack copies; this folds across lexicons.
+            for (const note of observed.notes) {
+                const line = `[${plugin.name}] ${note}`;
+                if (!notes.includes(line))
+                    notes.push(line);
+            }
+            // What the estate depends on but does not declare (#1273). Read after the
+            // managed resources, because the declared observation is the closure's
+            // roots — there is nothing to reference out from until it exists.
+            const dependencies = await collectDependencies(plugin, {
+                environment,
+                entities,
+                observed: observed.resources,
+                stacks,
+            });
+            for (const message of dependencies.warnings)
+                warnings.push(message);
+            // Resources of a managed kind that nothing declares or references (#1278).
+            // Bounded by what this lexicon's declared entities actually are, so a
+            // project managing security groups is not made to enumerate the account.
+            const ambient = includeAmbient
+                ? await collectAmbient(plugin, {
+                    environment,
+                    kinds: [...new Set([...entities.values()].map((e) => e.entityType))],
+                    observed: observed.resources,
+                    stacks,
+                    warnings,
+                })
+                : {};
+            // A resource can be reached as a dependency AND enumerated as ambient —
+            // the default VPC an instance sits in is both. It is one resource, and
+            // the dependency entry is the one carrying `referencedBy`, so it wins.
+            // Matched on physical id rather than on key, because ambient keys carry a
+            // region (#1416) and dependency keys do not, so the keys no longer
+            // collide even when the resource is the same one.
+            const dependedOn = new Set(Object.values(dependencies.resources)
+                .map((m) => m.physicalId)
+                .filter((id) => typeof id === "string"));
+            for (const [id, meta] of Object.entries(ambient)) {
+                if (meta.physicalId && dependedOn.has(meta.physicalId))
+                    continue;
+                (_a = dependencies.resources)[id] ?? (_a[id] = meta);
+            }
+            pushObservation(observations, warnings, plugin.name, observed, environment, entityNames.length, dependencies);
+        }
+        catch (err) {
+            // A thrown read is the whole-lexicon failure: every declared entity is
+            // NOT-OBSERVED, not absent (#1089). Emitting nothing here is what made a
+            // failed read look like "none of these exist" to every consumer.
+            const message = err instanceof Error ? err.message : String(err);
+            errors.push(`${plugin.name}: ${message}`);
+            pushObservation(observations, warnings, plugin.name, {
+                resources: {},
+                unobserved: unobservedAll(entityNames, "read-failed", message, entities),
+                queried: {},
+                sources: {},
+                notes: [],
+            }, environment, entityNames.length);
+        }
+    }
+    return { observations, warnings, errors, notes };
+}
+/**
+ * The subset of an observation belonging to one stack.
+ *
+ * A scoped stack's ids are qualified `${stack}::${id}` (#1162), so the prefix is
+ * the whole test. An unqualified observation — single-stack, or a bare-string
+ * stack sharing one id space — has no way to be split and is returned whole,
+ * which is what it already was.
+ */
+function scopeToStack(resources, stack) {
+    if (!stack)
+        return resources;
+    const prefix = `${stack}::`;
+    const scoped = Object.fromEntries(Object.entries(resources)
+        .filter(([id]) => id.startsWith(prefix))
+        .map(([id, meta]) => [id, meta]));
+    // No qualified ids at all means this observation was never stack-scoped.
+    return Object.keys(scoped).length > 0 ? scoped : resources;
+}
+/**
+ * Ask a lexicon what exists of the kinds it manages, beyond what is declared
+ * (#1278). Once per stack for the region, merged by physical id — the same
+ * ambient resource seen from two stacks is one resource.
+ *
+ * "The same" is per region (#1416). Two stacks in one region reporting the
+ * account's default security group is one group; two regions' default security
+ * groups are two, whatever their ids look like, so the merge key carries the
+ * region a resource records itself in.
+ */
+export async function collectAmbient(plugin, opts) {
+    var _a;
+    if (!plugin.observeAmbient || opts.kinds.length === 0)
+        return {};
+    const found = {};
+    const refs = opts.stacks.length > 0 ? opts.stacks : [{ name: undefined, region: undefined }];
+    // Only a merge needs region-qualified keys, and one ref is not a merge. This
+    // is what keeps a single-region project's ids exactly what they were, and a
+    // recorded snapshot — always one stack, so always one ref — bare.
+    const merging = refs.length > 1;
+    for (const ref of refs) {
+        try {
+            const part = await plugin.observeAmbient({
+                environment: opts.environment,
+                kinds: opts.kinds,
+                observed: opts.observed,
+                ...(ref.name ? { stack: ref.name } : {}),
+                ...(ref.region ? { region: ref.region } : {}),
+            });
+            for (const [id, meta] of Object.entries(part)) {
+                found[_a = merging ? unqualifiedKey(id, meta) : id] ?? (found[_a] = meta);
+            }
+        }
+        catch (err) {
+            opts.warnings.push(`${plugin.name}: ambient resources not read${ref.name ? ` for stack "${ref.name}"` : ""} — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return found;
+}
+const NO_DEPENDENCIES = { resources: {}, edges: [], warnings: [] };
+/**
+ * Ask a lexicon what its declared estate references but does not manage (#1273).
+ *
+ * Called once per stack, because the closure roots and the region differ per
+ * stack, and merged by key. Dependencies are keyed by physical id and are
+ * deliberately NOT stack-qualified: the account's default VPC route table is the
+ * same resource whichever stack routes through it, and qualifying it would
+ * produce one node per referrer and an edge to each.
+ *
+ * Best-effort. A lexicon that does not implement the hook, or one whose read
+ * fails, contributes nothing — the managed observation is already complete and
+ * useful on its own, and failing it because an ambient dependency could not be
+ * read would trade a whole answer for a partial one.
+ */
+export async function collectDependencies(plugin, opts) {
+    if (!plugin.observeDependencies)
+        return NO_DEPENDENCIES;
+    const resources = {};
+    const edges = [];
+    const warnings = [];
+    const refs = opts.stacks.length > 0 ? opts.stacks : [{ name: undefined, region: undefined }];
+    for (const ref of refs) {
+        // Only this stack's resources are the closure's roots. Handing a lexicon
+        // the whole estate makes it resolve out from resources that live somewhere
+        // else — for AWS that means `describe-instances` in one region with another
+        // region's instance ids, which fails outright with InvalidInstanceID and
+        // takes the whole read down with it.
+        const roots = scopeToStack(opts.observed, ref.name);
+        if (Object.keys(roots).length === 0)
+            continue;
+        try {
+            const found = await plugin.observeDependencies({
+                environment: opts.environment,
+                entities: opts.entities,
+                observed: roots,
+                ...(ref.name ? { stack: ref.name } : {}),
+                ...(ref.region ? { region: ref.region } : {}),
+            });
+            for (const [id, meta] of Object.entries(found.resources)) {
+                // Merge referrers rather than overwrite: two stacks routing through the
+                // same table is one node reached twice, and the reason it is here is
+                // both of them.
+                const existing = resources[id];
+                resources[id] = existing
+                    ? { ...existing, referencedBy: [...new Set([...(existing.referencedBy ?? []), ...(meta.referencedBy ?? [])])] }
+                    : meta;
+            }
+            edges.push(...(found.edges ?? []));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            warnings.push(`${plugin.name}: dependencies not read${ref.name ? ` for stack "${ref.name}"` : ""} — ${message}`);
+        }
+    }
+    return { resources, edges, warnings };
+}
+/** Record one lexicon's observation, warning once per unobserved entity. */
+function pushObservation(observations, warnings, lexicon, observed, environment, declaredCount, dependencies = NO_DEPENDENCIES) {
+    const hasResources = Object.keys(observed.resources).length > 0;
+    const unobservedNames = Object.keys(observed.unobserved);
+    for (const name of unobservedNames) {
+        warnings.push(`${lexicon}: not observed — ${formatUnobserved(name, observed.unobserved[name])}`);
+    }
+    if (!hasResources && unobservedNames.length === 0) {
+        // #1166 — this is exactly the "wrong endpoint" shape (AWS's
+        // stackDoesNotExist branch returns an empty map with no #1089 hole): a
+        // declared entity list with nothing observed and nothing explained.
+        // Previously this fell straight through with neither an observation nor a
+        // warning — silently indistinguishable from "nothing is deployed yet".
+        const notice = zeroResourcesWarning(lexicon, environment, declaredCount, observed);
+        if (notice)
+            warnings.push(notice);
+        return;
+    }
+    // Dependencies ride alongside the managed resources so they become nodes, and
+    // carry `referencedBy` so every consumer can still tell the two apart.
+    const hasDependencies = Object.keys(dependencies.resources).length > 0;
+    observations.push({
+        lexicon,
+        resources: hasDependencies
+            ? { ...observed.resources, ...dependencies.resources }
+            : observed.resources,
+        ...(unobservedNames.length > 0 ? { unobserved: observed.unobserved } : {}),
+        ...(dependencies.edges.length > 0 ? { edges: dependencies.edges } : {}),
+        ...(observed.stackExports && Object.keys(observed.stackExports).length > 0
+            ? { stackExports: observed.stackExports }
+            : {}),
+    });
+}

package/dist/lifecycle/oras-referrer-lookup.js

@@ -0,0 +1,82 @@
+/**
+ * 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 { defaultProcessRunner, q, requireTool, } from "../components/verbs/process-runner.js";
+/**
+ * Classify one oras-reported referrer manifest into a `ReferrerKind`, keyed
+ * off its `artifactType`/media type — the same three kinds
+ * ../components/verbs/build-ledger.ts's `Referrer.kind` already models
+ * (`sbom`, `provenance`, `signature`). An unrecognized artifact type is
+ * skipped (returns `undefined`) rather than guessed at, since a wrong
+ * classification (e.g. reporting a signature as an SBOM) would be worse than
+ * omitting it — the caller only ever sees referrers this module is confident
+ * about.
+ */
+function classify(descriptor) {
+    const type = (descriptor.artifactType ?? descriptor.mediaType ?? "").toLowerCase();
+    if (type.includes("spdx") || type.includes("cyclonedx") || type.includes("sbom"))
+        return "sbom";
+    if (type.includes("in-toto") || type.includes("provenance") || type.includes("slsa"))
+        return "provenance";
+    if (type.includes("cosign") || type.includes("signature") || type.includes("sig."))
+        return "signature";
+    return undefined;
+}
+/**
+ * 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 function createOrasReferrerLookup(options) {
+    const runner = options.runner ?? defaultProcessRunner();
+    return {
+        async discover(digest) {
+            await requireTool(runner, "oras", `discover OCI referrers for ${options.repo}@${digest}`);
+            const ref = `${options.repo.replace(/\/+$/, "")}@${digest}`;
+            const { stdout } = await runner.run(`oras discover --format json ${q(ref)}`);
+            let parsed;
+            try {
+                parsed = JSON.parse(stdout);
+            }
+            catch {
+                return []; // no referrers / unexpected output shape — degrade to "none known", never throw on a parse hiccup.
+            }
+            const referrers = [];
+            for (const descriptor of parsed.manifests ?? []) {
+                const kind = classify(descriptor);
+                if (!kind)
+                    continue;
+                referrers.push({
+                    kind,
+                    mediaType: descriptor.artifactType ?? descriptor.mediaType,
+                    digest: descriptor.digest,
+                    location: `${options.repo}@${descriptor.digest}`,
+                });
+            }
+            return referrers;
+        },
+    };
+}

package/dist/lifecycle/override-ledger.js

@@ -0,0 +1,54 @@
+/**
+ * The override gate's lines on `chant/lifecycle` (#3760): read the denials,
+ * overrides and applied records, record a denial, and record that a run
+ * applied under an override, which spends it. The decision is
+ * `../override-gate.ts`'s, which bundles without this module's git code.
+ *
+ * Denials and overrides share `_gates/policy-override.jsonl` with the
+ * ordinary gate line shapes, so `chant approve`, `chant operator status` and
+ * the audit reader read them as they read any gate. Applied records live in
+ * `_gates/policy-override/applied.jsonl`, which no gate reader lists.
+ */
+import { sortedJsonReplacer } from "../utils.js";
+import { appendPendingGate, readGateLedger } from "./gate-ledger.js";
+import { readBlobBySha, readBlobFromPath, readPathSha, RefCASConflictError, writeBlobToPath } from "./git.js";
+import { OVERRIDE_OP, parseAppliedOverrides, overridePending, } from "../override-gate.js";
+const APPLIED_DIR = `_gates/${OVERRIDE_OP}`;
+const APPLIED_FILE = "applied.jsonl";
+const APPEND_RETRY_ATTEMPTS = 5;
+/** The override ledger and its applied records, oldest first. Empty when nothing is recorded. */
+export async function readOverrideLedger(opts) {
+    const { resolutions, pending } = await readGateLedger(OVERRIDE_OP, opts);
+    const text = await readBlobFromPath(APPLIED_DIR, APPLIED_FILE, opts);
+    return { resolutions, pending, applied: text ? parseAppliedOverrides(text) : [] };
+}
+/** Append a denial's pending fact ({@link overridePending}). Does not push. */
+export async function recordOverrideDenial(input, opts) {
+    const { version: _v, kind: _k, ...rest } = overridePending(input);
+    const { commit, record } = await appendPendingGate(rest, opts);
+    return { commit, record: record };
+}
+/** Append applied records, spending the overrides they name. Write them before applying; a write that fails should stop the run. Does not push. */
+export async function recordOverridesApplied(records, opts) {
+    if (records.length === 0)
+        return undefined;
+    const lines = records.map((r) => JSON.stringify(r, sortedJsonReplacer)).join("\n");
+    let lastErr;
+    for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+        try {
+            const priorSha = await readPathSha(APPLIED_DIR, APPLIED_FILE, opts);
+            const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+            const content = `${existing ? `${existing.replace(/\n$/, "")}\n` : ""}${lines}\n`;
+            return await writeBlobToPath(APPLIED_DIR, APPLIED_FILE, content, `Applied under override: ${records.map((r) => r.gate).join(", ")}`, {
+                ...opts,
+                expectPriorPathSha: priorSha,
+            });
+        }
+        catch (err) {
+            if (!(err instanceof RefCASConflictError))
+                throw err;
+            lastErr = err;
+        }
+    }
+    throw lastErr;
+}

package/dist/lifecycle/plan-digest.js

@@ -0,0 +1,110 @@
+/**
+ * Plan identity for a gate (#2300, measured on INTENTIUS/choudoufu#1026).
+ *
+ * A gate resolution used to carry the op, the gate, the approver and a
+ * timestamp, and nothing about what was approved. Approve, edit the root,
+ * re-run, and the second run re-planned and applied: the resolution had
+ * authorised the *next run* of that op rather than the plan the approver
+ * read. This module is the missing half — one string that identifies a plan,
+ * written onto the pending fact the run records, onto the resolution `chant
+ * approve` appends, and compared by {@link latestResolutionForPlan} when a
+ * later run decides the gate.
+ *
+ * ## What a digest covers
+ *
+ * The change set, and only the change set: what a run proposes to create,
+ * update, replace or destroy, at which addresses, with which values. Two
+ * plans share a digest exactly when applying either one would do the same
+ * thing to the estate.
+ *
+ * ## What it deliberately does not cover
+ *
+ * - **When the plan was taken.** A plan file's own `timestamp`, and the
+ *   resolution's. Re-planning an unchanged root a minute later must produce
+ *   the same digest, or every approval would expire on the clock rather than
+ *   on the content.
+ * - **Which run took it.** `runId`, the CI job number, the workflow attempt.
+ *   Approving a plan and re-running the workflow is the whole loop; binding
+ *   the run id would make the approval unusable by the run that consumes it.
+ * - **The tool that produced it.** The terraform/choudoufu version, the plan
+ *   file's binary bytes and its path on disk. The digest is taken over the
+ *   `show -json` rendering rather than the file, so a plan-format bump does
+ *   not read as a changed plan.
+ * - **Who approved it, or where.** `resolvedBy`, `note`, `url` — those
+ *   describe the approval, not the plan.
+ *
+ * The identity is therefore a claim about consequence, not about provenance.
+ * That is the claim an approver is actually making.
+ */
+import { canonicalJson } from "../effect-receipt.js";
+import { contentDigest } from "../content-digest.js";
+/** The hash a plan digest is taken with. */
+export const PLAN_DIGEST_ALGORITHM = "sha256";
+/**
+ * The version prefix a plan digest is written with since #2547: `jcs1` names
+ * the input form (the RFC 8785 canonical JSON of `{ kind, subject }`, see
+ * `canonicalJson` in ../effect-receipt.ts) and `sha256` the hash. A later
+ * input form gets a new prefix, so a digest always says how it was made.
+ */
+export const PLAN_DIGEST_PREFIX = "jcs1-sha256:";
+/** The bare prefix every digest written before #2547 carries. Still read, never written for a plan. */
+export const LEGACY_PLAN_DIGEST_PREFIX = "sha256:";
+/** Shape of a well-formed digest: either prefix, then 64 lowercase hex characters. */
+const PLAN_DIGEST_PATTERN = /^(?:jcs1-)?sha256:([0-9a-f]{64})$/;
+/**
+ * Hash a plan's change set into a stable identity.
+ *
+ * `kind` names the shape `subject` is in (`"terraform-plan"`,
+ * `"lifecycle-diff"`), and is hashed alongside it so two different kinds of
+ * plan can never collide into the same digest by coincidence — a gate bound
+ * to a terraform plan must not be satisfiable by a lifecycle diff that
+ * happened to serialize identically.
+ *
+ * `subject` is put in canonical form by `canonicalJson` (../effect-receipt.ts)
+ * and hashed by `contentDigest` (../content-digest.ts), so object key order,
+ * which neither terraform's JSON writer nor `JSON.parse` guarantees across
+ * versions, does not change the answer. It is the caller's job to
+ * hand in a projection that already excludes the volatile fields this
+ * module's doc comment lists.
+ *
+ * The result is `jcs1-sha256:<hex>` (#2547). Before that it was
+ * `sha256:<hex>` over the same bytes, so the hex is unchanged and
+ * {@link samePlanDigest} treats the two spellings as one digest: a gate
+ * recorded under the old prefix still matches the plan it was approved for.
+ */
+export function computePlanDigest(kind, subject) {
+    return PLAN_DIGEST_PREFIX + contentDigest(canonicalJson({ kind, subject })).slice(LEGACY_PLAN_DIGEST_PREFIX.length);
+}
+/**
+ * Whether `raw` is a digest this code produced, in either prefix. Used at the
+ * `chant approve --plan` boundary, so a typo, a truncated copy-paste or a plan
+ * *file* path is refused before it is written into an immutable resolution
+ * that would then never match anything.
+ */
+export function isPlanDigest(raw) {
+    return typeof raw === "string" && PLAN_DIGEST_PATTERN.test(raw);
+}
+/**
+ * Whether two recorded or computed plan digests name the same plan. Two
+ * well-formed plan digests are the same when their hex is, whichever prefix
+ * each carries (read both, write new, #2547). Anything else, such as a
+ * release plan's own digest, is the same only when the strings are equal.
+ */
+export function samePlanDigest(a, b) {
+    if (a === b)
+        return true;
+    if (a === undefined || b === undefined)
+        return false;
+    const x = PLAN_DIGEST_PATTERN.exec(a);
+    const y = PLAN_DIGEST_PATTERN.exec(b);
+    return x !== null && y !== null && x[1] === y[1];
+}
+/**
+ * A digest as it reads in a message, and the one place that decides how an
+ * absent one reads. Records written before #2300 carry no digest at all, and
+ * "(none — recorded before plan-bound gates)" is what a refusal has to say
+ * about them instead of printing `undefined`.
+ */
+export function describePlanDigest(digest) {
+    return digest ?? "(none — recorded before plan-bound gates)";
+}