@intentius/chant 0.124.30 → 0.124.32

package/src/pr-loop.ts

@@ -28,6 +28,16 @@
  * and decides the gate against the new digest. The same plan applies; a moved
  * plan stops with both digests named and nothing applied.
  *
+ * ## A gate per wave on merge
+ *
+ * With `--wave-gate <gate>` (#4003) the apply runs a wave at a time, and
+ * plans each wave after the one before it applied. Wave 1 applies under the
+ * pull request's approval. A later wave whose new plan the approved change
+ * set covers (`planCoveredBy`) applies under that approval too; one whose
+ * plan moved waits at `<gate>-wave-<k>`, under the same op, for an approval
+ * of its new plan. The report's `waves` says which wave applied under which
+ * approval.
+ *
  * ## Inside a workspace member
  *
  * Each workspace member that generates the pipeline (#3465) runs its own
@@ -49,6 +59,15 @@ export const PR_REPORT_CONTRACT = 1;
 /** The first chant whose report can carry `deployedOutputs` (#4104). */
 export const PR_REPORT_DEPLOYED_OUTPUTS_FLOOR = "0.124.30";
 
+/** The first chant whose report can carry `waveGate` and `waves` (#4003). */
+export const PR_REPORT_WAVES_FLOOR = "0.124.32";
+/**
+ * The first chant whose report can carry `plannedOutputs`, `rounds`, a
+ * member's `unknownInputs`, `buildInputs`, `round` and `held`, and the `waiting` statuses
+ * (#3999).
+ */
+export const PR_REPORT_PLANNED_OUTPUTS_FLOOR = "0.124.32";
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -60,6 +79,16 @@ export function prOp(pr: number, member?: string): string {
   return member ? `pr-${pr}-${member}` : `pr-${pr}`;
 }
 
+/**
+ * The gate a round of an apply waits on (#3999): the pull request's own
+ * gate for the first, and `<gate>-round-<n>` for each one planned after an
+ * upstream applied. A workspace's `identity.gates` entry for `gate` covers
+ * every round.
+ */
+export function prRoundGate(gate: string, round: number): string {
+  return round <= 1 ? gate : `${gate}-round-${round}`;
+}
+
 /** Whether `op` is a pull request's gate op, with or without a member. Member names follow the declaration's name pattern. */
 export const PR_GATE_OP = /^pr-\d+(?:-[a-z0-9][a-z0-9-]*)?$/;
 
@@ -95,7 +124,13 @@ export type PrMemberStatus =
   /** The apply failed. */
   | "failed"
   /** Not applied because a member it depends on failed. */
-  | "blocked";
+  | "blocked"
+  /**
+   * Apply stage (#3999): held back because its plan read an upstream output
+   * that applied as another value, or was known only after apply. It waits
+   * on an approval of the plan the apply made for it afterwards (`rounds`).
+   */
+  | "waiting";
 
 export interface PrMember {
   /** The member's name in the change set: a root, for a terraform-family step. */
@@ -110,9 +145,48 @@ export interface PrMember {
   /**
    * Components this one depends on whose outputs changed when they applied
    * (apply stage). Its applied plan read the values from before, so the next
-   * run plans it again.
+   * run plans it again. Not written since #3999, which holds such a member
+   * back and plans it again in the same apply (`held`, `round`).
    */
   inputsMoved?: string[];
+  /**
+   * The upstream outputs its plan read that the change's plans could not
+   * say (#3999), as `<component>.<output>`, sorted: known only after that
+   * upstream applies. The approval does not cover what this member does
+   * with them; the apply plans it again once they are known.
+   */
+  unknownInputs?: string[];
+  /**
+   * The published artifact identities its plan read from a build in the
+   * same change (#3999), as `<component>.publish.<field>`, sorted: an image
+   * digest, say. Known only after the build runs, but never approved again:
+   * the build's provenance and attestation bind the digest, so the member
+   * applies without a later round.
+   */
+  buildInputs?: string[];
+  /** Apply stage (#3999): the round whose plan it applied or waits on, when not the first. */
+  round?: number;
+  /** Apply stage (#3999): why the first round's plan did not apply. */
+  held?: string;
+}
+
+/** A round of plans an apply made after an upstream applied (#3999), the report's `rounds`. */
+export interface PrRound {
+  /** 2 for the first plan made after an upstream applied, and on. */
+  round: number;
+  /** The gate it waits on: {@link prRoundGate}. */
+  gate: string;
+  /** The change-set digest of what the round planned. What its gate binds. */
+  digest: string;
+  /** The components planned again, in apply order. */
+  components: string[];
+  approval: PrApproval;
+  /** `waiting`: no approval stands for `digest`. `plan-failed`: a member failed to plan, so the round did not apply. */
+  status: "applied" | "failed" | "waiting" | "plan-failed";
+  /** With `waiting`: why an approval that stands does not count (`--require-review`). */
+  message?: string;
+  /** The change-set document the round planned. */
+  changeSet: ChangeSetDocument;
 }
 
 /** Where the approval stands for the planned digest. */
@@ -141,8 +215,19 @@ export type PrStatus =
   | "applied"
   /** Apply stage: a member failed to apply. Its dependents did not run. */
   | "failed"
+  /**
+   * Apply stage with `--wave-gate` and `--wave` (#4003): this wave applied,
+   * and a later wave of the change is still to run.
+   */
+  | "wave-applied"
   /** Apply stage: nothing applied, see `refusal`. */
-  | "refused";
+  | "refused"
+  /**
+   * Apply stage (#3999): the approved plans applied, except members held
+   * back after an upstream applied. They wait on the approval of the plan
+   * the last of `rounds` made.
+   */
+  | "waiting";
 
 /** Why an apply refused. */
 export type PrRefusal =
@@ -152,8 +237,45 @@ export type PrRefusal =
   | "plan-changed"
   /** The approval names someone who has not approved the pull request on the forge. */
   | "not-a-reviewer"
+  /** The approval names the pull request's author, or an author or committer of one of its commits (#4000). */
+  | "author-approved"
   /** No pull request merged this commit, so there is no approval to read. */
-  | "no-pull-request";
+  | "no-pull-request"
+  /** `--wave-gate` (#4003): the wave's new plan is not one the pull request approved, and no approval stands for it. */
+  | "wave-not-approved"
+  /** `--wave-gate`: an approval of the wave's gate stands for another digest, so its plan moved since. */
+  | "wave-plan-changed"
+  /** `--wave-gate` with `--wave <k>`: an earlier wave has work left, or no record says it applied. */
+  | "earlier-wave";
+
+/**
+ * One wave of an apply with `--wave-gate` (#4003): what it planned, where it
+ * got to, and which approval it applied or waits under.
+ */
+export interface PrWave {
+  /** 1-based, from the derivation (`selection.waves`). */
+  wave: number;
+  /** The components planned in it on the run that reached it. */
+  components: string[];
+  /** `applied`; `failed` or `plan-failed`; or `waiting` at its gate. */
+  status: "applied" | "failed" | "plan-failed" | "waiting";
+  /**
+   * `pull-request`: the approved change set covers the wave's plan, so it
+   * applies under the pull request's approval. `wave`: its plan moved, so it
+   * needs an approval of its own gate.
+   */
+  approval: "pull-request" | "wave";
+  /** The gate it applied or waits under: the pull request's, or `<wave gate>-wave-<k>`. */
+  gate: string;
+  /** The digest that gate binds: the pull request's change set, or the wave's new plan. */
+  digest: string;
+  /** Who approved that digest. */
+  approvedBy?: string[];
+  /** Waiting: an approval of the wave's gate stands for this other digest. */
+  approved?: string;
+  /** Why the approved change set does not cover the wave's plan, one line per member. */
+  moved?: string[];
+}
 
 /**
  * The document `pr-plan` and `pr-apply` write (`pr-report.schema.json`).
@@ -194,7 +316,28 @@ export interface PrReport {
    * {@link PR_REPORT_DEPLOYED_OUTPUTS_FLOOR}.
    */
   deployedOutputs?: Record<string, string[]>;
+  /**
+   * Per dependency in the change that a member was planned against (#3999),
+   * the names of the outputs its plan knows, sorted. An output it reads that
+   * is not here is known only after apply (a member's `unknownInputs`).
+   * Absent when no member read one. Added within contract 1 by chant
+   * {@link PR_REPORT_PLANNED_OUTPUTS_FLOOR}.
+   */
+  plannedOutputs?: Record<string, string[]>;
+  /**
+   * Apply stage (#3999): the rounds planned after an upstream applied, in
+   * order, each with its own gate and digest. Absent when nothing was held.
+   */
+  rounds?: PrRound[];
   approval: PrApproval;
+  /**
+   * The wave gate's base name with `--wave-gate` (#4003): wave k waits on
+   * `<waveGate>-wave-<k>` when its plan moved. Added within contract 1 by
+   * chant {@link PR_REPORT_WAVES_FLOOR}.
+   */
+  waveGate?: string;
+  /** With `waveGate`: each wave reached so far, in order. */
+  waves?: PrWave[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -252,6 +395,7 @@ const STATUS_WORDS: Record<PrMemberStatus, string> = {
   applied: "applied",
   failed: "apply failed",
   blocked: "blocked",
+  waiting: "waiting on its new plan",
 };
 
 function headline(report: PrReport): string {
@@ -268,11 +412,55 @@ function headline(report: PrReport): string {
       return `Applied ${members}.`;
     case "failed":
       return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${report.members.filter((m) => m.status === "applied").length} applied.`;
-    case "refused":
-      return "The apply refused.";
+    case "wave-applied": {
+      const applied = (report.waves ?? []).filter((w) => w.status === "applied").map((w) => w.wave);
+      const total = report.selection.waves.length;
+      return `Applied wave ${applied.at(-1) ?? "?"} of ${total}. The next wave runs in its own job.`;
+    }
+    case "refused": {
+      const waiting = report.waves?.find((w) => w.status === "waiting");
+      return waiting ? `Wave ${waiting.wave} waits at its gate ${code(waiting.gate)}; nothing in it applied.` : "The apply refused.";
+    }
+    case "waiting":
+      return `Applied ${report.members.filter((m) => m.status === "applied").length} of ${members}; ${report.members.filter((m) => m.status === "waiting").length} wait on an approval of the plan made after their upstream applied.`;
   }
 }
 
+/** Who a wave applied or waits under, as a table cell. */
+function waveApproval(w: PrWave): string {
+  const whose = w.approval === "pull-request" ? "the pull request's" : "its own";
+  const by = w.approvedBy?.length ? ` by ${w.approvedBy.map(code).join(", ")}` : w.status === "waiting" ? ", not approved yet" : "";
+  return `${whose} ${code(w.gate)}${by}`;
+}
+
+/**
+ * The waves of an apply with `--wave-gate` (#4003): a row per wave reached,
+ * saying which approval it applied under, then for a wave that waits the
+ * reason its plan moved and the approve command for its new plan.
+ */
+function waveLines(report: PrReport, approver: string): string[] {
+  const waves = report.waves ?? [];
+  if (waves.length === 0) return [];
+  const out = ["", "| Wave | Components | Status | Approval |", "|---:|---|---|---|"];
+  for (const w of waves) out.push(`| ${w.wave} | ${w.components.map(code).join(", ")} | ${w.status} | ${waveApproval(w)} |`);
+  for (const w of waves.filter((x) => x.status === "waiting")) {
+    out.push("", `Wave ${w.wave} was planned after the waves before it applied, and the approved plan does not cover it:`, "");
+    for (const why of w.moved ?? []) out.push(`- ${why}`);
+    if (w.approved) out.push("", `An approval of ${code(w.gate)} stands for ${code(w.approved)}, not for the plan now.`);
+    out.push(
+      "",
+      `Read wave ${w.wave}'s plan, ${code(w.digest)}, and approve it with:`,
+      "",
+      "```",
+      prApproveCommand({ op: report.op, gate: w.gate, digest: w.digest }, approver),
+      "```",
+      "",
+      "Then run the wave's apply job again.",
+    );
+  }
+  return out;
+}
+
 function approvalLines(report: PrReport, approver: string): string[] {
   const a = report.approval;
   if (report.status === "nothing") return [];
@@ -332,6 +520,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
       out.push("", "A member whose inputs moved applied the plan it was approved with. The next run plans it against the new values.");
     }
   }
+  out.push(...waveLines(report, options.approver ?? "<you>"));
   if (report.selection.unclaimed.length > 0) {
     out.push("", `Changed, and deployed by no component: ${report.selection.unclaimed.map(code).join(", ")}.`);
   }
@@ -340,9 +529,43 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     const each = deployed.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none yet"})`);
     out.push("", `Planned against outputs read from the deployed estate: ${each.join("; ")}.`);
   }
+  const planned = Object.entries(report.plannedOutputs ?? {});
+  if (planned.length > 0) {
+    const each = planned.map(([dep, names]) => `${code(dep)} (${names.length > 0 ? names.map(code).join(", ") : "none known"})`);
+    out.push("", `Planned against the outputs this change's plans say its upstreams will have: ${each.join("; ")}.`);
+  }
+  const unknown = [...new Set(report.members.flatMap((m) => (m.unknownInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+  if (unknown.length > 0) {
+    out.push(
+      "",
+      `Known only after apply: ${unknown.join("; ")}. This approval does not cover what those members do with them. ` +
+        "The apply plans them again once their upstream applied and asks for an approval of that plan.",
+    );
+  }
+  const fromBuild = [...new Set(report.members.flatMap((m) => (m.buildInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
+  if (fromBuild.length > 0) {
+    out.push(
+      "",
+      `From this pull request's build: ${fromBuild.join("; ")}. The image digest comes from this pull request's build, whose provenance binds it, ` +
+        "so those members apply with it once the build ran, without a second approval.",
+    );
+  }
+  for (const r of report.rounds ?? []) {
+    const what = `Round ${r.round} planned ${r.components.map(code).join(", ")} again after their upstream applied, digest ${code(r.digest)}`;
+    if (r.status === "waiting") {
+      if (r.message) out.push("", `> ${r.message}`);
+      out.push("", `${what}. Not approved yet. Approve it, then run the apply again with the same \`--resume\` record:`, "", "```", prApproveCommand({ op: report.op, gate: r.gate, digest: r.digest }, options.approver ?? "<you>"), "```");
+    } else {
+      out.push("", `${what}: ${r.status === "applied" ? `applied, approved by ${(r.approval.approvedBy ?? []).map(code).join(", ")}` : r.status === "plan-failed" ? "a member failed to plan" : "the apply failed"}.`);
+    }
+  }
   if (report.status !== "nothing") {
     out.push("", `Plan digest: ${code(report.digest)}`, "", ...approvalLines(report, options.approver ?? "<you>"));
   }
+  // #4003: with a gate per wave, a later wave's plan on merge may differ from this one.
+  if (report.stage === "plan" && report.status === "planned" && report.waveGate) {
+    out.push("", `On merge each wave after the first is planned again once the waves before it apply, and a wave whose plan moved stops at its own gate, ${code(`${report.waveGate}-wave-<k>`)}, for approval.`);
+  }
   const head = out.join("\n") + "\n";
   if (report.status === "nothing" || report.changeSet.members.length === 0) return head;
   const room = limit - [...head].length - 1;
@@ -374,19 +597,38 @@ export function prStatusDescription(report: PrReport): string {
     case "applied":
       text = `applied ${n} member${n === 1 ? "" : "s"}${digest}`;
       break;
+    case "wave-applied": {
+      const last = (report.waves ?? []).filter((w) => w.status === "applied").at(-1);
+      text = `applied wave ${last?.wave ?? "?"} of ${report.selection.waves.length}${last ? ` under ${last.approval === "pull-request" ? "the pull request's approval" : `${last.gate}`}` : ""}`;
+      break;
+    }
     case "failed":
       text = `apply failed for ${report.members.filter((m) => m.status === "failed").map((m) => m.member).join(", ")}`;
       break;
-    case "refused":
-      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+    case "waiting":
+      text = `waiting: ${report.members.filter((m) => m.status === "waiting").map((m) => m.member).join(", ")} planned again after an upstream applied, not approved yet`;
       break;
+    case "refused": {
+      const waiting = report.waves?.find((w) => w.status === "waiting");
+      if (waiting && (report.refusal === "wave-not-approved" || report.refusal === "wave-plan-changed")) {
+        text = `wave ${waiting.wave} waits at ${waiting.gate}: ${report.refusal === "wave-plan-changed" ? "its plan changed after its approval" : "its plan moved, approve it"}`;
+        break;
+      }
+      if (report.refusal === "earlier-wave") {
+        text = "refused: an earlier wave has not applied";
+        break;
+      }
+      text = `refused: ${report.refusal === "plan-changed" ? "the plan changed after review" : report.refusal === "not-a-reviewer" ? "the approver has not approved the pull request" : report.refusal === "author-approved" ? "the approver wrote the change" : report.refusal === "no-pull-request" ? "no pull request merged this commit" : "the plan is not approved"}`;
+      break;
+    }
   }
   return text.length > 140 ? text.slice(0, 137) + "..." : text;
 }
 
 /** The commit status state for a report: success, failure, or pending while it waits on approval. */
 export function prStatusState(report: PrReport): "success" | "failure" | "pending" {
-  if (report.status === "planned" || report.status === "applied" || report.status === "nothing") return "success";
-  if (report.status === "refused" && report.refusal === "not-approved") return "pending";
+  if (report.status === "planned" || report.status === "applied" || report.status === "wave-applied" || report.status === "nothing") return "success";
+  if (report.status === "refused" && (report.refusal === "not-approved" || report.refusal === "wave-not-approved")) return "pending";
+  if (report.status === "waiting") return "pending";
   return "failure";
 }

package/src/pr-report-url.ts

@@ -35,7 +35,7 @@
  */
 
 import { spawn } from "node:child_process";
-import { mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -44,17 +44,17 @@ export type ReportTarget =
   | { scheme: "file"; url: string; dir: string }
   | { scheme: "s3"; url: string; bucket: string; prefix: string };
 
-/** `--report-url` read, or why it can't be. */
-export function parseReportUrl(raw: string): ReportTarget | { error: string } {
+/** `--report-url` read, or why it can't be. `name` is what the error calls the value: the flag, or `ci.reportUrl` (#4160). */
+export function parseReportUrl(raw: string, name = "--report-url"): ReportTarget | { error: string } {
   const url = raw.trim();
   if (url.startsWith("file://")) {
     let dir: string;
     try {
       dir = fileURLToPath(url);
     } catch (err) {
-      return { error: `--report-url ${url}: ${err instanceof Error ? err.message : String(err)}` };
+      return { error: `${name} ${url}: ${err instanceof Error ? err.message : String(err)}` };
     }
-    if (!isAbsolute(dir)) return { error: `--report-url ${url}: a file URL names an absolute directory` };
+    if (!isAbsolute(dir)) return { error: `${name} ${url}: a file URL names an absolute directory` };
     return { scheme: "file", url: url.replace(/\/+$/, ""), dir };
   }
   const s3 = /^s3:\/\/([^/]+)\/?(.*)$/.exec(url);
@@ -62,7 +62,7 @@ export function parseReportUrl(raw: string): ReportTarget | { error: string } {
     const prefix = s3[2]!.replace(/\/+$/, "");
     return { scheme: "s3", url: `s3://${s3[1]}${prefix ? `/${prefix}` : ""}`, bucket: s3[1]!, prefix };
   }
-  return { error: `--report-url ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
+  return { error: `${name} ${url}: takes an s3://<bucket>/<prefix> or file://<directory> URL` };
 }
 
 /** The key a stage's files are kept under, below the URL: `<pr>/<commit>[/<member>]`. */
@@ -120,6 +120,58 @@ export function reportPut(target: ReportTarget, aws: AwsCli = realAwsCli): Repor
   };
 }
 
+/** Reads one object: `key` below the URL. Resolves null for an object that is not there, and rejects with a line a person can read for any other failure. */
+export type ReportGet = (key: string) => Promise<string | null>;
+
+/** Runs the AWS CLI with `args` and resolves its stdout, rejecting with its error line on a non-zero exit. */
+export type AwsRead = (args: string[]) => Promise<string>;
+
+/** The AWS CLI on PATH, read for the body `aws s3 cp <s3 url> -` prints. */
+export const realAwsRead: AwsRead = (args) =>
+  new Promise((resolveRead, reject) => {
+    const child = spawn(AWS_BINARY, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    let stderr = "";
+    child.stdout.on("data", (chunk: Buffer) => out.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (stderr.length < 4096) stderr += chunk.toString("utf8");
+    });
+    child.on("error", (err: NodeJS.ErrnoException) =>
+      reject(new Error(err.code === "ENOENT" ? "the AWS CLI (aws) is not on PATH; an s3 report URL is read with it" : err.message)),
+    );
+    child.on("close", (code) => {
+      if (code === 0) return resolveRead(Buffer.concat(out).toString("utf8"));
+      const line = stderr.trim().split("\n").filter(Boolean).at(-1) ?? "";
+      reject(new Error(`aws s3 cp exited ${code}${line ? `: ${line.slice(0, 300)}` : ""}`));
+    });
+  });
+
+/** What the AWS CLI says about an object that does not exist. */
+const S3_ABSENT = /\(404\)|Not Found|NoSuchKey|does not exist/i;
+
+/** A get for `target`. `aws` replaces the AWS CLI in a test. */
+export function reportGet(target: ReportTarget, aws: AwsRead = realAwsRead): ReportGet {
+  if (target.scheme === "file") {
+    return async (key) => {
+      try {
+        return readFileSync(join(target.dir, ...key.split("/")), "utf-8");
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+        throw err;
+      }
+    };
+  }
+  return async (key) => {
+    const object = `s3://${target.bucket}/${target.prefix ? `${target.prefix}/` : ""}${key}`;
+    try {
+      return await aws(["s3", "cp", object, "-", "--only-show-errors"]);
+    } catch (err) {
+      if (S3_ABSENT.test(messageOf(err))) return null;
+      throw err;
+    }
+  };
+}
+
 /** A stage's upload: its events as they are written, and its files at the end. */
 export interface PrReportUpload {
   /** The folder the stage's files go to: `<url>/<key>`. */

package/src/terraform/__fixtures__/advise.test.ts

@@ -1,5 +1,7 @@
 import { describe, test, expect } from "vitest";
 import { join } from "path";
+import { cpSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
 import {
   carveAdvise,
   carveJson,
@@ -50,10 +52,27 @@ describe("carve advise against the sample estate", () => {
     expect(byAddr["random_pet.suffix"].score).toBe(0);
     expect(byAddr["random_pet.suffix"].band).toBe("leave in Terraform");
 
-    // The report never proposes a mutation.
-    const text = formatCarveReport(r);
+    // The report never proposes a mutation. The estate path is the caller's,
+    // so it is masked before the check (#3169).
+    const text = formatCarveReport(r).split(r.from!).join("<estate>");
     expect(text).not.toMatch(/state rm|apply|destroy/i);
   });
+
+  test("the no-mutation check holds in a checkout whose path says apply or destroy (#3169)", async () => {
+    if (!parserAvailable) return;
+    const parent = mkdtempSync(join(tmpdir(), "carve-native-apply-destroy-"));
+    try {
+      const estate = join(parent, "sample-estate");
+      cpSync(ESTATE, estate, { recursive: true });
+      const r = await carveAdvise({ from: estate });
+      expect(r.ok).toBe(true);
+      const text = formatCarveReport(r);
+      expect(text).toContain(estate);
+      expect(text.split(r.from!).join("<estate>")).not.toMatch(/state rm|apply|destroy/i);
+    } finally {
+      rmSync(parent, { recursive: true, force: true });
+    }
+  });
 });
 
 /**

package/src/ts-loader.test.ts

@@ -1,7 +1,9 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { describe, expect, test } from "vitest";
-import { chantSourceDir, ensureTypeScriptLoader } from "./ts-loader";
+import { chantPackageSourceTarget, chantSourceDir, lexiconCompiledTwin, ensureTypeScriptLoader, ensureTypeScriptLoaderFor, typeScriptLoaderPending } from "./ts-loader";
 
 describe("ts-loader (#3878)", () => {
   const pkg = join(sep, "x", "node_modules", "@intentius", "chant");
@@ -20,4 +22,90 @@ describe("ts-loader (#3878)", () => {
   test("from source, the TypeScript loader is already there and nothing is registered", () => {
     expect(ensureTypeScriptLoader()).toBe(false);
   });
+
+  test("from source, no module asks for the loader (#3981)", () => {
+    expect(typeScriptLoaderPending()).toBe(false);
+    expect(ensureTypeScriptLoaderFor("/p/src/index.ts")).toBe(false);
+    expect(ensureTypeScriptLoaderFor("/p/dist/index.js")).toBe(false);
+  });
+
+  test("compiled, a JavaScript module leaves tsx unregistered (#3981)", () => {
+    const STATE = Symbol.for("chant.compiledCli");
+    const global = globalThis as { [STATE]?: { tsx: boolean } };
+    global[STATE] = { tsx: false };
+    try {
+      expect(typeScriptLoaderPending()).toBe(true);
+      expect(ensureTypeScriptLoaderFor("file:///p/dist/index.js")).toBe(false);
+      expect(ensureTypeScriptLoaderFor("/p/dist/meta.json")).toBe(false);
+      expect(global[STATE]).toEqual({ tsx: false });
+      global[STATE] = { tsx: true };
+      expect(typeScriptLoaderPending()).toBe(false);
+      expect(ensureTypeScriptLoaderFor("/p/src/index.ts")).toBe(true);
+    } finally {
+      delete global[STATE];
+    }
+  });
+});
+
+describe("chantPackageSourceTarget (#3981)", () => {
+  test("resolves a symlinked lexicon's root and pattern exports to their development source, by real path", () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-source-target-")));
+    try {
+      const lexicon = join(root, "lexicons", "demo");
+      mkdirSync(join(lexicon, "src", "generated"), { recursive: true });
+      writeFileSync(join(lexicon, "src", "index.ts"), "");
+      writeFileSync(join(lexicon, "src", "generated", "index.ts"), "");
+      writeFileSync(
+        join(lexicon, "package.json"),
+        JSON.stringify({
+          name: "@intentius/chant-lexicon-demo",
+          exports: {
+            ".": { development: "./src/index.ts", types: "./dist/index.d.ts", default: "./dist/index.js" },
+            "./*": { development: "./src/*.ts", types: "./dist/*.d.ts", default: "./dist/*.js" },
+            "./meta": "./dist/meta.json",
+          },
+        }),
+      );
+      mkdirSync(join(root, "project", "node_modules", "@intentius"), { recursive: true });
+      symlinkSync(lexicon, join(root, "project", "node_modules", "@intentius", "chant-lexicon-demo"), "dir");
+      mkdirSync(join(root, "project", "src"));
+      const parent = join(root, "project", "src", "infra.ts");
+
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo", parent)).toBe(join(lexicon, "src", "index.ts"));
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo/generated/index", parent)).toBe(join(lexicon, "src", "generated", "index.ts"));
+      // No development condition, a missing file, another scope or an absent package: left to Node.
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo/meta", parent)).toBeUndefined();
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo/missing", parent)).toBeUndefined();
+      expect(chantPackageSourceTarget("@other/chant-lexicon-demo", parent)).toBeUndefined();
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-absent", parent)).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("lexiconCompiledTwin (#3981)", () => {
+  test("points a lexicon's src/*.ts at its dist/*.js when that exists, and nothing else", () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-compiled-twin-")));
+    try {
+      const lexicon = join(root, "node_modules", "@intentius", "chant-lexicon-demo");
+      const other = join(root, "node_modules", "other");
+      for (const dir of [join(lexicon, "src", "generated"), join(lexicon, "dist", "generated"), join(other, "src"), join(other, "dist")]) {
+        mkdirSync(dir, { recursive: true });
+      }
+      writeFileSync(join(lexicon, "package.json"), JSON.stringify({ name: "@intentius/chant-lexicon-demo" }));
+      writeFileSync(join(other, "package.json"), JSON.stringify({ name: "other" }));
+      for (const file of ["src/generated/index.ts", "dist/generated/index.js", "src/only-source.ts"]) writeFileSync(join(lexicon, file), "");
+      for (const file of ["src/index.ts", "dist/index.js"]) writeFileSync(join(other, file), "");
+      const url = (path: string) => pathToFileURL(path).href;
+
+      expect(lexiconCompiledTwin(url(join(lexicon, "src", "generated", "index.ts")))).toBe(url(join(lexicon, "dist", "generated", "index.js")));
+      expect(lexiconCompiledTwin(url(join(lexicon, "src", "only-source.ts")))).toBeUndefined();
+      expect(lexiconCompiledTwin(url(join(lexicon, "dist", "generated", "index.js")))).toBeUndefined();
+      expect(lexiconCompiledTwin(url(join(other, "src", "index.ts")))).toBeUndefined();
+      expect(lexiconCompiledTwin("node:fs")).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });