@intentius/chant 0.124.39 → 0.124.41

package/src/components/auto-release.ts

@@ -26,8 +26,10 @@
  * env vars, timestamp is a real `new Date()` taken at record time).
  */
 import { getHeadCommit, pushLifecycle, StaleLifecycleBranchError } from "../lifecycle/git";
-import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseAdmission, type ReleaseRecord, type RunOrigin } from "../lifecycle/release-ledger";
-import type { DriverStepRecord } from "./driver";
+import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseAdmission, type ReleaseDigestKind, type ReleaseRecord, type RunOrigin } from "../lifecycle/release-ledger";
+import { changeSetDigest } from "../change-set";
+import type { DriverComponent, DriverStepRecord } from "./driver";
+import { componentInputDigests } from "./fan-out-inputs";
 
 /**
  * A step output that represents a *promoted* artifact — a publish-family result
@@ -68,6 +70,32 @@ export function extractRunDigest(records: DriverStepRecord[]): string | undefine
   return found;
 }
 
+/**
+ * What each component of a run applied, for the ones that publish no artifact
+ * (#4274). A component with planned members (`pr-apply`'s change set) gets its
+ * plan digest: the one member's `planDigest`, or with several the
+ * change-set digest over them, the way a set's digest is taken. Any other gets
+ * its deploy-input digest from `componentInputDigests`, computed on first use.
+ */
+export function appliedDigestOf(input: {
+  /** Every component of the project, so a component's upstream digests count. */
+  components: DriverComponent[];
+  env: string;
+  projectRoot: string;
+  /** The planned members a pull request applied, when there were any. */
+  members?: ReadonlyArray<{ member: string; component: string; planDigest: string | null }>;
+}): (component: string) => AppliedDigest | null {
+  let inputs: Record<string, string> | undefined;
+  return (component) => {
+    const planned = (input.members ?? []).filter((m): m is typeof m & { planDigest: string } => m.component === component && m.planDigest !== null);
+    if (planned.length === 1) return { digest: planned[0]!.planDigest, kind: "plan" };
+    if (planned.length > 1) return { digest: changeSetDigest(planned), kind: "plan" };
+    inputs ??= componentInputDigests(input.components, { projectRoot: input.projectRoot, env: input.env });
+    const digest = inputs[component];
+    return digest === undefined ? null : { digest, kind: "deploy-input" };
+  };
+}
+
 /** Explicit reasons `maybeRecordAutoRelease` declined to write a record — never a thrown error, since "nothing to record" (or "opted out") is an expected, common outcome. */
 export type AutoReleaseSkipReason =
   | "opted-out"
@@ -109,6 +137,19 @@ export interface AutoReleaseRunInfo {
    * when the run published no artifact. Set only with `releaseDigest`.
    */
   templatesDigest?: string;
+  /**
+   * What the run applied, for a component that published no artifact (#4274):
+   * its plan digest, or its deploy-input digest when nothing planned. Recorded
+   * as `digest` with `digestKind`, after an artifact digest and
+   * `templatesDigest`, so an infrastructure-only component has a record too.
+   */
+  appliedDigest?: AppliedDigest;
+}
+
+/** A digest naming what a component applied, not an artifact (#4274). */
+export interface AppliedDigest {
+  digest: string;
+  kind: Extract<ReleaseDigestKind, "plan" | "deploy-input">;
 }
 
 /** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
@@ -142,7 +183,8 @@ function resolveActor(override?: string): string | undefined {
  *  - `run.success` false — defensive; callers should not reach here on failure.
  *  - no digest found in the run's records — a component with no publish step
  *    has nothing to bind a release record to, unless the run was made under a
- *    release that records its templates (`templatesDigest`, #4222).
+ *    release that records its templates (`templatesDigest`, #4222) or the
+ *    caller names what it applied (`appliedDigest`, #4274).
  *  - no resolvable actor — mirrors `runComponentsReleaseRecord`'s hard
  *    requirement; an unattributed record defeats the ledger's purpose.
  *
@@ -166,7 +208,10 @@ export async function maybeRecordAutoRelease(
     return { recorded: false, reason: "run-not-successful" };
   }
 
-  const digest = run.digest ?? extractRunDigest(run.records ?? []) ?? (run.releaseDigest ? run.templatesDigest : undefined);
+  const artifact = run.digest ?? extractRunDigest(run.records ?? []);
+  const templates = artifact === undefined && run.releaseDigest ? run.templatesDigest : undefined;
+  const digest = artifact ?? templates ?? run.appliedDigest?.digest;
+  const digestKind: ReleaseDigestKind | undefined = artifact !== undefined ? undefined : templates !== undefined ? "templates" : run.appliedDigest?.kind;
   if (!digest) {
     return { recorded: false, reason: "no-digest", detail: `component "${run.component}" published no digest-bearing artifact` };
   }
@@ -201,6 +246,7 @@ export async function maybeRecordAutoRelease(
         ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
         ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
         ...(run.releaseDigest ? { releaseDigest: run.releaseDigest } : {}),
+        ...(digestKind ? { digestKind } : {}),
       },
       { cwd: options.cwd },
     );

package/src/components/cli-support.ts

@@ -489,6 +489,8 @@ export interface RunComponentsResult {
   run?: DriverRunResult;
   /** Component names actually dispatched to the driver, in run order. */
   selected: string[];
