@intentius/chant 0.124.51 → 0.124.54

package/src/op/local-executor.ts

@@ -35,6 +35,7 @@ import { contentDigest } from "../content-digest";
 import { parseDuration } from "./duration";
 import { stepLabel, withRunConsole, withStepConsole } from "./step-console";
 import { stepTimeoutProblem } from "./activity-profiles";
+import { knownOutputsOf } from "./activity-failure";
 import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateApprovalRule, type GateCheck, type GateLedgerPort, type WorkspaceGateStandIn } from "./gate";
 import { resolveWorkspaceRun, type WorkspaceRunCitation } from "./workspace-run-env";
 import { gateName } from "./gate-name";
@@ -98,7 +99,11 @@ export interface StepRecord {
    * predates the plural form. {@link StepRecord.outcomes} is the whole list.
    */
   outcome?: { name: string; value: unknown };
-  /** Every outcome attribute the step published, in authored order (#2105). Absent when it published none. */
+  /**
+   * Every outcome attribute the step published, in authored order (#2105).
+   * Absent when it published none. A failed step publishes the ones its
+   * activity knew before it failed (#4512; see `withKnownOutputs`).
+   */
   outcomes?: Array<{ name: string; value: unknown }>;
   error?: string;
   /** Set on a `gate` step that passed (#2119): who resolved it, when, and at what address. */
@@ -522,13 +527,7 @@ async function runStep(
       const result = await callWithTimeout(fn, args, timeoutMs, signal);
       if (step.id) resultsById.set(step.id, result);
       const record: StepRecord = { ...base, status: "ok", durationMs: Date.now() - start };
-      const attrs = outcomeAttributesOf(step);
-      // An attribute whose path the result does not hold is left off, rather than recorded as undefined.
-      const outcomes = attrs.map((a) => ({ name: a.name, value: resolvePath(result, a.from) })).filter((o) => o.value !== undefined);
-      if (outcomes.length > 0) {
-        record.outcomes = outcomes;
-        record.outcome = outcomes[0];
-      }
+      captureOutcomes(step, record, result);
       return { record, result };
     } catch (err) {
       // An open decision point (#2749) is not a failure and not worth a retry:
@@ -554,7 +553,26 @@ async function runStep(
       break;
     }
   }
-  return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) } };
+  const failed: StepRecord = { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) };
+  // #4512: a failed step still records the outcomes its activity knew before it
+  // failed, read off the last attempt's error, as terraformInit's root path.
+  const known = knownOutputsOf(lastErr);
+  if (known) captureOutcomes(step, failed, known);
+  return { record: failed };
+  }
+}
+
+/**
+ * Set `record`'s outcomes from the step's `outcomeAttribute` paths over
+ * `source`: the activity's result, or for a failed step the outputs it knew
+ * before it failed (#4512). An attribute whose path `source` does not hold is
+ * left off, rather than recorded as undefined.
+ */
+function captureOutcomes(step: ActivityStep, record: StepRecord, source: unknown): void {
+  const outcomes = outcomeAttributesOf(step).map((a) => ({ name: a.name, value: resolvePath(source, a.from) })).filter((o) => o.value !== undefined);
+  if (outcomes.length > 0) {
+    record.outcomes = outcomes;
+    record.outcome = outcomes[0];
   }
 }
 

package/src/pr-loop-bundle.test.ts

@@ -41,8 +41,11 @@ describe("the pull-request loop bundle", () => {
       "packages/core/src/pr-forge.ts",
       "packages/core/src/pr-loop.ts",
       "packages/core/src/pr-migrations.ts",
+      // The next-release floor constant (#4480): no imports.
+      "packages/core/src/release-floors.ts",
     ]);
-    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) the requires checks (#4301) and the migration notes (#4407), about 97 KB.
-    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(100 * 1024);
+    // About 89 KB today, after the hooks line (#4288), the blocked set (#4291), the scheduled-run reads (#4289) the requires checks (#4301) and the migration notes (#4407), about 97 KB; with the group lines (#4446), about 100 KB.
+    // 110 KB is the ruled ceiling (#4481, ruling 12, 2026-10-25), not a figure to lower by trimming note text.
+    expect(result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0)).toBeLessThan(110 * 1024);
   });
 });

