@intentius/chant 0.124.51 → 0.124.54

package/src/capabilities/templates.ts

@@ -0,0 +1,204 @@
+/**
+ * Investigation templates (#4531): the capability catalog's second kind of
+ * entry, after the capabilities themselves (behold#1022 contract 3).
+ *
+ * A template is a fixed query with the resource filled in, so a click in
+ * behold, choudoufu's `investigate` (choudoufu#2280) and an agent run the
+ * same query. Each says which language it expands to (behold#1022 ruling Q4):
+ * a `chant search` path pattern where one can express the question, Cypher
+ * otherwise. A path template needs nothing beyond chant search, so it keeps
+ * working where behold's optional LadybugDB peer is missing; a Cypher one
+ * needs behold's graph pane.
+ *
+ * The catalog lives here, beside the capability rules (ruling Q5), and is
+ * data: `templates.json` beside this module, shipped as
+ * `@intentius/chant/capabilities/templates.json` and carried as `templates`
+ * on the capabilities document (`chant search --capabilities --json`).
+ * behold and choudoufu read it as data. The initial set is the one behold#1027
+ * stubbed in behold's src/graph-db/templates.ts.
+ *
+ * Filling in: a path template's `{{<input>}}` is replaced by the input's
+ * value, the resource's id for `{{node}}`. A Cypher template takes its inputs
+ * as query parameters, never spliced into the text: the resource's key is
+ * `$key` and every other input is `$<name>`.
+ */
+import { NEXT_RELEASE } from "../release-floors";
+import data from "./templates.json" with { type: "json" };
+
+/** The first chant whose capabilities document carries `templates` (#4531). */
+export const CAPABILITY_TEMPLATES_FLOOR = NEXT_RELEASE;
+
+/** The version of templates.json's shape. */
+export const TEMPLATES_DATA_VERSION = 1;
+
+export type TemplateQueryKind = "path" | "cypher";
+
+/** What answering reads: the declared source, a live read, recorded snapshots, or only the session's loaded graph. */
+export type TemplateReads = "source" | "live" | "snapshots" | "session";
+
+/**
+ * resource: the node the template is about, given as a name, an IR id, a
+ * block address or a cloud ID, and resolved to one node before expanding.
+ * scope: an environment or estate the query is read in. term: one search
+ * term, such as a kind or a capability call.
+ */
+export type TemplateInputKind = "resource" | "scope" | "term";
+
+export interface TemplateInput {
+  name: string;
+  kind: TemplateInputKind;
+  description: string;
+}
+
+export interface TemplateEntry {
+  id: string;
+  title: string;
+  /** The question it answers, in people's words. */
+  question: string;
+  /** The sources whose nodes it applies to (behold's source kinds); absent means every source. */
+  sources?: string[];
+  inputs: TemplateInput[];
+  reads: TemplateReads;
+  query: { kind: TemplateQueryKind; text: string };
+  /** What it does not answer, said where it is offered. */
+  note?: string;
+}
+
+/** A templates file that does not hold to the entry kind, naming the template. */
+export class TemplateCatalogError extends Error {}
+
+const ID = /^[a-z][a-z0-9-]*$/;
+const INPUT_NAME = /^[a-z][A-Za-z0-9_]*$/;
+const KINDS: readonly TemplateQueryKind[] = ["path", "cypher"];
+const READS: readonly TemplateReads[] = ["source", "live", "snapshots", "session"];
+const INPUT_KINDS: readonly TemplateInputKind[] = ["resource", "scope", "term"];
+const PLACEHOLDER = /\{\{([^{}]*)\}\}/g;
+const PARAM = /\$([A-Za-z_][A-Za-z0-9_]*)/g;
+
+const str = (v: unknown): v is string => typeof v === "string" && v.trim() !== "";
+
+/**
+ * Read a templates file, checking each entry against the entry kind: a
+ * unique id, exactly one resource input first, a query of a known kind
+ * whose placeholders (path) or parameters (Cypher) are its inputs, and every
+ * input used.
+ */
+export function parseTemplates(raw: unknown): TemplateEntry[] {
+  const doc = raw as { version?: unknown; templates?: unknown };
+  if (!doc || typeof doc !== "object") throw new TemplateCatalogError("a templates file is an object");
+  if (doc.version !== TEMPLATES_DATA_VERSION) throw new TemplateCatalogError(`templates file version ${String(doc.version)} is not ${TEMPLATES_DATA_VERSION}`);
+  if (!Array.isArray(doc.templates)) throw new TemplateCatalogError("templates is a list");
+  const seen = new Set<string>();
+  return doc.templates.map((t, i) => {
+    const e = t as Partial<TemplateEntry>;
+    const where = str(e?.id) ? `template ${e.id}` : `template ${i}`;
+    const fail = (m: string): never => {
+      throw new TemplateCatalogError(`${where}: ${m}`);
+    };
+    if (!e || typeof e !== "object") fail("is not an object");
+    if (!str(e.id) || !ID.test(e.id)) fail("needs an id of lowercase letters, digits and -");
+    if (seen.has(e.id!)) fail("is defined twice");
+    seen.add(e.id!);
+    if (!str(e.title)) fail("needs a title");
+    if (!str(e.question)) fail("needs the question it answers");
+    if (!READS.includes(e.reads as TemplateReads)) fail(`reads is one of ${READS.join(", ")}`);
+    if (e.sources !== undefined && (!Array.isArray(e.sources) || !e.sources.every(str))) fail("sources is a list of source kinds");
+    if (e.note !== undefined && !str(e.note)) fail("a note is text");
+    if (!Array.isArray(e.inputs)) fail("needs its inputs");
+    const names = new Set<string>();
+    for (const input of e.inputs!) {
+      if (!input || !str(input.name) || !INPUT_NAME.test(input.name)) fail("an input needs a name");
+      if (names.has(input.name)) fail(`input ${input.name} is listed twice`);
+      names.add(input.name);
+      if (!INPUT_KINDS.includes(input.kind)) fail(`input ${input.name}'s kind is one of ${INPUT_KINDS.join(", ")}`);
+      if (!str(input.description)) fail(`input ${input.name} needs a description`);
+    }
+    const resources = e.inputs!.filter((x) => x.kind === "resource");
+    if (resources.length !== 1 || e.inputs![0] !== resources[0]) fail("takes one resource input, first");
+    const q = e.query;
+    if (!q || !KINDS.includes(q.kind) || !str(q.text)) fail(`query is { kind: ${KINDS.join(" | ")}, text }`);
+    const resource = resources[0].name;
+    if (q!.kind === "path") {
+      if (/\$[A-Za-z_]/.test(q!.text)) fail("a path pattern takes {{input}} placeholders, not $parameters");
+      const used = new Set([...q!.text.matchAll(PLACEHOLDER)].map((m) => m[1]));
+      for (const u of used) if (!names.has(u)) fail(`{{${u}}} names no input`);
+      // A scope is where the query is read, not part of its text.
+      for (const input of e.inputs!) if (input.kind !== "scope" && !used.has(input.name)) fail(`the path pattern never uses ${input.name}`);
+    } else {
+      if (/\{\{/.test(q!.text)) fail("a Cypher query takes $parameters, never spliced {{input}} text");
+      if (!/^\s*(MATCH|OPTIONAL MATCH|WITH|CALL|UNWIND)\b/i.test(q!.text)) fail("a Cypher query starts with a reading clause");
+      if (/\b(CREATE|MERGE|DELETE|DETACH|SET|REMOVE|DROP)\b/i.test(q!.text)) fail("a Cypher query only reads");
+      if (!balanced(q!.text)) fail("its brackets do not balance");
+      const params = new Set([...q!.text.matchAll(PARAM)].map((m) => m[1]));
+      if (!params.has("key")) fail("a Cypher query binds the resource as $key");
+      for (const p of params) if (p !== "key" && !names.has(p)) fail(`$${p} names no input`);
+      for (const input of e.inputs!) if (input.name !== resource && input.kind !== "scope" && !params.has(input.name)) fail(`the query never uses $${input.name}`);
+    }
+    return e as TemplateEntry;
+  });
+}
+
+/** Whether (), [] and {} nest, outside quoted strings. */
+function balanced(text: string): boolean {
+  const open: string[] = [];
+  const pair: Record<string, string> = { ")": "(", "]": "[", "}": "{" };
+  let quote: string | undefined;
+  for (const c of text) {
+    if (quote) {
+      if (c === quote) quote = undefined;
+      continue;
+    }
+    if (c === "'" || c === '"') quote = c;
+    else if (c === "(" || c === "[" || c === "{") open.push(c);
+    else if (c in pair && open.pop() !== pair[c]) return false;
+  }
+  return open.length === 0 && !quote;
+}
+
+let cache: TemplateEntry[] | undefined;
+
+/** The templates chant ships, checked. */
+export function investigationTemplates(): TemplateEntry[] {
+  cache ??= parseTemplates(data);
+  return cache;
+}
+
+/** A value spliced into a path pattern is one search term: letters, digits and `_ : . - / * ( ) , [ ]` only. */
+const TERM_VALUE = /^[A-Za-z0-9_:.\-/*(),[\]]+$/;
+
+export interface ExpandedTemplate {
+  template: string;
+  kind: TemplateQueryKind;
+  reads: TemplateReads;
+  /** path: the chant search query. cypher: the statement, unchanged. */
+  text: string;
+  /** cypher: the parameters, the resource as `key`. */
+  params?: Record<string, string>;
+  /** The scope inputs given, which say where the query is read. */
+  scope?: Record<string, string>;
+}
+
+/**
+ * Fill one template. `inputs` holds every input by name, the resource input
+ * as the resolved node's id (path) or key (Cypher). A value that would make
+ * a second search term is refused.
+ */
+export function expandTemplate(t: TemplateEntry, inputs: Record<string, string>): ExpandedTemplate {
+  for (const i of t.inputs) if (!inputs[i.name]) throw new TemplateCatalogError(`${t.id} needs ${i.name}: ${i.description}`);
+  for (const k of Object.keys(inputs)) if (!t.inputs.some((i) => i.name === k)) throw new TemplateCatalogError(`${t.id} takes no input ${k}`);
+  const scopes = t.inputs.filter((i) => i.kind === "scope");
+  const scope = scopes.length ? Object.fromEntries(scopes.map((i) => [i.name, inputs[i.name]!])) : undefined;
+  const head = { template: t.id, kind: t.query.kind, reads: t.reads, ...(scope ? { scope } : {}) };
+  if (t.query.kind === "cypher") {
+    const resource = t.inputs[0].name;
+    const params: Record<string, string> = { key: inputs[resource]! };
+    for (const i of t.inputs) if (i.name !== resource && i.kind !== "scope") params[i.name] = inputs[i.name]!;
+    return { ...head, text: t.query.text, params };
+  }
+  const text = t.query.text.replace(PLACEHOLDER, (_, name: string) => {
+    const v = inputs[name]!;
+    if (!TERM_VALUE.test(v)) throw new TemplateCatalogError(`${t.id}: ${name} ${JSON.stringify(v)} is not one search term`);
+    return v;
+  });
+  return { ...head, text };
+}

package/src/change-set-bundle.test.ts

@@ -7,6 +7,12 @@
  * lexicon's `change-set` subpath must not reach `typescript`, esbuild, zod or
  * chant's fold, lint and codegen modules. This bundles the three entry points
  * the way terragucci would and reads esbuild's own list of what went in.
+ *
+ * The drift record (#4451) ships under the same rule: `@intentius/chant/
+ * drift-record` and the terraform lexicon's `drift-record` subpath bundle to
+ * the plan hashing code, the observation contract, the change-set graph's
+ * node rule, the instance rollup, the sensitive-key list and the plan projection, and nothing
+ * heavier.
  */
 
 import { join } from "node:path";
@@ -50,8 +56,85 @@ describe("the change-set bundle", () => {
       "packages/core/src/intrinsic.ts",
       "packages/core/src/lifecycle/plan-digest.ts",
       "packages/core/src/plan-summary.ts",
+      // The next-release floor constant (#4480): no imports.
+      "packages/core/src/release-floors.ts",
     ]);
     const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
     expect(bytes).toBeLessThan(BUDGET_BYTES);
   });
+
+  test("the drift-record bundle holds the record, its adapters and the digest, and nothing heavier", async () => {
+    const result = await build({
+      entryPoints: [
+        join(REPO, "packages", "core", "src", "drift-record.ts"),
+        join(REPO, "lexicons", "terraform", "src", "drift-record.ts"),
+      ],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?(packages|lexicons)\//, "$1/")).sort()).toEqual([
+      "lexicons/terraform/src/drift-record.ts",
+      "lexicons/terraform/src/live-plan-reasons.ts",
+      "lexicons/terraform/src/plan-observation.ts",
+      "packages/core/src/change-set-graph.ts",
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/drift-record.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/instance-nodes.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/observation.ts",
+      "packages/core/src/pulumi-urn.ts",
+      "packages/core/src/sensitive-key.ts",
+    ]);
+    // About 66 KB today: each entry point carries its own copy of the shared modules.
+    const bytes = result.outputFiles.reduce((n, f) => n + f.contents.byteLength, 0);
+    expect(bytes).toBeLessThan(96 * 1024);
+  });
+
+  test("the pulumi lexicon's change-set and drift-record adapters (#4453) bundle the same way", async () => {
+    const result = await build({
+      entryPoints: [
+        join(REPO, "lexicons", "pulumi", "src", "change-set.ts"),
+        join(REPO, "lexicons", "pulumi", "src", "drift-record.ts"),
+      ],
+      bundle: true,
+      platform: "node",
+      format: "esm",
+      write: false,
+      metafile: true,
+      outdir: "out",
+      logLevel: "silent",
+    });
+    const inputs = Object.keys(result.metafile.inputs);
+    for (const pattern of FORBIDDEN) {
+      expect(inputs.filter((i) => pattern.test(i)), String(pattern)).toEqual([]);
+    }
+    expect(inputs.map((i) => i.replace(/^.*?(packages|lexicons)\//, "$1/")).sort()).toEqual([
+      "lexicons/pulumi/src/change-set.ts",
+      "lexicons/pulumi/src/drift-record.ts",
+      "lexicons/pulumi/src/values.ts",
+      "packages/core/src/change-set-graph.ts",
+      "packages/core/src/content-digest.ts",
+      "packages/core/src/declarable.ts",
+      "packages/core/src/drift-record.ts",
+      "packages/core/src/effect-receipt.ts",
+      "packages/core/src/instance-nodes.ts",
+      "packages/core/src/intrinsic.ts",
+      "packages/core/src/lifecycle/plan-digest.ts",
+      "packages/core/src/observation.ts",
+      "packages/core/src/pulumi-urn.ts",
+      "packages/core/src/sensitive-key.ts",
+    ]);
+  });
 });

package/src/change-set-graph.ts

@@ -18,11 +18,25 @@
  * a delete of a block the source no longer declares, or a warden or sql
  * change outside the graph.
  *
- * Like `./change-set.ts`, this imports nothing at run time, so it bundles
- * into one file with the change-set code.
+ * An instance of a `count` or `for_each` block gets its instance node
+ * (#4454): the block node's id followed by the instance key as the planner
+ * prints it, `<root>/module.app/terraform_data.instance[0]`, with
+ * `instanceOf` naming the block node. That holds whether or not the graph
+ * lists the instance node, since a graph read of the source lists only the
+ * instances it can count (`./instance-nodes.ts`). Under an expanded module
+ * call the module key sits on the call's segment (#4486):
+ * `module.app[0].aws_eip.pool[1]` is `<root>/module.app[0]/aws_eip.pool[1]`.
+ * {@link graphNodeFor} is the same rule for a single address, which a drift
+ * row uses.
+ *
+ * Like `./change-set.ts`, this imports nothing at run time but
+ * `./instance-nodes.ts` and `./pulumi-urn.ts`, which import nothing either,
+ * so it bundles into one file with the change-set code.
  */
 
 import type { ChangeSetDocument, ChangeSetEntry } from "./change-set";
+import { terraformInstancePath } from "./instance-nodes";
+import { pulumiNodeCandidates } from "./pulumi-urn";
 
 /** The graph a document is mapped onto: the node ids of one member's own IR. */
 export interface ChangeSetGraphNodes {
@@ -104,9 +118,14 @@ export function terraformBlockKey(address: string): string | undefined {
  * - `terraform`, `tofu`, `choudoufu`: `<root>/<block key>`, the root being
  *   the change-set member (`terraformBlockKey`), then the address.
  * - `warden`, `sql`: the address.
+ * - `pulumi`: the address is a URN, and the id is `<member>/<key>` by the
+ *   one URN rule (`pulumiNodeCandidates`, `./pulumi-urn.ts`, #4456); none
+ *   for a provider or the root stack.
  */
 export function changeSetNodeCandidates(entry: Pick<ChangeSetEntry, "member" | "planner" | "address">): string[] {
   switch (entry.planner) {
+    case "pulumi":
+      return pulumiNodeCandidates(entry);
     case "terraform":
     case "tofu":
     case "choudoufu": {
@@ -118,24 +137,76 @@ export function changeSetNodeCandidates(entry: Pick<ChangeSetEntry, "member" | "
   }
 }
 
+/** Where one address sits on a graph: its node, and the block node when that node is an instance's. */
+export interface GraphNodePlacement {
+  /** The node id, with the member in front inside a workspace, or null when the graph holds none for the address. */
+  node: string | null;
+  /** The block node's id, set when `node` is an instance node (#4454). */
+  instanceOf?: string;
+  /** The source file of the node, or of its block node for an instance, from the graph's `sources`. */
+  source?: string;
+}
+
+/**
+ * The node an address of a member's planner is on, in `ids` (one member's
+ * node ids, without the member) with `prefix` in front: the first candidate
+ * ({@link changeSetNodeCandidates}) the graph holds, and for an instance of a
+ * terraform-family block that the graph holds, the instance node (#4454).
+ */
+function placeOn(
+  entry: Pick<ChangeSetEntry, "member" | "planner" | "address">,
+  ids: ReadonlySet<string>,
+  prefix: string,
+  sources: ReadonlyMap<string, string> | undefined,
+): GraphNodePlacement {
+  const id = changeSetNodeCandidates(entry).find((c) => ids.has(c));
+  if (id === undefined) return { node: null };
+
+  const path =
+    (entry.planner === "terraform" || entry.planner === "tofu" || entry.planner === "choudoufu") && id !== entry.address
+      ? terraformInstancePath(entry.address)
+      : undefined;
+  // The block node the graph holds is `<root>/<block>`; its instance is
+  // `<root>/<instance>`, the module key on its call segment (#4486).
+  const root = path !== undefined && id.endsWith(`/${path.block}`) ? id.slice(0, id.length - path.block.length) : undefined;
+  if (path === undefined || root === undefined) {
+    const source = sources?.get(id);
+    return { node: `${prefix}${id}`, ...(source !== undefined ? { source } : {}) };
+  }
+  const instance = `${root}${path.instance}`;
+  const source = sources?.get(instance) ?? sources?.get(id);
+  return { node: `${prefix}${instance}`, instanceOf: `${prefix}${id}`, ...(source !== undefined ? { source } : {}) };
+}
+
+/**
+ * The node one engine address is on in `graph`, by the change set's mapping
+ * rules: what a drift row's `node` and `instanceOf` are (#4454), so a drift
+ * row and a change-set entry for the same instance name the same node. A null
+ * `graph` places nothing.
+ */
+export function graphNodeFor(
+  entry: Pick<ChangeSetEntry, "member" | "planner" | "address">,
+  graph: ChangeSetGraphNodes | null,
+): GraphNodePlacement {
+  if (graph === null) return { node: null };
+  return placeOn(entry, new Set(graph.ids), graph.member ? `${graph.member}/` : "", graph.sources);
+}
+
 /**
  * The document with each entry's `node` set from `graph`, and `graph`
  * recording which graph it was. A null `graph` (none could be read) gives
- * every entry `node: null`. The digest is unchanged: `node` is not hashed.
+ * every entry `node: null`. The digest is unchanged: `node`, `instanceOf` and
+ * `source` are not hashed.
  */
 export function mapChangeSetToGraph(doc: ChangeSetDocument, graph: ChangeSetGraphNodes | null): ChangeSetDocument {
   if (graph === null) {
-    return { ...doc, entries: doc.entries.map((e) => ({ ...e, node: null })), graph: null };
+    return { ...doc, entries: doc.entries.map(({ instanceOf: _i, ...e }) => ({ ...e, node: null })), graph: null };
   }
   const ids = new Set(graph.ids);
   const prefix = graph.member ? `${graph.member}/` : "";
   return {
     ...doc,
-    entries: doc.entries.map((e) => {
-      const id = changeSetNodeCandidates(e).find((c) => ids.has(c));
-      const source = id === undefined ? undefined : graph.sources?.get(id);
-      return { ...e, node: id === undefined ? null : `${prefix}${id}`, ...(source !== undefined ? { source } : {}) };
-    }),
+    entries: doc.entries.map(({ instanceOf: _i, ...e }) => ({ ...e, ...placeOn(e, ids, prefix, graph.sources) })),
     graph: { member: graph.member, at: graph.at },
   };
 }

package/src/change-set.test.ts

@@ -28,6 +28,7 @@ import {
   changeSetDigest,
   changeSetDocumentDigest,
   composeChangeSet,
+  isEmptyChangeSet,
   lifecyclePlanPart,
   readChangeSetPartFile,
   reconcilePlanPart,
@@ -291,3 +292,26 @@ describe("readChangeSetPartFile (#3767)", () => {
     expect(failed.member).toMatchObject({ status: "failed", error: "out of order", planDigest: null });
   });
 });
+
+describe("a grouped member (ws-107, #4440)", () => {
+  const digest = computePlanDigest("capability-group", { kind: "k", members: [], composition: "c" });
+  const part = (member: string, group?: { digest: string; reads: string[] }): ChangeSetPart => ({
+    member: { member, lexicon: "chant", planner: "chant", status: "planned", planDigest: computePlanDigest("p", member), holes: [], ...(group ? { group } : {}) },
+    entries: [],
+  });
+
+  test("a member without a group hashes as before; with one, the group is in the digest and the schema", () => {
+    const plain = composeChangeSet([part("a"), part("b")]);
+    const grouped = composeChangeSet([part("a", { digest, reads: [] }), part("b", { digest, reads: ["a.id"] })]);
+    expect(plain.digest).toBe(changeSetDocumentDigest({ members: plain.members, entries: [] }));
+    expect(grouped.digest).not.toBe(plain.digest);
+    expect(composeChangeSet([part("a", { digest, reads: [] }), part("b", { digest, reads: [] })]).digest).not.toBe(grouped.digest);
+    expect(verifyChangeSetDigest(grouped)).toBe(true);
+    expectValid(grouped);
+  });
+
+  test("a change set whose member reads a value its group computes is never empty (ruling 4)", () => {
+    expect(isEmptyChangeSet(composeChangeSet([part("a", { digest, reads: [] }), part("b", { digest, reads: [] })]))).toBe(true);
+    expect(isEmptyChangeSet(composeChangeSet([part("a", { digest, reads: [] }), part("b", { digest, reads: ["a.id"] })]))).toBe(false);
+  });
+});

package/src/change-set.ts

@@ -11,8 +11,8 @@
  * Each planner reaches it through an adapter that returns a
  * {@link ChangeSetPart}: one member and its entries. The lifecycle and
  * reconcile adapters are here; the terraform-family ones live in the
- * terraform lexicon's `change-set` subpath and the SQL ones in the sql
- * lexicon's. A part another process wrote to a file reads back through
+ * terraform lexicon's `change-set` subpath, the SQL ones in the sql
+ * lexicon's and the Pulumi one in the pulumi lexicon's. A part another process wrote to a file reads back through
  * {@link readChangeSetPartFile}. {@link composeChangeSet} joins
  * the parts.
  *
@@ -45,6 +45,7 @@
 import { computePlanDigest } from "./lifecycle/plan-digest";
 import type { ChangeSet as LifecycleChangeSet, ChangeSetEntry as LifecycleEntry } from "./lifecycle/change-set";
 import type { ChangeSet as ReconcileChangeSet } from "./reconcile";
+import { NEXT_RELEASE } from "./release-floors";
 
 /** The schema a change-set document names in `$schema`. */
 export const CHANGE_SET_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/change-set/v1/change-set.schema.json";
@@ -52,6 +53,12 @@ export const CHANGE_SET_SCHEMA_ID = "https://intentius.io/chant/schemas/workspac
 /** The read-contract version the document follows. */
 export const CHANGE_SET_CONTRACT = 1;
 
+/** The first chant whose change set can carry a member's `group` (ws-107, #4440). */
+export const CHANGE_SET_GROUP_FLOOR = NEXT_RELEASE;
+
+/** The first chant whose change set can carry a member's `placeholders` (#4463). */
+export const CHANGE_SET_PLACEHOLDERS_FLOOR = NEXT_RELEASE;
+
 /** What a planner proposes for one resource. `no-op`, `read` and `forget` appear only when the planner reports them. */
 export type ChangeSetAction = "create" | "update" | "replace" | "delete" | "read" | "no-op" | "forget";
 
@@ -61,16 +68,17 @@ export const CHANGE_SET_ACTIONS: readonly ChangeSetAction[] = ["create", "update
 /** How much applying one change hurts, in the vocabulary of `./lifecycle/disruption.ts`. */
 export type ChangeSetDisruption = "in-place" | "rolling" | "replace" | "destroy" | "unknown";
 
-/** Which tool produced a member's plan. */
 /**
  * Which tool produced a member's plan. `sql` is a SQL schema change: a
  * versioned plan (a product's migrations) or one of the sql lexicon's
  * migration Ops' plans, through `@intentius/chant-lexicon-sql/change-set`.
+ * `pulumi` is a `pulumi preview --json` of a Pulumi member, through
+ * `@intentius/chant-lexicon-pulumi/change-set` (#4453); its addresses are URNs.
  */
-export type ChangeSetPlanner = "terraform" | "tofu" | "choudoufu" | "chant" | "warden" | "sql";
+export type ChangeSetPlanner = "terraform" | "tofu" | "choudoufu" | "chant" | "warden" | "sql" | "pulumi";
 
 /** Every planner, in the order the schema lists them. */
-export const CHANGE_SET_PLANNERS: readonly ChangeSetPlanner[] = ["terraform", "tofu", "choudoufu", "chant", "warden", "sql"];
+export const CHANGE_SET_PLANNERS: readonly ChangeSetPlanner[] = ["terraform", "tofu", "choudoufu", "chant", "warden", "sql", "pulumi"];
 
 /** One attribute a change writes, at top-level granularity. */
 export interface ChangeSetAttribute {
@@ -109,6 +117,18 @@ export interface ChangeSetEntry {
   importing?: true;
   /** Set on update, replace and delete. `unknown` means nobody could say. */
   disruption?: ChangeSetDisruption;
+  /**
+   * The planner could not enumerate what this entry stands for (#4453). A
+   * Pulumi program can register resources inside an `apply()`, which does not
+   * run at preview while its input is unknown, so the preview never lists
+   * them. The pulumi adapter keeps them in the set rather than dropping them:
+   * one entry per component whose children may appear, at
+   * `pulumiMayAppearAddress` of the component, and an entry for each resource
+   * the last export holds under such a component that the preview did not
+   * list or plans to delete. An entry carrying it is never empty
+   * ({@link isEmptyChangeSet}). Part of the digest.
+   */
+  mayAppear?: true;
   region?: string;
   /** The estate, environment or org the change lands in. */
   scope?: string;
@@ -120,8 +140,19 @@ export interface ChangeSetEntry {
    * a delete of a block the source no longer declares. Absent until the
    * document is mapped onto a graph (`./change-set-graph.ts`), and never
    * part of the digest.
+   *
+   * An instance of a `count` or `for_each` block (#4454) gets the instance
+   * node's id, the block node's id followed by the key as the planner prints
+   * it (`<member>/aws_eip.pool[0]`), and {@link instanceOf} names the block
+   * node. See `./instance-nodes.ts`.
    */
   node?: string | null;
+  /**
+   * On an entry whose `node` is an instance node (#4454): the id of the block
+   * node it is an instance of, the rollup, in the same id space as `node`.
+   * Absent on every other entry. Like `node`, never part of the digest.
+   */
+  instanceOf?: string;
   /**
    * The source file that declares the entry's node, from the repository
    * root (#4025): the node's `sourceLoc.file` in the member's graph IR, with
@@ -158,9 +189,36 @@ export interface ChangeSetMember {
    * summary never folds it into a group of real plans.
    */
   provisional?: true;
+  /**
+   * The inputs the member was previewed with stand-in values for (#4463),
+   * sorted: a Terraform root whose `vars` read an output not known yet is
+   * planned with a typed placeholder per such variable (`var.<name>`), and
+   * every attribute those drive is marked unknown in its entries. Its plan
+   * digest covers them. The apply plans it again with the real values and
+   * holds that plan to the preview's shape. Added within contract 1 by chant
+   * {@link CHANGE_SET_PLACEHOLDERS_FLOOR}.
+   */
+  placeholders?: string[];
   /** The planner's own digest of the same plan, when it prints one (choudoufu's per-root digest). */
   nativeDigest?: string;
   holes: ChangeSetHole[];
+  /**
+   * Set on a member a capability planned with others as one group (ws-107,
+   * #4440). Part of the document's digest when present. Added within
+   * contract 1 by chant {@link CHANGE_SET_GROUP_FLOOR}.
+   */
+  group?: ChangeSetMemberGroup;
+}
+
+/** A grouped member's group (ws-107): the group digest folded into its `planDigest`, and what it reads inside the group. */
+export interface ChangeSetMemberGroup {
+  digest: string;
+  /**
+   * The `<component>.<output>` values it reads from another member of its
+   * group that the plan does not know, sorted. The group's apply computes
+   * them. A change set with any is never empty ({@link isEmptyChangeSet}).
+   */
+  reads: string[];
 }
 
 /** A provider-defined side effect an apply runs: a Terraform `action` block's invocation. */
@@ -288,7 +346,8 @@ export function changeSetDigest(members: ReadonlyArray<Pick<ChangeSetMember, "me
  *
  * A release gate's document (#4045) also hashes the `releaseDigest` and
  * `environment` it was planned for. A document without them hashes as it
- * always has, so no earlier digest moves.
+ * always has, so no earlier digest moves. A grouped member's `group`
+ * (ws-107) is hashed with it the same way: only when present.
  */
 export function changeSetDocumentDigest(
   doc: Pick<ChangeSetDocument, "members" | "entries" | "sideEffects" | "releaseDigest" | "environment">,
@@ -296,15 +355,15 @@ export function changeSetDocumentDigest(
   const provisional = new Set(doc.members.filter((m) => m.provisional === true).map((m) => m.member));
   const members = doc.members
     .filter((m) => !provisional.has(m.member))
-    .map((m) => ({ member: m.member, status: m.status, holes: m.holes }))
+    .map((m) => ({ member: m.member, status: m.status, holes: m.holes, ...(m.group ? { group: { digest: m.group.digest, reads: [...m.group.reads].sort() } } : {}) }))
     .sort((a, b) => byString(a.member, b.member));
-  // An entry's graph node (#4022) and its source file (#4025) say where on
-  // the graph the change is, not what the plan does, so they stay outside
-  // the digest: mapping a stored
+  // An entry's graph node (#4022), its block node (#4454) and its source
+  // file (#4025) say where on the graph the change is, not what the plan
+  // does, so they stay outside the digest: mapping a stored
   // document onto a graph never moves the value its gate bound.
   const entries = doc.entries
     .filter((e) => !provisional.has(e.member))
-    .map(({ node: _node, source: _source, ...e }) => e)
+    .map(({ node: _node, instanceOf: _instanceOf, source: _source, ...e }) => e)
     .sort((a, b) => byString(entryKey(a), entryKey(b)));
   const sideEffects = (doc.sideEffects ?? []).filter((s) => !provisional.has(s.member)).sort(bySideEffect);
   const planned =
@@ -413,15 +472,19 @@ export function verifyChangeSetDigest(
 /**
  * Whether a change set changes nothing (ws-104 question 6, #4045): it has at
  * least one member, every member planned, none failed or provisional, no
- * member has a hole, and every entry is a `no-op` or a `read`. A release
- * gate over such a document passes without an approval.
+ * member has a hole, and every entry is a `no-op` or a `read` that no
+ * planner marked `mayAppear`. A release gate over such a document passes
+ * without an approval. A member that reads a value its group computes in its
+ * apply (`group.reads`, ws-107 ruling 4) makes it not empty: what the plan
+ * shows may not be all the apply does.
  */
 export function isEmptyChangeSet(doc: Pick<ChangeSetDocument, "members" | "entries">): boolean {
   if (doc.members.length === 0) return false;
   for (const m of doc.members) {
     if (m.status !== "planned" || m.provisional === true || m.holes.length > 0) return false;
+    if (m.group && m.group.reads.length > 0) return false;
   }
-  return doc.entries.every((e) => e.action === "no-op" || e.action === "read");
+  return doc.entries.every((e) => (e.action === "no-op" || e.action === "read") && e.mayAppear !== true);
 }
 
 // ── chant lifecycle plan ───────────────────────────────────────────────────────