+  /** The components dispatched, as they ran (#4274): what a component's deploy-input digest is taken over. */
+  components?: DriverComponent[];
   error?: string;
   /** Set when the run stopped at a `gate` nobody has approved (#2119): the component it stopped at and the pending fact recorded for it. */
   gated?: {
@@ -718,6 +720,7 @@ export async function runComponents(
         success: run.status === "ok",
         run,
         selected,
+        components: resolvedTargets,
         buildParams: options.buildParams,
         ...(run.status === "gated" && run.gate
           ? {
@@ -785,6 +788,7 @@ export async function runComponents(
       success: componentResult.ok,
       run,
       selected,
+      components: resolvedTargets,
       buildParams: options.buildParams,
       ...(componentResult.status === "gated" && componentResult.gate
         ? {

package/src/components/deploy-units.ts

@@ -59,6 +59,11 @@ export const DEPLOY_UNIT_RULES: readonly DeployUnitRule[] = [
   // A Terraform-family root (#3049). Its unit is the root's name in
   // `terraform.roots`, which is also the member a gated wave's digest names.
   { kind: "terraform-apply", field: "root", lexicon: "terraform" },
+  // An ARM template applied into one resource group (#4273). Its unit is the group.
+  { kind: "arm-deploy", field: "resourceGroup", lexicon: "azure" },
+  // A Config Connector manifest applied over REST (#4273). Its unit is the
+  // step's `stack`, the member its plan names.
+  { kind: "gcp-apply", field: "stack", lexicon: "gcp" },
 ];
 
 /** One resolved unit a component's deploy composition targets. */

package/src/components/fan-out-run.ts

@@ -129,6 +129,19 @@ export interface FanOutWaveGate {
    * do not exist yet. A later wave is left for its own job.
    */
   only?: number;
+  /**
+   * With `only` (#4291): members of earlier waves the record says failed to
+   * plan or to apply. Each blocks its dependents in this wave and names
+   * itself as what blocked them; the rest of the wave runs. An earlier
+   * member that neither applied nor failed still refuses the run.
+   */
+  failedEarlier?: readonly string[];
+  /**
+   * With `only` (#4291): earlier waves the record says stopped at their gate.
+   * A member left in one of them stops this wave too ({@link EarlierWaveWaitingError}),
+   * since a gate nobody approved stops every wave after it.
+   */
+  waitingEarlier?: ReadonlyArray<{ wave: number; gate: string; components: readonly string[] }>;
 }
 
 /** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
@@ -146,6 +159,22 @@ export class EarlierWaveNotAppliedError extends Error {
   }
 }
 
+/**
+ * Thrown when `FanOutWaveGate.only` names a wave after one that waits at its
+ * gate (#4291): nothing in this wave runs until that gate is approved and
+ * its job runs again. The CLI exits 3, as the waiting wave's job does.
+ */
+export class EarlierWaveWaitingError extends Error {
+  constructor(
+    readonly wave: number,
+    readonly earlier: number,
+    readonly gate: string,
+  ) {
+    super(`wave ${wave} does not run yet: wave ${earlier} waits at its gate ${gate}. Approve it and run wave ${earlier} again, then this wave.`);
+    this.name = "EarlierWaveWaitingError";
+  }
+}
+
 /** The single gate over a whole fan-out. Omit it to run without one. */
 export interface FanOutGate {
   /** The name `chant approve <op> <gate>` takes — the fan-out's name, not a component's. */
@@ -518,7 +547,13 @@ async function runGatedWaves(
       if (!wave) return { end: "stop" };
       const runnable = wave.filter((name) => left.has(name) && !blockedBy.has(name));
       if (waveGate.only !== undefined && waveNum < waveGate.only) {
-        if (runnable.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, runnable);
+        // #4291: an earlier member that failed blocks only its dependents; one that waits at its gate stops this wave.
+        const failedBefore = new Set(waveGate.failedEarlier ?? []);
+        const open = runnable.filter((name) => !failedBefore.has(name));
+        const waiting = waveGate.waitingEarlier?.find((w) => w.wave === waveNum && open.some((name) => w.components.includes(name)));
+        if (waiting) throw new EarlierWaveWaitingError(waveGate.only, waveNum, waiting.gate);
+        if (open.length > 0) throw new EarlierWaveNotAppliedError(waveGate.only, waveNum, open);
+        for (const name of runnable) markBlocked(name);
         return { end: "next" };
       }
       if (waveGate.only !== undefined && waveNum > waveGate.only) return { end: "stop" };
@@ -664,7 +699,9 @@ async function runGatedWaves(
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([component, by]) => ({ component, reason: "blocked" as const, blockedBy: by }));
 
-  const status: FanOutRunResult["status"] = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
+  // #4291: a member of this job's wave that an earlier job's failure blocked fails the job, though the rest of the wave applied.
+  const blockedHere = waveGate.only !== undefined && (plan.waves[waveGate.only - 1] ?? []).some((name) => blockedBy.has(name));
+  const status: FanOutRunResult["status"] = failed.length > 0 || blockedHere ? "fail" : gatedFact ? "gated" : "ok";
   emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
 
   return {

package/src/components/fan-out-waves.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, test } from "vitest";
 import { CapabilityRegistry, type DeployContext } from "./capability";
 import { memoryGateLedgerPort } from "../op/gate";
 import { planFanOut } from "./fan-out";
-import { EarlierWaveNotAppliedError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
+import { EarlierWaveNotAppliedError, EarlierWaveWaitingError, runFanOut, type FanOutRunOptions } from "./fan-out-run";
 import { computePlanDigest } from "../lifecycle/plan-digest";
 import type { DriverComponent } from "./driver";
 import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
@@ -354,6 +354,50 @@ describe("one wave per CI job", () => {
   });
 });
 
+describe("a failed member blocks only its dependents across wave jobs (#4291)", () => {
+  /** net, then a and b, then app (reads a) and web (reads b). */
+  const WIDE: DriverComponent[] = [...ESTATE, root("web", ["b"])];
+
+  test("wave 3's job blocks what an earlier job's failure holds, and plans the rest", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    const result = await runFanOut(plan, WIDE, w.registry, {
+      ...waveOptions(ledger()),
+      waveGate: { op: "fan-out", gate: "release", only: 3, failedEarlier: ["a"] },
+      progress: { completed: ["net", "b"] },
+    });
+    expect(result.blocked).toEqual([{ component: "app", reason: "blocked", blockedBy: "a" }]);
+    expect(w.planned.map((p) => p.root)).toEqual(["web"]);
+    // A member of the job's own wave was blocked, so the job fails though web went on to its gate.
+    expect(result.status).toBe("fail");
+  });
+
+  test("an earlier member that neither applied nor failed still refuses the job", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, WIDE, w.registry, {
+        ...waveOptions(ledger()),
+        waveGate: { op: "fan-out", gate: "release", only: 3, failedEarlier: ["a"] },
+        progress: { completed: ["net"] },
+      }),
+    ).rejects.toThrow(EarlierWaveNotAppliedError);
+  });
+
+  test("an earlier wave that waits at its gate stops the job", async () => {
+    const w = world();
+    const plan = planFanOut({ components: WIDE, changed: ["net"] });
+    await expect(
+      runFanOut(plan, WIDE, w.registry, {
+        ...waveOptions(ledger()),
+        waveGate: { op: "fan-out", gate: "release", only: 3, waitingEarlier: [{ wave: 2, gate: "release-wave-2", components: ["a", "b"] }] },
+        progress: { completed: ["net"] },
+      }),
+    ).rejects.toThrow(EarlierWaveWaitingError);
+    expect(w.planned).toEqual([]);
+  });
+});
+
 describe("both modes", () => {
   test("a run takes one gate over the set or one per wave, not both", async () => {
     const w = world();

package/src/components/pr-environment.test.ts

@@ -0,0 +1,249 @@
+/**
+ * A pull request's environment (#4298): what it derives from the template,
+ * the records that say which environments stand, and the ownership check a
+ * teardown runs before it deletes anything.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { ChantConfig } from "../config";
+import type { TeardownPlan, TeardownReport } from "../lifecycle/teardown";
+import type { ObservationLexicon, TeardownCandidate } from "../lexicon";
+import {
+  acceptHandedRecord,
+  derivePrEnvironment,
+  handedPrEnvReport,
+  expired,
+  isPrEnvironmentName,
+  livePrEnvironments,
+  ownedEntries,
+  parsePrEnvRecords,
+  prEnvStatusState,
+  releaseTargetRefusal,
+  renderPrEnvNote,
+  teardownComplete,
+  tearDownPrEnvironment,
+  teardownRefusal,
+  ttlMs,
+  type PrEnvRecord,
+} from "./pr-environment";
+
+const CONFIG: ChantConfig = {
+  environments: ["local", { name: "staging", endpoint: "http://localhost:4566" }, "prod", "pr-*"],
+  ownership: { stack: "shop", env: { param: "env" } },
+  buildParams: { env: { type: "string", default: "local" } },
+} as ChantConfig;
+
+function up(over: Partial<PrEnvRecord> = {}): PrEnvRecord {
+  return {
+    version: 1,
+    kind: "up",
+    pr: 7,
+    env: "pr-7",
+    template: "staging",
+    marker: { stack: "shop", env: "pr-7" },
+    commit: "a".repeat(40),
+    components: ["app"],
+    planDigest: "sha256:aa",
+    result: "applied",
+    by: "octo",
+    timestamp: "2026-10-22T10:00:00.000Z",
+    expiresAt: "2026-10-25T10:00:00.000Z",
+    releaseTarget: false,
+    ...over,
+  };
+}
+
+describe("deriving a pull request's environment", () => {
+  test("pr-<n> takes the template's endpoint and the marker env follows the build parameter", () => {
+    const d = derivePrEnvironment(CONFIG, "staging", 7);
+    expect(d).toMatchObject({ env: "pr-7", template: "staging", stack: "shop", param: "env", endpoint: "http://localhost:4566" });
+    if ("refusal" in d) throw new Error(d.refusal);
+    expect(d.environments?.[0]).toEqual({ name: "pr-7", endpoint: "http://localhost:4566" });
+  });
+
+  test("a pr-* entry's own endpoint wins over the template's", () => {
+    const config = { ...CONFIG, environments: ["staging", { name: "pr-*", endpoint: "http://localhost:9000" }] } as ChantConfig;
+    expect(derivePrEnvironment(config, "staging", 7)).toMatchObject({ endpoint: "http://localhost:9000" });
+  });
+
+  test("refuses when the resources could not be told apart from the template's", () => {
+    const off = derivePrEnvironment({ ...CONFIG, ownership: undefined } as ChantConfig, "staging", 7);
+    expect(off).toMatchObject({ refusal: expect.stringContaining("no ownership.stack") });
+    const literal = derivePrEnvironment({ ...CONFIG, ownership: { stack: "shop", env: "staging" } } as ChantConfig, "staging", 7);
+    expect(literal).toMatchObject({ refusal: expect.stringContaining('the literal "staging"') });
+    const unset = derivePrEnvironment({ ...CONFIG, ownership: { stack: "shop" } } as ChantConfig, "staging", 7);
+    expect(unset).toMatchObject({ refusal: expect.stringContaining("ownership.env is unset") });
+  });
+
+  test("refuses a template the config does not declare, and a name it would not take", () => {
+    expect(derivePrEnvironment(CONFIG, "qa", 7)).toMatchObject({ refusal: expect.stringContaining("do not declare") });
+    const noPattern = { ...CONFIG, environments: ["staging", "prod"] } as ChantConfig;
+    expect(derivePrEnvironment(noPattern, "staging", 7)).toMatchObject({ refusal: expect.stringContaining('add "pr-*"') });
+    const literal = { ...CONFIG, environments: ["staging", "pr-7", "pr-*"] } as ChantConfig;
+    expect(derivePrEnvironment(literal, "staging", 7)).toMatchObject({ refusal: expect.stringContaining("declared outright") });
+  });
+});
+
+describe("the records", () => {
+  test("an up makes an environment live, a destroying down ends it, an incomplete down leaves it", () => {
+    const records = [up(), up({ pr: 8, env: "pr-8", marker: { stack: "shop", env: "pr-8" } }), { ...up(), kind: "down" as const, result: "destroyed" as const }];
+    const live = livePrEnvironments(records);
+    expect([...live.keys()]).toEqual(["pr-8"]);
+    const incomplete = livePrEnvironments([up(), { ...up(), kind: "down", result: "incomplete" }]);
+    expect(incomplete.get("pr-7")?.teardownIncomplete).toBe(true);
+  });
+
+  test("a later up refreshes the expiry and keeps every component it ever applied", () => {
+    const live = livePrEnvironments([up(), up({ components: ["db"], expiresAt: "2026-10-26T10:00:00.000Z" })]).get("pr-7")!;
+    expect(live.components).toEqual(["app", "db"]);
+    expect(live.expiresAt).toBe("2026-10-26T10:00:00.000Z");
+    expect(expired(live, new Date("2026-10-26T10:00:00.000Z"))).toBe(true);
+    expect(expired(live, new Date("2026-10-25T10:00:00.000Z"))).toBe(false);
+  });
+
+  test("malformed lines are skipped", () => {
+    expect(parsePrEnvRecords(`not json\n${JSON.stringify(up())}\n{"version":2}\n`)).toHaveLength(1);
+  });
+});
+
+describe("the ownership check on teardown", () => {
+  const live = livePrEnvironments([up()]).get("pr-7")!;
+
+  test("passes for the pull request's own environment", () => {
+    expect(teardownRefusal(7, live, CONFIG.environments)).toBeUndefined();
+  });
+
+  test("refuses another pull request's record, a marker of another environment, and a declared environment", () => {
+    expect(teardownRefusal(8, live, CONFIG.environments)).toContain("not 8");
+    expect(teardownRefusal(7, { ...live, marker: { stack: "shop", env: "staging" } }, CONFIG.environments)).toContain("another environment's resources");
+    expect(teardownRefusal(7, live, ["staging", "pr-7"])).toContain("declared outright");
+  });
+
+  test("drops every planned entry whose marker is not exactly the environment's", () => {
+    const plan: TeardownPlan = {
+      environment: "pr-7",
+      stack: "shop",
+      entries: [
+        { lexicon: "k8s", name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "pr-7" } },
+        { lexicon: "k8s", name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "staging" } },
+        { lexicon: "k8s", name: "other", type: "K8s::Core::Service", marker: { stack: "other", env: "pr-7" } },
+      ],
+      holes: [],
+      skipped: [],
+    };
+    const owned = ownedEntries(plan, { stack: "shop", env: "pr-7" });
+    expect(owned.plan.entries.map((e) => e.marker)).toEqual([{ stack: "shop", env: "pr-7" }]);
+    expect(owned.dropped).toHaveLength(2);
+  });
+
+  test("a teardown with a failure, a skip or a hole is not complete", () => {
+    const plan: TeardownPlan = { environment: "pr-7", stack: "shop", entries: [], holes: [], skipped: [] };
+    const report = (outcome: TeardownReport["outcomes"][number]["outcome"]): TeardownReport => ({
+      environment: "pr-7",
+      stack: "shop",
+      plan,
+      outcomes: [{ lexicon: "k8s", name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "pr-7" }, outcome }],
+      unimplemented: [],
+    });
+    expect(teardownComplete(report("deleted"))).toBe(true);
+    expect(teardownComplete(report("retained"))).toBe(true);
+    expect(teardownComplete(report("failed"))).toBe(false);
+    expect(teardownComplete(report("skipped"))).toBe(false);
+    expect(teardownComplete({ ...report("deleted"), plan: { ...plan, holes: [{ lexicon: "k8s", name: "*", reason: "read-failed" }] } })).toBe(false);
+  });
+});
+
+describe("tearing down through the lexicons", () => {
+  const live = livePrEnvironments([up()]).get("pr-7")!;
+
+  /** A lexicon whose enumeration also returns another environment's resource, and records what it was asked to delete. */
+  function lexicon(): { plugin: ObservationLexicon; asked: { environment?: string; deleted: TeardownCandidate[] } } {
+    const asked: { environment?: string; deleted: TeardownCandidate[] } = { deleted: [] };
+    const plugin = {
+      name: "k8s",
+      async teardownOwned({ environment }: { environment: string }) {
+        asked.environment = environment;
+        return {
+          candidates: [
+            { name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "pr-7" } },
+            { name: "web", type: "K8s::Apps::Deployment", marker: { stack: "shop", env: "staging" } },
+          ],
+        };
+      },
+      async executeTeardown({ candidates }: { candidates: TeardownCandidate[] }) {
+        asked.deleted.push(...candidates);
+        return { outcomes: candidates.map((c) => ({ name: c.name, outcome: "deleted" as const })) };
+      },
+    } as unknown as ObservationLexicon;
+    return { plugin, asked };
+  }
+
+  test("deletes only what carries pr-<n>'s marker", async () => {
+    const { plugin, asked } = lexicon();
+    const torn = await tearDownPrEnvironment({ pr: 7, live, config: CONFIG, plugins: [plugin] });
+    if ("refusal" in torn) throw new Error(torn.refusal);
+    expect(asked.environment).toBe("pr-7");
+    expect(asked.deleted.map((c) => c.marker)).toEqual([{ stack: "shop", env: "pr-7" }]);
+    expect(teardownComplete(torn.report)).toBe(true);
+  });
+
+  test("a refused teardown reads and deletes nothing", async () => {
+    const { plugin, asked } = lexicon();
+    const torn = await tearDownPrEnvironment({ pr: 7, live: { ...live, marker: { stack: "shop", env: "staging" } }, config: CONFIG, plugins: [plugin] });
+    expect(torn).toMatchObject({ refusal: expect.stringContaining("nothing was torn down") });
+    expect(asked.environment).toBeUndefined();
+    expect(asked.deleted).toEqual([]);
+  });
+});
+
+describe("not a release target", () => {
+  test("a pr-<n> name is refused as a release's source or target, and nothing else is", () => {
+    expect(isPrEnvironmentName("pr-42")).toBe(true);
+    expect(isPrEnvironmentName("pr-")).toBe(false);
+    expect(isPrEnvironmentName("prod")).toBe(false);
+    expect(releaseTargetRefusal("pr-42")).toContain("never a release target");
+    expect(releaseTargetRefusal("staging")).toBeUndefined();
+  });
+
+  test("the note says so", () => {
+    const note = renderPrEnvNote({ stage: "up", pr: 7, env: "pr-7", template: "staging", head: "a".repeat(40), op: "pr-7", gate: "pr-env", digest: "sha256:aa", status: "waiting", components: [] });
+    expect(note).toContain("<!-- chant-pr-env:pr-7 -->");
+    expect(note).toContain("chant approve pr-7 pr-env --plan sha256:aa");
+    expect(note).toContain("is not a release target");
+    expect(prEnvStatusState({ status: "waiting" })).toBe("pending");
+  });
+});
+
+test("ttlMs reads minutes, hours and days", () => {
+  expect(ttlMs("90m")).toBe(5_400_000);
+  expect(ttlMs("72h")).toBe(259_200_000);
+  expect(ttlMs("7d")).toBe(604_800_000);
+  expect(ttlMs("1w")).toBeUndefined();
+});
+
+describe("what env-up hands on is checked as data (#4295)", () => {
+  const check = { pr: 7, head: "c".repeat(40), template: "staging", ttlMs: 3_600_000, now: new Date("2026-10-22T12:00:00.000Z"), by: "github-actions" };
+
+  test("a record for this pull request is kept with the post job's own commit, actor and expiry", () => {
+    const accepted = acceptHandedRecord(up({ expiresAt: "2099-01-01T00:00:00.000Z", commit: "d".repeat(40), by: "mallory" }), check);
+    if ("refusal" in accepted) throw new Error(accepted.refusal);
+    expect(accepted.record).toMatchObject({ pr: 7, env: "pr-7", commit: check.head, by: "github-actions", expiresAt: "2026-10-22T13:00:00.000Z", marker: { stack: "shop", env: "pr-7" }, releaseTarget: false });
+  });
+
+  test("a record for another environment, marker, template or member is refused", () => {
+    expect(acceptHandedRecord(up({ pr: 8, env: "pr-8" }), check)).toMatchObject({ refusal: expect.stringContaining("not pr-7") });
+    expect(acceptHandedRecord(up({ marker: { stack: "shop", env: "staging" } }), check)).toMatchObject({ refusal: expect.stringContaining("marker env") });
+    expect(acceptHandedRecord(up({ template: "prod" }), check)).toMatchObject({ refusal: expect.stringContaining("template") });
+    expect(acceptHandedRecord(up({ member: "api" }), check)).toMatchObject({ refusal: expect.stringContaining("member") });
+    expect(acceptHandedRecord({ ...up(), kind: "down", result: "destroyed" }, check)).toMatchObject({ refusal: expect.stringContaining("down record") });
+    expect(acceptHandedRecord("nonsense", check)).toMatchObject({ refusal: expect.stringContaining("does not read") });
+  });
+
+  test("a report for another environment is refused, and a kept one takes the post job's head and op", () => {
+    expect(handedPrEnvReport({ stage: "up", pr: 8, env: "pr-8", status: "applied" }, { pr: 7, head: "h" })).toMatchObject({ refusal: expect.any(String) });
+    expect(handedPrEnvReport(undefined, { pr: 7, head: "h" })).toMatchObject({ refusal: "The env-up job handed on no report." });
+    const kept = handedPrEnvReport({ stage: "up", pr: 7, env: "pr-7", status: "waiting", op: "pr-99", head: "x", digest: "sha256:aa", components: [{ component: "app", status: "planned", create: 1 }] }, { pr: 7, head: "h" });
+    if ("refusal" in kept) throw new Error(kept.refusal);
+    expect(kept.report).toMatchObject({ head: "h", op: "pr-7", status: "waiting", components: [{ component: "app", create: 1, delete: 0 }] });
+  });
+});