package/src/pr-loop.test.ts

@@ -204,7 +204,8 @@ describe("the note", () => {
   test("a plan names the outputs read from upstream plans and the ones known only after apply (#3999)", () => {
     const note = renderPrNote(unknownReport);
     expect(note).toContain("Planned against the outputs this change's plans say its upstreams will have: `a` (`arn`).");
-    expect(note).toContain("Known only after apply: `app` reads `a.id`. This approval does not cover what those members do with them.");
+    expect(note).toContain("Known only after apply: `app` reads `a.id`. The apply plans those members again once their upstream applied.");
+    expect(note).toContain("anything else asks for an approval of its own");
     expect(renderPrNote(planReport)).not.toContain("Known only after apply");
     expect(note).toContain("From this pull request's build: `app` reads `img.publish.digest`. The image digest comes from this pull request's build");
     expect(renderPrNote(planReport)).not.toContain("From this pull request's build");
@@ -212,6 +213,18 @@ describe("the note", () => {
     expect(schema.required).not.toContain("plannedOutputs");
   });
 
+  test("a covered round names the first digest and the inputs filled in; an uncovered one gives the reason (#4419)", () => {
+    const covered = renderPrNote({
+      ...unknownReport,
+      status: "applied",
+      rounds: [{ ...waitingReport.rounds![0]!, status: "applied", approval: { status: "approved", approvedBy: ["github:rev"] }, covered: { digest: unknownReport.digest, filledInputs: ["a.id"] } }],
+    } as never);
+    expect(covered).toContain(`covered by the approval of \`${unknownReport.digest}\`, with \`a.id\` filled in, so it applied without a new approval`);
+    const not = renderPrNote({ ...unknownReport, rounds: [{ ...waitingReport.rounds![0]!, notCovered: "app now plans to create Bucket, which the first plan did not" }] } as never);
+    expect(not).toContain(`not covered by the approval of \`${unknownReport.digest}\`: app now plans to create Bucket, which the first plan did not.`);
+    expect(not).toContain("Not approved yet");
+  });
+
   test("a waiting apply names the round's digest and the command that approves it (#3999)", () => {
     const note = renderPrNote(waitingReport, { approver: "github:<your-login>" });
     expect(note).toContain("Applied 1 of 2 members; 1 wait on an approval of the plan made after their upstream applied.");
@@ -476,3 +489,46 @@ describe("new migration files in the plan note (#4407)", () => {
     expect(note).toContain("- not read: bad # heading `x`");
   });
 });
+
+describe("groups and fallbacks in the report and the note (#4446)", () => {
+  const groupDigest = `jcs1-sha256:${hex(7)}`;
+  const grouped: PrReport = {
+    ...planReport,
+    groups: [{ capability: "terraform-apply", components: ["a", "app"], wave: 1, digest: groupDigest, reads: [{ component: "app", ref: "a.id" }] }],
+    fallbacks: [{ component: "net", capability: "terraform-apply", kind: "backend", reason: "net keeps its state in another backend" }],
+    members: planReport.members.map((m) => ({ ...m, group: 0 })),
+  };
+
+  test("a report with a group and a fallback validates, and one without them still does", () => {
+    expect(schema.required).not.toContain("groups");
+    expect(schema.required).not.toContain("fallbacks");
+    expectValid(grouped);
+    expectValid(planReport);
+    expectValid({ ...grouped, groups: [{ ...grouped.groups![0]!, digest: null, error: "cannot compose" }] });
+  });
+
+  test("the note names the group and the reads its apply computes, and why a component fell back", () => {
+    const note = renderPrNote(grouped);
+    expect(note).toContain("`a` and `app` plan and apply as one (`terraform-apply`, wave 1); `app` reads `a.id`, known when the group applies.");
+    expect(note).toContain("Planned one by one, not as a group: `net` (`backend`): net keeps its state in another backend.");
+    expect(renderPrNote({ ...grouped, fallbacks: [{ ...grouped.fallbacks![0]!, kind: "off" }] })).not.toContain("not as a group");
+  });
+
+  test("an apply that stopped part way validates with each member's group outcome, and the note says what stays applied", () => {
+    const stopped: PrReport = {
+      ...grouped,
+      stage: "apply",
+      status: "failed",
+      approval: { status: "approved", approvedBy: ["github:alice"] },
+      members: [
+        { ...grouped.members[0]!, status: "applied", groupOutcome: "applied" },
+        { ...grouped.members[1]!, status: "failed", groupOutcome: "partial", error: "app: quota exceeded" },
+      ],
+    };
+    expectValid(stopped);
+    expectValid({ ...stopped, members: [stopped.members[0]!, { ...stopped.members[1]!, status: "not-started", groupOutcome: "not-started" }] });
+    const note = renderPrNote(stopped);
+    expect(note).toContain("The group's apply stopped part way: `a` applied and stays applied; `app` applied in part, and what applied stays. Nothing that applied is undone.");
+    expect(note).toContain("`pr-apply --resume` plans `app` again");
+  });
+});

package/src/pr-loop.ts

@@ -51,6 +51,7 @@ import type { ChangeSetAction, ChangeSetDocument } from "./change-set";
 import type { PrRequireOutcome } from "./pr-requires";
 import { renderMigrationLines, type PrMigrationFile } from "./pr-migrations";
 import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown } from "./plan-summary";
+import { NEXT_RELEASE } from "./release-floors";
 
 /** The schema a pull-request report names in `$schema`. */
 export const PR_REPORT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/pr-report/v1/pr-report.schema.json";
@@ -88,6 +89,15 @@ export const PR_REPORT_BEFORE_MERGE_FLOOR = "0.124.42";
 /** The first chant whose plan report can carry `migrations` (#4407). */
 export const PR_REPORT_MIGRATIONS_FLOOR = "0.124.49";
 
+/** The first chant whose report can carry a member's `reads`, known at plan or not. */
+export const PR_REPORT_READS_FLOOR = "0.124.52";
+
+/** The first chant whose report can carry the `not-started` member status (ws-107, #4440). */
+export const PR_REPORT_NOT_STARTED_FLOOR = NEXT_RELEASE;
+
+/** The first chant whose report can carry `groups`, `fallbacks`, and a member's `group` and `groupOutcome` (ws-107, #4446). */
+export const PR_REPORT_GROUPS_FLOOR = NEXT_RELEASE;
+
 /** The gate a pull request's apply waits on, unless the pipeline names another. */
 export const PR_APPLY_GATE = "pr-apply";
 
@@ -153,7 +163,55 @@ export type PrMemberStatus =
    * 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";
+  | "waiting"
+  /**
+   * Apply stage (ws-107, #4440): a member of a group whose apply stopped
+   * before its part began. Written by chant {@link PR_REPORT_NOT_STARTED_FLOOR}
+   * and newer.
+   */
+  | "not-started";
+
+/** One upstream a member reads outputs of (`PrMember.reads`). */
+export interface PrMemberRead {
+  /** The component (or stack) whose outputs it reads. */
+  upstream: string;
+  /** The output names it reads, sorted. `publish.<field>` for a published artifact. */
+  outputs: string[];
+  /** The ones its plan had no value for, sorted: known only after the upstream applies. Absent when every one was known. */
+  unknown?: string[];
+}
+
+/** How a member's part of a group apply ended, as its capability said (ws-107): `PrMember.groupOutcome`. */
+export type PrGroupOutcome = "applied" | "partial" | "failed" | "not-started" | "no-changes";
+
+/** Components one capability planned and applied as one (ws-107, #4446): the report's `groups`. */
+export interface PrGroup {
+  /** The kind of the capability every member's one step names. */
+  capability: string;
+  /** The members, by component, in apply order: upstreams first. */
+  components: string[];
+  /** The 1-based wave of `selection.waves` it ran in. */
+  wave: number;
+  /** The group digest folded into each member's `planDigest`. `null` when the group failed to plan. */
+  digest: string | null;
+  /** Why the group failed to plan. Every member is then `plan-failed`. */
+  error?: string;
+  /** Each read of another member its plan did not know, which the group's apply computes, sorted. Absent when none. */
+  reads?: Array<{ component: string; ref: string }>;
+}
+
+/**
+ * A component that could have joined a group and did not (ws-107, ruling 1,
+ * #4446): the report's `fallbacks`. `kind` is core's `steps`, `split` or
+ * `cycle`, or the capability's own; `off` means the capability's setting
+ * turns grouping off, and the note does not print it.
+ */
+export interface PrGroupFallback {
+  component: string;
+  capability: string;
+  kind: string;
+  reason: string;
+}
 
 export interface PrMember {
   /** The member's name in the change set: a root, for a terraform-family step. */
@@ -175,8 +233,10 @@ export interface PrMember {
   /**
    * 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.
+   * upstream applies. The apply plans the member again once they are known;
+   * the first approval covers that round when it does only what the preview
+   * showed with only these inputs filled in, and anything else waits for an
+   * approval of its own (`PrRound.covered`, `PrRound.notCovered`).
    */
   unknownInputs?: string[];
   /**
@@ -187,12 +247,25 @@ export interface PrMember {
    * applies without a later round.
    */
   buildInputs?: string[];
+  /**
+   * Every other component's output its steps read, one entry per upstream,
+   * by upstream: the output names, sorted, and under `unknown` the ones its
+   * plan had no value for. A read whose value the plan knew is here too, so
+   * a reader of the report sees each read between components from the plan
+   * on, not only the ones `unknownInputs` names. Added within contract 1 by
+   * chant {@link PR_REPORT_READS_FLOOR}.
+   */
+  reads?: PrMemberRead[];
   /** 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 blocked member's (#4291): the component whose failure held it, past any component blocked in between. */
   blockedBy?: string;
+  /** The index in the report's `groups` of the group it planned and applied with (#4446). Added within contract 1 by chant {@link PR_REPORT_GROUPS_FLOOR}. */
+  group?: number;
+  /** Apply stage (#4446): how its part of the group's apply ended. Absent when the group did not run. */
+  groupOutcome?: PrGroupOutcome;
 }
 
 /** A round of plans an apply made after an upstream applied (#3999), the report's `rounds`. */
@@ -210,6 +283,15 @@ export interface PrRound {
   status: "applied" | "failed" | "waiting" | "plan-failed";
   /** With `waiting`: why an approval that stands does not count (`--require-review`). */
   message?: string;
+  /**
+   * The first approval covered this round's plan (#4419): no gate of its own was
+   * decided. `digest` is the first approval's, which the coverage is bound
+   * to; `filledInputs` are the inputs it previewed as unknown and this plan
+   * had a value for, as `<component>.<output>`.
+   */
+  covered?: { digest: string; filledInputs: string[] };
+  /** Why the first approval did not cover this round, so it asked for its own (#4419). */
+  notCovered?: string;
   /** The change-set document the round planned. */
   changeSet: ChangeSetDocument;
 }
@@ -447,6 +529,15 @@ export interface PrReport {
    * {@link PR_REPORT_MIGRATIONS_FLOOR}.
    */
   migrations?: PrMigrationFile[];
+  /**
+   * The groups a capability planned and applied as one (ws-107, #4446), in
+   * plan order of their first member. On a resume, what is left of a group,
+   * grouped again. Absent when none formed. Added within contract 1 by chant
+   * {@link PR_REPORT_GROUPS_FLOOR}.
+   */
+  groups?: PrGroup[];
+  /** The components that could have grouped and did not, with why (#4446), sorted. Absent when none. Since {@link PR_REPORT_GROUPS_FLOOR}. */
+  fallbacks?: PrGroupFallback[];
   /** Component names: which changed, which run because they depend on one, and what the change touched that no component deploys. */
   selection: {
     changed: string[];
@@ -522,6 +613,7 @@ const STATUS_WORDS: Record<PrMemberStatus, string> = {
   failed: "apply failed",
   blocked: "blocked",
   waiting: "waiting on its new plan",
+  "not-started": "not started",
 };
 
 function headline(report: PrReport): string {
@@ -541,7 +633,8 @@ function headline(report: PrReport): string {
       return `Applied ${members}.`;
     case "failed": {
       const blocked = report.members.filter((m) => m.status === "blocked").length;
-      return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${blocked > 0 ? `${blocked} blocked, ` : ""}${report.members.filter((m) => m.status === "applied").length} applied.`;
+      const notStarted = report.members.filter((m) => m.status === "not-started").length;
+      return `The apply failed: ${report.members.filter((m) => m.status === "failed").length} failed, ${blocked > 0 ? `${blocked} blocked, ` : ""}${notStarted > 0 ? `${notStarted} not started, ` : ""}${report.members.filter((m) => m.status === "applied").length} applied.`;
     }
     case "wave-applied": {
       const applied = (report.waves ?? []).filter((w) => w.status === "applied").map((w) => w.wave);
@@ -576,6 +669,50 @@ function blockedLine(members: readonly PrMember[]): string | undefined {
   return `Blocked, so not applied: ${groups.join("; ")}. A failure blocks only the members that depend on it, so the rest went on.`;
 }
 
+/** `a`, `b` and `c`. */
+const listed = (items: string[]): string => (items.length > 1 ? `${items.slice(0, -1).join(", ")} and ${items.at(-1)}` : (items[0] ?? ""));
+
+const GROUP_OUTCOME_WORDS: Record<PrGroupOutcome, string> = {
+  applied: "applied and stays applied",
+  "no-changes": "had no changes",
+  partial: "applied in part, and what applied stays",
+  failed: "failed",
+  "not-started": "did not start",
+};
+
+/**
+ * The groups and fallbacks (#4446): a line per group naming its members and
+ * the reads its apply computes, how a group that stopped part way left each
+ * member, and why the components that could have grouped did not.
+ */
+function groupLines(report: PrReport): string[] {
+  const out: string[] = [];
+  for (const g of report.groups ?? []) {
+    const reads = (g.reads ?? []).map((r) => `${code(r.component)} reads ${code(r.ref)}`);
+    out.push(
+      "",
+      `${listed(g.components.map(code))} plan and apply as one (${code(g.capability)}, wave ${g.wave})` +
+        (g.error ? `; the group failed to plan, so nothing applies: ${g.error}.` : reads.length > 0 ? `; ${listed(reads)}, known when the group applies.` : "."),
+    );
+    const outcome = new Map(report.members.filter((m) => m.groupOutcome && g.components.includes(m.component)).map((m) => [m.component, m.groupOutcome!]));
+    const left = g.components.filter((c) => outcome.has(c) && outcome.get(c) !== "applied" && outcome.get(c) !== "no-changes");
+    if (left.length === 0) continue;
+    out.push(
+      "",
+      `The group's apply stopped part way: ${g.components.filter((c) => outcome.has(c)).map((c) => `${code(c)} ${GROUP_OUTCOME_WORDS[outcome.get(c)!]}`).join("; ")}. ` +
+        `Nothing that applied is undone. \`pr-apply --resume\` plans ${listed(left.map(code))} again, as one group where they still join, and applies them under this approval when the new plans are covered.`,
+    );
+  }
+  const byWhy = new Map<string, string[]>();
+  for (const f of report.fallbacks ?? []) {
+    if (f.kind === "off") continue;
+    const why = `(${code(f.kind)}): ${f.reason}`;
+    byWhy.set(why, [...(byWhy.get(why) ?? []), code(f.component)]);
+  }
+  if (byWhy.size > 0) out.push("", `Planned one by one, not as a group: ${[...byWhy].map(([why, names]) => `${names.join(", ")} ${why}`).join("; ")}.`);
+  return out;
+}
+
 /** The policy's lines in the note (#4294): what denied or held the plan, and how a denial is overridden. */
 function policyLines(report: PrReport): string[] {
   const p = report.policy;
@@ -675,10 +812,14 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
     out.push("", "| Member | Component | Status | Create | Update | Replace | Delete |", "|---|---|---|---:|---:|---:|---:|");
     for (const m of report.members) {
       const holes = memberHoleReasons(report, m.member);
+      // #4463: a member planned with stand-in values says so, naming them.
+      const placeholders = report.changeSet.members.find((x) => x.member === m.member)?.placeholders ?? [];
       const status =
         STATUS_WORDS[m.status] +
         (m.status === "blocked" && m.blockedBy ? ` by ${code(m.blockedBy)}` : "") +
+        (m.groupOutcome === "partial" ? ", applied in part" : m.groupOutcome === "no-changes" ? ", no changes" : "") +
         (m.inputsMoved?.length ? `, inputs from ${m.inputsMoved.join(", ")} moved` : "") +
+        (placeholders.length > 0 ? `, previewed with placeholders for ${placeholders.map(code).join(", ")}` : "") +
         (holes.length > 0 ? `; ${holes.length > 2 ? `${holes[0]}; and ${holes.length - 1} more, listed under Holes` : holes.join("; ")}` : "");
       // A member whose plan has holes and no entries says nothing about what
       // it changes, so its counts are unknown, not zero (#4084).
@@ -692,6 +833,7 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   }
   const blocked = blockedLine(report.members);
   if (blocked) out.push("", blocked);
+  out.push(...groupLines(report));
   out.push(...waveLines(report, options.approver ?? "<you>"));
   // #4288: the hooks that did not pass, by name; a passed hook is a count.
   const hooks = report.hooks ?? [];
@@ -719,8 +861,8 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   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.",
+      `Known only after apply: ${unknown.join("; ")}. ` +
+        "The apply plans those members again once their upstream applied. When that plan does only what this one shows, with only those inputs filled in, this approval covers it; anything else asks for an approval of its own.",
     );
   }
   const fromBuild = [...new Set(report.members.flatMap((m) => (m.buildInputs ?? []).map((ref) => `${code(m.component)} reads ${code(ref)}`)))];
@@ -733,6 +875,12 @@ export function renderPrNote(report: PrReport, options: { limit?: number; approv
   }
   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.covered) {
+      const filled = r.covered.filledInputs.length > 0 ? `, with ${r.covered.filledInputs.map(code).join(", ")} filled in` : "";
+      out.push("", `${what}: covered by the approval of ${code(r.covered.digest)}${filled}, so it ${r.status === "applied" ? "applied" : "did not apply"} without a new approval${r.status === "failed" ? " (the apply failed)" : ""}.`);
+      continue;
+    }
+    if (r.notCovered) out.push("", `Round ${r.round}'s plan is not covered by the approval of ${code(report.digest)}: ${r.notCovered}.`);
     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>"), "```");

package/src/pulumi-urn.ts

@@ -0,0 +1,151 @@
+/**
+ * Pulumi URN to graph node (#4456): the one rule every Pulumi reader uses.
+ *
+ * A Pulumi resource is named by its URN,
+ * `urn:pulumi:<stack>::<project>::<qualified type>::<name>`, where the
+ * qualified type is the parent type chain joined with `$` and the resource's
+ * own type last (`my:mod:Web$aws:lambda/function:Function`). The stack export
+ * the pulumi member kind renders, the steps of `pulumi preview --json` (the
+ * change set) and of `pulumi refresh --preview-only --json` (drift records)
+ * all carry that URN, and nothing else they all carry names the resource. So
+ * the node is a function of the URN alone:
+ *
+ * - The node key is the URN after its stack and project,
+ *   `<qualified type>::<name>`: `aws:s3/bucket:Bucket::assets`,
+ *   `my:mod:Web$aws:lambda/function:Function::handler`. Two stacks of one
+ *   program give the same keys, and a key never changes with the stack or
+ *   project name.
+ * - Inside a workspace the node id is `<member>/<key>`, as the terraform
+ *   lexicon names a block `<root>/<block key>`.
+ * - Provider resources (`pulumi:providers:*`, at any depth) and the root
+ *   `pulumi:pulumi:Stack` have no node: {@link pulumiNodeKey} is null, and a
+ *   change-set entry or drift record for one gets `node: null`.
+ *
+ * A child sits under its component through the `parent` edge the export
+ * gives, not through its id. A component's name is not part of its
+ * children's URNs, and a preview narrowed with `--target`, or a delete step,
+ * need not carry the chain of parents, so an id built from parent names
+ * could differ between the export and a change set for the same resource.
+ * The parent's type is part of the key, through the qualified type.
+ *
+ * Like `./change-set.ts`, this imports nothing at run time, so the change-set
+ * and drift-record bundles can carry it. The pulumi lexicon imports it as
+ * `@intentius/chant/pulumi-urn`.
+ */
+
+/** A URN split into its parts. */
+export interface PulumiUrn {
+  stack: string;
+  project: string;
+  /** The parent type chain and the resource's own type, joined with `$`. */
+  qualifiedType: string;
+  /** The resource's own type, the last of the chain. */
+  type: string;
+  /** The parent types, outermost first; empty for a resource whose parent is the stack. */
+  parentTypes: string[];
+  /** The resource's name; it may itself hold `::`. */
+  name: string;
+}
+
+const PREFIX = "urn:pulumi:";
+const PROVIDER_TYPE = /^pulumi:providers:/;
+/** The type of the root resource every stack has. */
+export const PULUMI_STACK_TYPE = "pulumi:pulumi:Stack";
+
+/** The parts of a Pulumi URN, or undefined when `urn` is not one. */
+export function parsePulumiUrn(urn: string): PulumiUrn | undefined {
+  if (!urn.startsWith(PREFIX)) return undefined;
+  const parts = urn.slice(PREFIX.length).split("::");
+  if (parts.length < 4) return undefined;
+  const [stack, project, qualifiedType] = parts;
+  const name = parts.slice(3).join("::");
+  if (!stack || !project || !qualifiedType || !name) return undefined;
+  const chain = qualifiedType.split("$");
+  return { stack, project, qualifiedType, type: chain[chain.length - 1], parentTypes: chain.slice(0, -1), name };
+}
+
+/** True for a resource that never gets a node: a provider or the root stack. */
+export function isPulumiNodeless(type: string): boolean {
+  return PROVIDER_TYPE.test(type) || type === PULUMI_STACK_TYPE;
+}
+
+/**
+ * The node key of a URN in its member's graph, `<qualified type>::<name>`.
+ * Null for a provider resource or the root stack. A string that is not a
+ * Pulumi URN is its own key, so a reader that holds something else still
+ * gets a stable id.
+ */
+export function pulumiNodeKey(urn: string): string | null {
+  const parsed = parsePulumiUrn(urn);
+  if (!parsed) return urn;
+  if (isPulumiNodeless(parsed.type)) return null;
+  return `${parsed.qualifiedType}::${parsed.name}`;
+}
+
+/** The node id of a URN inside a workspace, `<member>/<key>`, or null when it has no node. */
+export function pulumiNodeId(member: string, urn: string): string | null {
+  const key = pulumiNodeKey(urn);
+  return key === null ? null : `${member}/${key}`;
+}
+
+const MAY_APPEAR_TYPE = "$*";
+const MAY_APPEAR_NAME = "/*";
+
+/**
+ * The address of a change-set entry that stands for the resources a
+ * component may register inside an `apply()` that preview could not run
+ * (#4453): the component's URN with `$*` after its qualified type and `/*`
+ * after its name, `urn:pulumi:dev::site::my:web:Site$*::site/*`. It reads as
+ * any resource, of any type and name, whose parent chain is the component,
+ * and stays unique per component, since a component's URN is.
+ */
+export function pulumiMayAppearAddress(componentUrn: string): string {
+  const parsed = parsePulumiUrn(componentUrn);
+  if (!parsed) return `${componentUrn}${MAY_APPEAR_NAME}`;
+  return `${PREFIX}${parsed.stack}::${parsed.project}::${parsed.qualifiedType}${MAY_APPEAR_TYPE}::${parsed.name}${MAY_APPEAR_NAME}`;
+}
+
+/** The component URN a {@link pulumiMayAppearAddress} was made from, or undefined for any other address. */
+export function pulumiMayAppearParent(address: string): string | undefined {
+  const parsed = parsePulumiUrn(address);
+  if (!parsed || !parsed.qualifiedType.endsWith(MAY_APPEAR_TYPE) || !parsed.name.endsWith(MAY_APPEAR_NAME)) return undefined;
+  const qualifiedType = parsed.qualifiedType.slice(0, -MAY_APPEAR_TYPE.length);
+  const name = parsed.name.slice(0, -MAY_APPEAR_NAME.length);
+  if (!qualifiedType || !name) return undefined;
+  return `${PREFIX}${parsed.stack}::${parsed.project}::${qualifiedType}::${name}`;
+}
+
+/**
+ * The ids, in the order tried, that a Pulumi change-set entry or drift
+ * record can have in its member's graph IR, in the shape of
+ * `changeSetNodeCandidates` (`./change-set-graph.ts`): `<member>/<key>`.
+ * Empty for a provider or the root stack, so mapping leaves `node: null`.
+ * A may-appear entry ({@link pulumiMayAppearAddress}) is on its component's
+ * node, since nothing names the resources it stands for.
+ */
+export function pulumiNodeCandidates(entry: { member: string; address: string }): string[] {
+  const id = pulumiNodeId(entry.member, pulumiMayAppearParent(entry.address) ?? entry.address);
+  return id === null ? [] : [id];
+}
+
+/** One step of `pulumi preview --json` (or `refresh --preview-only --json`), as far as the node rule reads it. */
+export interface PulumiPreviewStep {
+  op?: string;
+  urn?: string;
+}
+
+/**
+ * The URN and node id of each step of a `pulumi preview --json` document
+ * (`{ steps: [...] }`). A replace shows as several steps on one URN; each
+ * gets the same node. Steps with no URN are skipped.
+ */
+export function pulumiPreviewNodes(preview: unknown, member: string): { urn: string; op: string; node: string | null }[] {
+  const steps = (preview as { steps?: unknown } | null)?.steps;
+  if (!Array.isArray(steps)) return [];
+  const out: { urn: string; op: string; node: string | null }[] = [];
+  for (const s of steps as PulumiPreviewStep[]) {
+    if (typeof s?.urn !== "string") continue;
+    out.push({ urn: s.urn, op: typeof s.op === "string" ? s.op : "", node: pulumiNodeId(member, s.urn) });
+  }
+  return out;
+}

package/src/release-floors.ts

@@ -0,0 +1,22 @@
+/**
+ * The version of the next chant release (#4480, #4473).
+ *
+ * A contract floor added since the last release, the first chant that can
+ * write a field, names the release that ships it. That release has no number
+ * until the maintainer cuts it, so every such floor is this constant, and the
+ * schema and docs text that repeats a floor ("written by chant X and newer",
+ * the "Fields added within version 1" rows) is listed in
+ * scripts/release-floors.ts, which checks it agrees.
+ *
+ * To set the number: `npx tsx scripts/release-floors.ts --set <version>`
+ * rewrites this constant and every listed text. `just release` refuses to
+ * cut a version when any floor names a version that is neither a published
+ * release nor the one being cut.
+ *
+ * After the cut, a floor stays at the value it was released with. Once the
+ * release is published, `just release-floors --freeze <version>` writes the
+ * version into every floor that names this constant as a literal, and moves
+ * this constant to the next patch (#4501). The check fails while a floor
+ * still names this constant after its version shipped.
+ */
+export const NEXT_RELEASE = "0.124.54";

package/src/sensitive-key.ts

@@ -0,0 +1,34 @@
+/**
+ * Which property names carry a secret, by name alone.
+ *
+ * One list for every path that redacts by key: the deep observation's
+ * normalization pass (`./deep-observation.ts`), the thin snapshot path's
+ * warning (`./lifecycle/snapshot.ts`), and the drift record's second
+ * redaction pass (`./drift-record.ts`). This module imports nothing, so the
+ * drift record can use it inside the change-set bundle (#3421).
+ */
+
+/**
+ * Property-name patterns that mark a value secret-bearing. Deliberately narrow
+ * and key-name based: broadening this to e.g. `/key/i` would mask an AWS tag's
+ * `Key` field and every `*KeyName` reference, which is how masking turns into
+ * its own drift signal.
+ *
+ * Shared with the thin snapshot path (`./lifecycle/snapshot.ts`), which warns
+ * on the same names — one list, so the two paths cannot disagree about what
+ * counts as a secret.
+ */
+export const SENSITIVE_KEY_PATTERNS: readonly RegExp[] = [
+  /password/i,
+  /secret/i,
+  /token/i,
+  /private.?key/i,
+  /credential/i,
+  /connection.?string/i,
+];
+
+/** True when a property name looks secret-bearing (see {@link SENSITIVE_KEY_PATTERNS}). */
+export function isSensitiveKey(key: string): boolean {
+  return SENSITIVE_KEY_PATTERNS.some((p) => p.test(key));
+}
+