@intentius/chant 0.124.13 → 0.124.14

package/dist/op/activities/lifecycle.js

@@ -0,0 +1,109 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import { computePlanDigest } from "../../lifecycle/plan-digest.js";
+const execAsync = promisify(exec);
+/**
+ * Take a chant lifecycle snapshot for the given environment.
+ * Uses fastIdempotent profile — 5m timeout, 3 retries.
+ */
+export async function lifecycleSnapshot(args, signal) {
+    const { stdout, stderr } = await execAsync(`chant lifecycle snapshot ${args.env}`, { signal });
+    if (stdout)
+        console.log(stdout);
+    if (stderr)
+        console.error(stderr);
+}
+/**
+ * The change set half of a `chant lifecycle diff` render, canonicalised for
+ * digesting (#2300).
+ *
+ * The diff render is line-oriented: section headers and the resource rows
+ * under them. Two runs over an unchanged environment print the same lines, so
+ * the lines are the change set. Normalising is deliberately minimal — CRLF to
+ * LF, trailing whitespace off each line, blank lines dropped — because
+ * anything more aggressive would start discarding rows, and a digest that
+ * discards rows is a digest that approves changes nobody saw.
+ *
+ * Unlike a terraform plan there is no timestamp to strip: the diff render
+ * carries none. If one is ever added it has to be dropped here, or every
+ * approval would be stale the moment it was written.
+ */
+export function normalizeDiffChangeSet(output) {
+    return output
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => line.replace(/\s+$/, ""))
+        .filter((line) => line !== "");
+}
+/**
+ * Section headers emitted by `chant lifecycle diff --live` that indicate a
+ * non-empty drift category. See packages/core/src/cli/handlers/state.ts.
+ */
+const DRIFT_HEADERS = [
+    "MISSING",
+    "ORPHAN",
+    "DISAPPEARED",
+    "DRIFTED",
+    // An owned resource whose live properties differ from its declaration (the
+    // deep read): a sql table's TTL changed out of band, say (#3642).
+    "PROPERTY DRIFT",
+    // A change an apply would make that no declared property shows: a
+    // privilege granted by hand on a Postgres table (#3706).
+    "PENDING",
+    "ARTIFACTS ADDED",
+    "ARTIFACTS REMOVED",
+    "ARTIFACTS CHANGED",
+];
+/** True when a `chant lifecycle diff` render carries any of {@link DRIFT_HEADERS}' sections. */
+export function detectDrift(output) {
+    return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
+}
+/**
+ * The identity of one `chant lifecycle diff` result (#2300). The environment
+ * and the `--live` flag are hashed alongside the change set because they say
+ * what the change set is *of*: the same rows against `staging` are not an
+ * approval to apply against `prod`.
+ */
+export function lifecycleDiffDigest(args, output) {
+    return computePlanDigest("lifecycle-diff", {
+        env: args.env,
+        live: args.live === true,
+        changeSet: normalizeDiffChangeSet(output),
+    });
+}
+/**
+ * Run `chant lifecycle diff <env>` and return the output + structured drift
+ * flag. Read-only; intended for use inside watch/observation Ops.
+ * Uses fastIdempotent profile.
+ *
+ * The `drifted` field is computed by scanning the output for any of the
+ * MISSING / ORPHAN / DRIFTED / DISAPPEARED / PROPERTY DRIFT section headers documented in
+ * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
+ * on a WatchOp activity step to surface drift as the run's `Drift` outcome.
+ *
+ * A diff that exits non-zero (#3712) fails the step and yields no digest.
+ * Its output is an error, not a change set: every failed run printed the
+ * same lines, so a digest over them was one an approval matched whatever
+ * the declarations had become since.
+ */
+export async function lifecycleDiff(args, signal) {
+    const liveFlag = args.live ? " --live" : "";
+    const command = `chant lifecycle diff ${args.env}${liveFlag}`;
+    let stdout;
+    let stderr;
+    try {
+        ({ stdout, stderr } = await execAsync(command, { signal }));
+    }
+    catch (err) {
+        const e = err;
+        const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+        if (output)
+            console.error(output);
+        const message = `${command} failed (exit ${String(e.code ?? 1)}); no plan to digest${output ? `:\n${output}` : ""}`;
+        throw new Error(message);
+    }
+    const output = `${stdout}${stderr}`.trim();
+    if (output)
+        console.log(output);
+    return { output, exitCode: 0, drifted: detectDrift(output), planDigest: lifecycleDiffDigest(args, output) };
+}

package/dist/op/activities/pipeline-audit.js

@@ -0,0 +1,147 @@
+/**
+ * pipelineSupplyChainAudit — the live counterpart to the gitlab post-synth
+ * include/component/image checks (#297).
+ *
+ * Some include/component checks can only be answered against a moving external
+ * truth: whether a pinned component/include ref still resolves upstream, whether
+ * the upstream project was archived or moved, or whether a new advisory now
+ * covers a component/image already in use. These change independent of the
+ * source, so they cannot live in the deterministic build — this activity owns
+ * *only* the checks that require live resolution.
+ *
+ * Dependency-free and primitives-only: it reads the emitted `.gitlab-ci.yml`
+ * (passed as a string) and resolves references through an injectable
+ * `GitlabRefResolver`, so `chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+/**
+ * Collect `include:project` (+ ref), `component:` (with @version), and `image:`
+ * references from a `.gitlab-ci.yml`.
+ */
+export function collectPipelineRefs(yaml) {
+    const out = [];
+    // include:\n  - project: group/proj\n    ref: main
+    const projectRe = /-\s+project:\s*['"]?([^\s'"]+)['"]?[\s\S]*?ref:\s*['"]?([^\s'"]+)['"]?/g;
+    let m;
+    while ((m = projectRe.exec(yaml)) !== null) {
+        out.push({ refKind: "include", identifier: m[1], ref: m[2] });
+    }
+    // - component: host/group/comp@1.0.0
+    const componentRe = /-\s+component:\s*['"]?([^\s'"@]+)@([^\s'"]+)['"]?/g;
+    while ((m = componentRe.exec(yaml)) !== null) {
+        out.push({ refKind: "component", identifier: m[1], ref: m[2] });
+    }
+    // Images: inline `image: name` or block `image:\n  name: ...` (and services).
+    const lines = yaml.split("\n");
+    const imgSeen = new Set();
+    const addImage = (raw) => {
+        const image = raw.trim().replace(/^['"]|['"]$/g, "");
+        if (!image || image.includes("$") || imgSeen.has(image))
+            return;
+        imgSeen.add(image);
+        const at = image.lastIndexOf("@");
+        const colon = image.lastIndexOf(":");
+        const ref = at !== -1 ? image.slice(at + 1) : colon > image.lastIndexOf("/") ? image.slice(colon + 1) : "latest";
+        out.push({ refKind: "image", identifier: image, ref });
+    };
+    for (let i = 0; i < lines.length; i++) {
+        const inline = lines[i].match(/^\s+image:[ \t]+(\S.*)$/);
+        if (inline) {
+            addImage(inline[1]);
+            continue;
+        }
+        if (/^\s+image:\s*$/.test(lines[i]) || /^\s+-\s+name:[ \t]+(\S.*)$/.test(lines[i])) {
+            const svcName = lines[i].match(/^\s+-\s+name:[ \t]+(\S.*)$/);
+            if (svcName) {
+                addImage(svcName[1]);
+                continue;
+            }
+            const nameLine = lines.slice(i + 1, i + 4).find((l) => /^\s+name:[ \t]+/.test(l));
+            if (nameLine)
+                addImage(nameLine.replace(/^\s+name:[ \t]+/, ""));
+        }
+    }
+    return out;
+}
+/**
+ * Default resolver: query the GitLab REST API for project existence / archive /
+ * move status. Best-effort and resilient — errors yield an "unknown" resolution
+ * (exists=true, no findings) rather than a false positive. Component/image
+ * advisory lookups are left to a configured resolver.
+ */
+export const defaultGitlabRefResolver = async (kind, identifier) => {
+    const unknown = { exists: true, archived: false, advisories: [] };
+    if (kind === "image")
+        return unknown; // image advisory feeds are resolver-specific
+    const host = "https://gitlab.com";
+    const project = kind === "component" ? identifier.split("/").slice(1, 3).join("/") : identifier;
+    try {
+        const resp = await fetch(`${host}/api/v4/projects/${encodeURIComponent(project)}`, {
+            headers: process.env.GITLAB_TOKEN ? { "PRIVATE-TOKEN": process.env.GITLAB_TOKEN } : {},
+        });
+        if (resp.status === 404)
+            return { exists: false, archived: false, advisories: [] };
+        if (!resp.ok)
+            return unknown;
+        const p = (await resp.json());
+        return { exists: true, archived: !!p.archived, advisories: [] };
+    }
+    catch {
+        return unknown;
+    }
+};
+function renderSummary(findings) {
+    if (findings.length === 0)
+        return "## Pipeline include/component audit\n\nNo live drift detected against upstream references.\n";
+    let out = `## Pipeline include/component audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+    out += "| Reference | Ref | Finding | Detail |\n|---|---|---|---|\n";
+    for (const f of findings)
+        out += `| ${f.identifier} (${f.refKind}) | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+    return out;
+}
+async function readFileBestEffort(path) {
+    try {
+        const { readFile } = await import("node:fs/promises");
+        return [await readFile(path, "utf-8")];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve each include/component/image reference in the emitted pipeline against
+ * live upstreams and report drift.
+ */
+export async function pipelineSupplyChainAudit(args) {
+    const resolver = args.resolver ?? defaultGitlabRefResolver;
+    const mode = args.mode ?? "report";
+    let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+    if (yamls.length === 0) {
+        yamls = await readFileBestEffort(args.pipelineFile ?? ".gitlab-ci.yml");
+    }
+    const findings = [];
+    const seen = new Set();
+    for (const yaml of yamls) {
+        for (const { refKind, identifier, ref } of collectPipelineRefs(yaml)) {
+            const key = `${refKind}:${identifier}@${ref}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const res = await resolver(refKind, identifier, ref);
+            if (!res.exists) {
+                findings.push({ kind: "unresolved", refKind, identifier, ref, detail: `${refKind} "${identifier}@${ref}" no longer resolves upstream` });
+                continue;
+            }
+            if (res.archived) {
+                findings.push({ kind: "archived", refKind, identifier, ref, detail: `${identifier} has been archived upstream` });
+            }
+            if (res.movedTo) {
+                findings.push({ kind: "moved", refKind, identifier, ref, detail: `${identifier} moved to ${res.movedTo}` });
+            }
+            for (const adv of res.advisories) {
+                findings.push({ kind: "advisory", refKind, identifier, ref, detail: `disclosed advisory ${adv} covers ${identifier}` });
+            }
+        }
+    }
+    return { mode, findings, summary: renderSummary(findings) };
+}

package/dist/op/activities/policy.js

@@ -0,0 +1,26 @@
+import { nonRetryableFailure } from "../activity-failure.js";
+import { evaluateProjectPolicies } from "../../lint/policy.js";
+/**
+ * Gate an apply on organizational policy: build the project, run its
+ * `lint.policies` over the resolved resources, and **block** on any violation.
+ * Place it as a step before the apply phase — a violation fails the run
+ * (non-retryable; the `policyCheck` profile is single-attempt) so nothing is
+ * applied. A clean evaluation passes through.
+ *
+ * A plain activity on every runtime, not a `gate` step.
+ */
+export async function policyGate(args, _signal) {
+    const { violations, suppressed, env } = await evaluateProjectPolicies({ path: args.path ?? ".", env: args.env });
+    if (violations.length > 0) {
+        const summary = violations
+            .map((v) => `[${v.checkId}]${v.entity ? ` ${v.entity}:` : ""} ${v.message}`)
+            .join("; ");
+        throw nonRetryableFailure(`Organizational policy blocked the apply — ${violations.length} violation(s): ${summary}`, "PolicyViolation");
+    }
+    // chant #1138 — a check `lint.rules` turned "off" is counted here rather
+    // than vanishing silently, mirroring `chant build`'s own suppressed-count line.
+    if (suppressed.length > 0) {
+        console.log(`[policy] ${suppressed.length} finding(s) suppressed via lint.rules`);
+    }
+    console.log(`[policy] ${env ? `env=${env}: ` : ""}no violations — apply may proceed`);
+}

package/dist/op/activities/predict-behaviour.js

@@ -0,0 +1,341 @@
+/**
+ * The `predictBehaviour` activity and the pull-request finding built on it
+ * (#2358, epic #2355).
+ *
+ * Two activities, because they answer two questions:
+ *
+ *  - {@link predictBehaviour} asks the project's predicting lexicon what the
+ *    declared estate would do at a stated traffic level, and returns the
+ *    {@link BehaviourResult} as the contract defines it — a report, or a named
+ *    refusal. It builds the project in-process, assembles the request from the
+ *    build the way `lifecycle plan` assembles a deep read's, and hands it to
+ *    the one configured lexicon that implements the fourth observation method.
+ *    `isBehaviourRefusalReport` is the branch every consumer of its result
+ *    takes first.
+ *  - {@link behaviourFinding} runs that prediction twice — once on the
+ *    checkout the run is in (the pull request's head) and once on the base
+ *    branch it targets — differences the two under the rules in
+ *    `../../behaviour-delta.ts`, and posts the finding in `comment` mode
+ *    through {@link reconcilePr}. Same sticky comment on GitHub and Forgejo,
+ *    same merge-request note on GitLab, same marker recipe: nothing here
+ *    posts anything itself.
+ *
+ * ## The base side is a checkout, not a snapshot
+ *
+ * The finding is declared-versus-declared: the graph the pull request
+ * proposes against the graph its base branch already holds. Both sides are
+ * built from source, so the base branch is checked out into a detached git
+ * worktree under the repository's own root (module resolution walks up from
+ * there to the same `node_modules` the head build uses) and removed again
+ * whether the prediction succeeded or not. A shallow CI clone does not carry
+ * the base branch, so it is fetched at depth one first — the same reason
+ * `converge.ts` fetches `chant/lifecycle` before reading it.
+ *
+ * The base branch name comes off the run's own event, the way the pull
+ * request itself does in `reconcile.ts`: `GITHUB_BASE_REF` on a GitHub
+ * Actions or Forgejo Actions `pull_request` job, `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`
+ * on a GitLab `merge_request_event` pipeline. A run with neither and no
+ * explicit `base` fails by name rather than guessing `main`.
+ *
+ * ## What the marker names
+ *
+ * The comment's hidden marker names the Op and the env together
+ * ({@link behaviourFindingMarker}), for #2319's reason: a `comment`-mode
+ * `reconcilePr` step on the same pull request keys its marker on the env
+ * alone, and a behaviour finding over `prod` sharing a marker with a plan
+ * finding over `prod` would edit the wrong comment on every push.
+ *
+ * ## Edge coverage on the declared path
+ *
+ * `buildGraphIr` produces reference edges and is exhaustive for them. It
+ * produces no containment — a subnet's membership of a VPC is not a reference
+ * — and #2360's third comment records that nothing on the declared path does
+ * yet. So the request never claims `complete`: that would be a true claim
+ * about references and a false one about the graph. It cannot honestly claim
+ * `partial` either, because `partial` has to name a gap as `dangling` or
+ * `unresolvedKinds`, and the gap here is neither — every reference resolved,
+ * and the generic builder has no vocabulary for "this kind is a boundary
+ * whose containment is missing" (the request fixture names its boundary
+ * kinds by hand, which is lexicon knowledge core does not have). An earlier
+ * draft named every kind no reference touched, and named a queue nobody
+ * references as "unresolved", which it is not. So the claim is `unknown`,
+ * which the contract tells a consumer to treat exactly as it treats
+ * `partial`, and the finding shows each side's coverage and does not compare
+ * resilience verdicts across it — see `renderBehaviourFinding`.
+ */
+import { exec } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { isBehaviourRefusalReport, } from "../../behaviour.js";
+import { behaviourDelta, renderBehaviourFinding, validateBehaviourResult, } from "../../behaviour-delta.js";
+import { createBehaviourPredict } from "../../behaviour-predict.js";
+import { markerSlug, reconcilePr, suppliedMarker } from "./reconcile.js";
+const execAsync = promisify(exec);
+function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * What the activity says when nothing has contributed coverage rows.
+ *
+ * Not an error and not a refusal: the prediction runs, every declared entity
+ * is withheld as `unknown-type`, and this is what the report's own detail says
+ * one level down. Kept as a message rather than a throw because an estate
+ * whose lexicons contribute no rows is a real state with a real answer — "no
+ * row says what any of these are" — and a throw would turn it into a broken
+ * command (#2382).
+ */
+export function noContributedRowsMessage(lexicons) {
+    const configured = lexicons.length > 0 ? lexicons.join(", ") : "(none)";
+    return ("predictBehaviour has the estate to predict and no coverage rows to read it with: none of the " +
+        `configured lexicons (${configured}) contributes \`behaviourKinds\`. Every entity will be reported ` +
+        "unpredicted as `unknown-type`. Set CHANT_BEHAVIOUR_ENGINE to the engine's address, and add rows " +
+        "in the lexicon that owns the entity types you expect priced.");
+}
+/**
+ * The declared path's honest coverage claim. See the module doc: reference
+ * edges are exhaustive and containment is absent, and the contract has a
+ * field for a missing reference and none for missing containment, so the
+ * claim is `unknown`. Never `complete`, and not `partial` naming a kind the
+ * generic builder has no basis to name. A function rather than a constant so
+ * the day the declared path produces containment edges (#2360), the claim
+ * changes here and nowhere else.
+ */
+export function declaredEdgeCoverage() {
+    return { verdict: "unknown" };
+}
+/**
+ * Predict the estate declared under `projectPath`. The in-process half of
+ * {@link predictBehaviour}, taking the project root explicitly so the
+ * finding can run it on the base checkout too.
+ *
+ * Imports are dynamic so this module carries no load-time edge into the CLI
+ * or the build: `cli/plugins` reaches back into the root index, and the
+ * activity registry imports this module statically.
+ */
+export async function predictDeclared(projectPath, args) {
+    const { loadChantConfigUpward } = await import("../../config.js");
+    const { loadPlugins, resolveProjectLexicons } = await import("../../cli/plugins.js");
+    const { build } = await import("../../build.js");
+    const { buildGraphIr } = await import("../../graph-ir.js");
+    const { config } = await loadChantConfigUpward(projectPath);
+    const lexicons = await resolveProjectLexicons(projectPath);
+    const plugins = (await loadPlugins(lexicons));
+    // Rows, not a predictor. Since #2382 core predicts and each lexicon says
+    // only what its own entity types mean, so there is nothing to choose between
+    // and nothing to refuse when two lexicons both answer — they are additive.
+    const kinds = plugins.map((p) => p.behaviourKinds).filter((k) => k !== undefined);
+    const sourceDir = resolve(projectPath, config.sourceDir ?? ".");
+    const result = await build(sourceDir, plugins.map((p) => p.serializer));
+    if (result.errors.length > 0) {
+        const messages = result.errors.map((e) => (typeof e === "string" ? e : e.message ?? String(e)));
+        throw new Error(`predictBehaviour: the project under ${projectPath} did not build: ${messages.join("; ")}`);
+    }
+    // Every declared entity with a type. The contributed rows decide what
+    // reaches the engine and what is declared unmapped, and they can only decide
+    // about what they are handed: filtering here to "resources" would silently
+    // drop the kinds the coverage rows exist to name.
+    const entities = new Map();
+    for (const [name, entity] of result.entities) {
+        const declarable = entity;
+        if (typeof declarable.entityType !== "string")
+            continue;
+        entities.set(name, {
+            entityType: declarable.entityType,
+            props: (declarable.props != null ? declarable.props : {}),
+        });
+    }
+    const edges = buildGraphIr(result.entities, sourceDir).edges;
+    // The build output the other three reads are handed — a string, not a path
+    // (cli/handlers/lifecycle.ts). Nothing on this path reads it; the mirror is
+    // kept so the four methods take the same shape. With no predicting lexicon
+    // to take it from, it is the first output the build produced, or empty.
+    const raw = [...result.outputs.values()][0];
+    const buildOutput = raw === undefined ? "" : typeof raw === "string" ? raw : raw.primary;
+    const options = {
+        environment: args.environment,
+        buildOutput,
+        entityNames: [...entities.keys()],
+        entities,
+        ...(args.stack ? { stack: args.stack } : {}),
+        ...(args.region ? { region: args.region } : {}),
+        ...(args.owned !== undefined ? { owned: args.owned } : {}),
+        traffic: args.traffic,
+        edges,
+        edgeCoverage: declaredEdgeCoverage(),
+        // This activity builds from `discover` + `build`, never from an account —
+        // it is the declared estate by construction, on whichever checkout it runs.
+        from: "declared",
+    };
+    const answer = await createBehaviourPredict({ kinds })(options);
+    // On arrival, with the names that were asked — `behaviourReport` checks the
+    // ordinary route and says a consumer that needs the guarantee checks again.
+    return validateBehaviourResult(answer, options.entityNames);
+}
+/**
+ * Predict the declared estate in the working directory at `args.traffic`.
+ * Returns the contract's result as it is; a refusal is a result, not a
+ * thrown error, and `isBehaviourRefusalReport` is the branch to take first.
+ * Uses the `fastIdempotent` profile: the build is offline and the engine call
+ * is read-only.
+ */
+export async function predictBehaviour(args) {
+    return predictDeclared(resolve("."), args);
+}
+/**
+ * The hidden marker a behaviour finding is found by across re-runs. Keyed on
+ * the Op *and* the env, both slugified the same way `reconcilePr`'s markers
+ * are, and distinct from both of those by its prefix: a `comment`-mode
+ * `reconcilePr` step and this step on one pull request must never match each
+ * other's comment.
+ */
+export function behaviourFindingMarker(op, env) {
+    return `<!-- chant-behaviour:${markerSlug(op)}/${markerSlug(env)} -->`;
+}
+/** What the finding says when the run names no base branch to predict against. */
+export function noBaseRefMessage() {
+    return ("behaviourFinding predicts the pull request's declared estate against its base branch's, and this run " +
+        "names no base branch. On GitHub Actions and Forgejo Actions a pull_request event sets GITHUB_BASE_REF; on " +
+        "GitLab CI a merge_request_event pipeline sets CI_MERGE_REQUEST_TARGET_BRANCH_NAME. Trigger the Op from " +
+        "one of those, or pass `base` with the branch name.");
+}
+/** Where the base branch name comes from, most specific first. Pure — exported for testing. */
+export function baseRefFrom(env, explicit) {
+    const fromArgs = explicit?.trim();
+    if (fromArgs)
+        return fromArgs;
+    for (const source of ["GITHUB_BASE_REF", "CI_MERGE_REQUEST_TARGET_BRANCH_NAME"]) {
+        const value = env[source]?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** What the head side is called in the finding: the source branch when the run names one, else the short commit. */
+export function headRefFrom(env, shortSha) {
+    for (const source of ["GITHUB_HEAD_REF", "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"]) {
+        const value = env[source]?.trim();
+        if (value)
+            return value;
+    }
+    return shortSha?.trim() || "head";
+}
+/**
+ * Check `base` out into a detached worktree beside the repository. Fetches it
+ * at depth one first, because a CI clone carries only the pull request's own
+ * ref; a branch already present locally (a full clone, a developer's own
+ * checkout) is used as it stands after the fetch fails.
+ */
+export async function checkoutBase(base, signal) {
+    const { stdout: rootOut } = await execAsync("git rev-parse --show-toplevel", { signal });
+    const { stdout: prefixOut } = await execAsync("git rev-parse --show-prefix", { signal });
+    const root = rootOut.trim();
+    const prefix = prefixOut.trim();
+    let commitish = "FETCH_HEAD";
+    try {
+        await execAsync(`git fetch --depth=1 origin ${shellQuote(base)}`, { signal });
+    }
+    catch {
+        // No remote, or no such branch there: a local branch of that name is
+        // the only other thing `base` can honestly mean.
+        commitish = base;
+    }
+    const dir = await mkdtemp(join(root, ".chant-behaviour-base-"));
+    try {
+        await execAsync(`git worktree add --detach ${shellQuote(dir)} ${shellQuote(commitish)}`, { signal });
+    }
+    catch (err) {
+        await rm(dir, { recursive: true, force: true });
+        throw new Error(`behaviourFinding could not check out base branch ${JSON.stringify(base)}: ${err.message}`);
+    }
+    return {
+        projectPath: prefix ? join(dir, prefix) : dir,
+        async cleanup() {
+            try {
+                await execAsync(`git worktree remove --force ${shellQuote(dir)}`);
+            }
+            catch {
+                await rm(dir, { recursive: true, force: true });
+            }
+        },
+    };
+}
+async function defaultShortSha() {
+    try {
+        const { stdout } = await execAsync("git rev-parse --short HEAD");
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the finding activity, with its four side effects injected so a test
+ * can drive the whole thing — predict twice, difference, render, post —
+ * against fixtures and a stubbed poster.
+ */
+export function createBehaviourFinding(deps = {}) {
+    const predict = deps.predict ?? predictDeclared;
+    const checkout = deps.checkout ?? checkoutBase;
+    const post = deps.post ?? reconcilePr;
+    const env = deps.env ?? process.env;
+    const shortSha = deps.shortSha ?? defaultShortSha;
+    return async function behaviourFinding(args, signal) {
+        const mode = args.mode ?? "comment";
+        if (typeof args.op !== "string" || args.op.trim() === "") {
+            throw new Error("behaviourFinding needs `op`, the name of the Op this step belongs to: it keys the comment's marker " +
+                "together with `environment`, and an env alone is not unique across Ops (#2319).");
+        }
+        const base = baseRefFrom(env, args.base);
+        if (!base)
+            throw new Error(noBaseRefMessage());
+        const head = headRefFrom(env, await shortSha());
+        const predictArgs = {
+            environment: args.environment,
+            traffic: args.traffic,
+            ...(args.stack ? { stack: args.stack } : {}),
+            ...(args.region ? { region: args.region } : {}),
+            ...(args.owned !== undefined ? { owned: args.owned } : {}),
+        };
+        // Head first: it is the checkout the run is already in, and a build error
+        // there is the pull request's own and should surface before any worktree
+        // is created.
+        const headResult = await predict(resolve("."), predictArgs);
+        const baseCheckout = await checkout(base, signal);
+        let baseResult;
+        try {
+            baseResult = await predict(baseCheckout.projectPath, predictArgs);
+        }
+        finally {
+            await baseCheckout.cleanup();
+        }
+        const finding = behaviourDelta({ label: "base", ref: base, result: baseResult }, { label: "head", ref: head, result: headResult });
+        const summary = renderBehaviourFinding(finding, { env: args.environment, op: args.op });
+        const refused = isBehaviourRefusalReport(baseResult) || isBehaviourRefusalReport(headResult);
+        const result = { mode, base, head, finding, refused, summary };
+        if (mode === "report")
+            return result;
+        const posted = await post({
+            env: args.environment,
+            op: args.op,
+            mode: "comment",
+            marker: suppliedMarker(behaviourFindingMarker(args.op, args.environment)),
+            body: summary,
+            title: args.title ?? `Predicted behaviour for ${args.environment} at ${args.traffic}`,
+        }, signal);
+        return {
+            ...result,
+            ...(posted.commentUrl ? { commentUrl: posted.commentUrl } : {}),
+            ...(posted.pullRequest ? { pullRequest: posted.pullRequest } : {}),
+            ...(posted.mergeRequest ? { mergeRequest: posted.mergeRequest } : {}),
+        };
+    };
+}
+/**
+ * Predict the pull request's declared estate and its base branch's, and post
+ * the delta as one sticky comment on the pull request — or one note on the
+ * merge request — that triggered the run. Needs a pull-request-triggered
+ * run; fails by name without one, the same way `reconcilePr`'s `comment`
+ * mode does, because that is the function that posts.
+ */
+export const behaviourFinding = createBehaviourFinding();