@intentius/chant 0.124.46 → 0.124.49

package/src/terraform/reach.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, test } from "vitest";
+import { join } from "path";
+import { loadHcl2json, parseTerraformDir } from "./parse";
+import { carveIndex, reach } from "./reach";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/**
+ * #2325: transitive reachability over the carve graph. The fixture assertions
+ * run against depth-estate (#2323) as the production parse builds it; the
+ * cycle and cross-stack cases need graphs Terraform would not produce, so they
+ * are hand-built.
+ */
+let parserAvailable = false;
+try {
+  await loadHcl2json();
+  parserAvailable = true;
+} catch {
+  parserAvailable = false;
+}
+
+const ESTATE = join(__dirname, "__fixtures__", "depth-estate");
+const STATE = join(ESTATE, "terraform.tfstate");
+
+const node = (address: string, extra: Partial<TfNode> = {}): TfNode => {
+  const [type, name] = address.split(".");
+  return { address, kind: "resource", type, name, instances: 1, hasDynamic: false, ...extra };
+};
+const edge = (from: string, to: string, extra: Partial<TfEdge> = {}): TfEdge => ({ from, to, attrs: [], via: [], ...extra });
+
+describe("reach against depth-estate", () => {
+  test("the subnet group's radius is the cluster, its instance and the Lambda, plus one output, two deep", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    expect(reach(graph, "aws_db_subnet_group.main")).toEqual({
+      address: "aws_db_subnet_group.main",
+      resources: ["aws_lambda_function.api", "aws_rds_cluster.main", "aws_rds_cluster_instance.one"],
+      outputs: ["output.db_endpoint"],
+      depth: 2,
+      crossStack: [],
+      hidden: [],
+    });
+    const vpc = reach(graph, "aws_vpc.main");
+    expect(vpc.resources).toHaveLength(13);
+    expect(vpc.outputs).toEqual(["output.db_endpoint", "output.lb_dns"]);
+    expect(vpc.depth).toBe(3);
+  });
+
+  test("folds contract first: the bucket's radius is the Lambda alone, not its own versioning block", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    // The uncontracted graph has the versioning block reading the bucket.
+    expect(graph.edges.some((e) => e.from === "aws_s3_bucket_versioning.assets" && e.to === "aws_s3_bucket.assets")).toBe(true);
+    expect(reach(graph, "aws_s3_bucket.assets").resources).toEqual(["aws_lambda_function.api"]);
+    // Asking from the folded child walks from its parent.
+    expect(reach(graph, "aws_s3_bucket_versioning.assets").address).toBe("aws_s3_bucket.assets");
+    expect(carveIndex(graph).membersOf("aws_s3_bucket.assets")).toEqual(["aws_s3_bucket.assets", "aws_s3_bucket_versioning.assets"]);
+  });
+
+  test("outputs are counted apart and end the walk", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    const lb = reach(graph, "aws_lb.public");
+    expect(lb.resources).toEqual(["aws_lb_listener.https"]);
+    expect(lb.outputs).toEqual(["output.lb_dns"]);
+    expect(reach(graph, "aws_lb_listener.https")).toMatchObject({ resources: [], outputs: [], depth: 0 });
+  });
+
+  test("a module and an unresolved count are named as hiding their contents; --state resolves the count", async () => {
+    if (!parserAvailable) return;
+    const bare = await parseTerraformDir(ESTATE);
+    expect(reach(bare, "aws_vpc.main").hidden).toEqual(["aws_subnet.private", "module.platform"]);
+    const withState = await parseTerraformDir(ESTATE, { statePath: STATE });
+    expect(reach(withState, "aws_vpc.main").hidden).toEqual(["module.platform"]);
+  });
+
+  test("direction out walks what a node needs", async () => {
+    if (!parserAvailable) return;
+    const graph = await parseTerraformDir(ESTATE);
+    expect(reach(graph, "aws_rds_cluster_instance.one", { direction: "out" }).resources).toEqual([
+      "aws_db_subnet_group.main",
+      "aws_kms_key.data",
+      "aws_rds_cluster.main",
+      "aws_security_group.db",
+      "aws_subnet.a",
+      "aws_subnet.b",
+      "aws_vpc.main",
+    ]);
+  });
+});
+
+describe("reach on hand-built graphs", () => {
+  test("a depends_on cycle terminates and does not count the start", () => {
+    const graph: TfGraph = {
+      nodes: [node("aws_sqs_queue.a"), node("aws_sqs_queue.b"), node("aws_sqs_queue.c")],
+      edges: [
+        edge("aws_sqs_queue.a", "aws_sqs_queue.b", { via: ["depends_on"] }),
+        edge("aws_sqs_queue.b", "aws_sqs_queue.c", { via: ["depends_on"] }),
+        edge("aws_sqs_queue.c", "aws_sqs_queue.a", { via: ["depends_on"] }),
+      ],
+    };
+    expect(reach(graph, "aws_sqs_queue.a")).toMatchObject({ resources: ["aws_sqs_queue.b", "aws_sqs_queue.c"], depth: 2 });
+  });
+
+  test("what is reachable only through a crossStack edge is listed apart", () => {
+    const graph: TfGraph = {
+      nodes: [node("A/Bucket"), node("A/Fn"), node("B/Fn"), node("B/Alarm")],
+      edges: [
+        edge("A/Fn", "A/Bucket"),
+        edge("B/Fn", "A/Bucket", { crossStack: true }),
+        edge("B/Alarm", "B/Fn"),
+      ],
+    };
+    expect(reach(graph, "A/Bucket")).toMatchObject({ resources: ["A/Fn", "B/Alarm", "B/Fn"], crossStack: ["B/Alarm", "B/Fn"] });
+  });
+
+  test("an address the graph does not hold is an error, not an empty radius", () => {
+    expect(() => reach({ nodes: [], edges: [] }, "aws_vpc.nope")).toThrow(/not a resource or module/);
+  });
+
+  test("under 100 ms at 6 000 nodes, index included", () => {
+    // Layered like the spike's synthetic estates: 60 layers of 100, each node
+    // reading two nodes in the layer below, about 11 800 edges. Node i reads
+    // 2i and 2i+1 below it, so the dependents of one bottom node double per
+    // layer and a walk from it covers almost everything.
+    const layers = 60;
+    const width = 100;
+    const nodes: TfNode[] = [];
+    const edges: TfEdge[] = [];
+    for (let l = 0; l < layers; l++) {
+      for (let i = 0; i < width; i++) {
+        nodes.push(node(`aws_sqs_queue.l${l}_${i}`));
+        if (l > 0) {
+          edges.push(edge(`aws_sqs_queue.l${l}_${i}`, `aws_sqs_queue.l${l - 1}_${(2 * i) % width}`));
+          edges.push(edge(`aws_sqs_queue.l${l}_${i}`, `aws_sqs_queue.l${l - 1}_${(2 * i + 1) % width}`));
+        }
+      }
+    }
+    reach({ nodes, edges }, "aws_sqs_queue.l0_0"); // warm the JIT on a different graph object
+    const graph: TfGraph = { nodes, edges };
+    const started = performance.now();
+    const r = reach(graph, "aws_sqs_queue.l0_0");
+    const took = performance.now() - started;
+    expect(r.resources.length).toBeGreaterThan(5_000);
+    expect(took).toBeLessThan(100);
+  });
+});

package/src/terraform/reach.ts

@@ -0,0 +1,247 @@
+/**
+ * Transitive reachability over the carve graph (#2325).
+ *
+ * `inboundEdges`/`outboundEdges` in `graph.ts` answer one hop with a linear
+ * scan, which is right for the scorer's depth-1 counts and wrong as the step of
+ * a walk: calling it per node per step is O(V²E). This module builds one
+ * index per graph instead, and walks it with the same breadth-first walk
+ * `chant search` uses (`graph-walk.ts`).
+ *
+ * Four rules from the spike (docs/design/carve-dependency-blast-radius-spike.md)
+ * hold for every walk here and for the set functions in `cuts.ts` built on it:
+ *
+ *  - Folds contract first. A folded sub-resource is its parent for the walk, so
+ *    `aws_s3_bucket_versioning.assets` is never a dependent of
+ *    `aws_s3_bucket.assets`, and a node reading the child depends on the
+ *    parent.
+ *  - Outputs are terminal and counted apart. An `output.<name>` pseudo-address
+ *    has no inbound edges, so it never extends a path; it is reported in its
+ *    own list.
+ *  - Modules and unresolved `count`/`for_each` hide how much a node holds. A
+ *    `module.x` node is one node whatever it contains, and `count = 20` is one
+ *    node until `--state` resolves it. They are walked through and named, so a
+ *    caller can say `unknown` instead of a number.
+ *  - Cross-stack hops are told apart. On the CDK path an `Fn::ImportValue` edge
+ *    carries `crossStack: true`; what is reachable only through one is listed
+ *    separately.
+ *
+ * Pure, like the rest of the carve analysis. `src/cdk/graph.ts` emits the same
+ * `TfGraph`, so one implementation covers both sources.
+ */
+
+import { adjacencyOf, walkBreadthFirst, type Adjacency } from "../graph-walk";
+import { computeFolds } from "./folds";
+import type { TfEdge, TfGraph, TfNode } from "./types";
+
+/** An edge with both ends contracted to their fold parents. `edge` is the edge as the graph holds it. */
+export interface ContractedEdge extends TfEdge {
+  edge: TfEdge;
+}
+
+/** The index every walk over one graph shares. Built once per graph; see {@link carveIndex}. */
+export interface CarveIndex {
+  graph: TfGraph;
+  /** Every node by address, folded sub-resources included. */
+  nodes: Map<string, TfNode>;
+  /** The address a walk sees for `address`: its fold parent, or itself. */
+  rep(address: string): string;
+  /** A walked node's own blocks: itself first, then what folds into it, sorted. */
+  membersOf(address: string): string[];
+  /** Contracted edges by both ends. An edge internal to one fold is dropped. */
+  adj: Adjacency<ContractedEdge>;
+  /** The graph has at least one `crossStack` edge (a CDK assembly of several stacks). */
+  crossStack: boolean;
+}
+
+const indexes = new WeakMap<TfGraph, CarveIndex>();
+
+/**
+ * The fold-contracted adjacency index for a graph, built on first use and
+ * cached against the graph object. O(V+E) to build; every walk after that is
+ * O(V+E). A caller that mutates `graph.edges` after the first walk must pass a
+ * new graph object (`applyStateCounts` only touches node instance counts, which
+ * the index reads live).
+ */
+export function carveIndex(graph: TfGraph): CarveIndex {
+  const cached = indexes.get(graph);
+  if (cached) return cached;
+  const nodes = new Map(graph.nodes.map((n) => [n.address, n]));
+  const parentOf = new Map<string, string>();
+  const { childrenOf } = computeFolds(graph);
+  for (const [parent, children] of childrenOf) for (const child of children) parentOf.set(child, parent);
+  const rep = (address: string): string => parentOf.get(address) ?? address;
+  const contracted: ContractedEdge[] = [];
+  for (const e of graph.edges) {
+    const from = rep(e.from);
+    const to = rep(e.to);
+    if (from === to) continue; // a folded child reading its own parent is not an edge of the fold
+    contracted.push({ ...e, from, to, edge: e });
+  }
+  const index: CarveIndex = {
+    graph,
+    nodes,
+    rep,
+    membersOf: (address) => [address, ...[...(childrenOf.get(address) ?? [])].sort()],
+    adj: adjacencyOf(contracted),
+    crossStack: graph.edges.some((e) => e.crossStack),
+  };
+  indexes.set(graph, index);
+  return index;
+}
+
+/** `output.<name>`: a pseudo-address `buildGraph` gives an output block's edges (#1638). */
+export function isOutputAddress(address: string): boolean {
+  return address.startsWith("output.");
+}
+
+/**
+ * Whether a node stands for an amount of infrastructure the graph cannot see:
+ * a Terraform `module` block (one node, whatever it holds; state is not read
+ * inside modules), or a `count`/`for_each` block whose instance count no
+ * `.tfstate` resolved. A CDK L3 construct is also `kind: "module"`, but its
+ * members are listed and its address is a construct path, so it hides nothing.
+ */
+export function hidesContents(node: TfNode): boolean {
+  if (node.kind === "module" && node.address.startsWith("module.")) return true;
+  return node.expansion !== undefined && node.instancesFrom !== "state";
+}
+
+/**
+ * Which way a walk steps: `in` follows who reads a node (its dependents), `out`
+ * what it reads, `both` either (weak connectivity, #3909). An output is
+ * terminal every way: it is reached, never stepped from.
+ */
+export type WalkDirection = "in" | "out" | "both";
+
+/**
+ * Walk from `seeds` (already contracted) and return every node reached with its
+ * shortest depth, seeds excluded. `sameStack` refuses `crossStack` edges.
+ */
+export function walkFrom(
+  index: CarveIndex,
+  seeds: Iterable<string>,
+  direction: WalkDirection,
+  opts: { sameStack?: boolean } = {},
+): Map<string, number> {
+  const start = new Set(seeds);
+  const reached = new Map<string, number>();
+  const stepsAlong = (edges: ContractedEdge[] | undefined, far: "from" | "to"): { far: string; hops: never[] }[] =>
+    (edges ?? []).filter((e) => !(opts.sameStack && e.crossStack)).map((e) => ({ far: e[far], hops: [] }));
+  walkBreadthFirst<never>(start, {
+    steps: (id) => {
+      if (isOutputAddress(id) && !start.has(id)) return [];
+      const steps: { far: string; hops: never[] }[] = [];
+      if (direction !== "out") steps.push(...stepsAlong(index.adj.in.get(id), "from"));
+      if (direction !== "in") steps.push(...stepsAlong(index.adj.out.get(id), "to"));
+      return steps;
+    },
+    arrive: ({ id, depth }) => {
+      if (!start.has(id) && !reached.has(id)) reached.set(id, depth);
+      return false;
+    },
+  });
+  return reached;
+}
+
+/** What a walk from one node reached. Every list is sorted and holds contracted addresses. */
+export interface Reach {
+  /** The node the walk started from: the requested address, or its fold parent. */
+  address: string;
+  /** Resource and module nodes reached, the start excluded. */
+  resources: string[];
+  /** `output.<name>` pseudo-addresses reached; terminal, never in `resources`. */
+  outputs: string[];
+  /** The longest shortest path to anything reached, outputs included; 0 when nothing was. */
+  depth: number;
+  /** Of `resources`, those reached only through a `crossStack` edge. Empty off the CDK path. */
+  crossStack: string[];
+  /** Of `resources`, those that hide how much they hold (see {@link hidesContents}). */
+  hidden: string[];
+}
+
+/**
+ * Everything reachable from `address` (#2325). Direction `in` (the default)
+ * walks dependents: what a change to `address` reaches, its blast radius.
+ * Direction `out` walks dependencies: what `address` needs.
+ *
+ * Throws when `address` is not a node of the graph.
+ */
+export function reach(graph: TfGraph, address: string, opts: { direction?: WalkDirection } = {}): Reach {
+  const index = carveIndex(graph);
+  if (!index.nodes.has(address)) throw new Error(`reach: ${address} is not a resource or module in this graph`);
+  const start = index.rep(address);
+  const direction = opts.direction ?? "in";
+  const reached = walkFrom(index, [start], direction);
+  const sorted = [...reached.keys()].sort(cmp);
+  const resources = sorted.filter((a) => !isOutputAddress(a));
+  let crossStack: string[] = [];
+  if (index.crossStack) {
+    const inStack = walkFrom(index, [start], direction, { sameStack: true });
+    crossStack = resources.filter((a) => !inStack.has(a));
+  }
+  return {
+    address: start,
+    resources,
+    outputs: sorted.filter(isOutputAddress),
+    depth: Math.max(0, ...reached.values()),
+    crossStack,
+    hidden: resources.filter((a) => hidesContents(index.nodes.get(a)!)),
+  };
+}
+
+/** Code-point order, as `buildGraph` sorts: locale-independent. */
+export function cmp(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * How far a change to one node reaches, as `carve advise` reports it (#2326):
+ * its own axis beside the peelability score, never a penalty term. Every score
+ * term is a unit of work (an inbound edge is one data-source patch); a
+ * transitive dependent is not work, nobody patches it, and its count can run
+ * far past what a 0-100 score carries.
+ */
+export interface BlastRadius {
+  /**
+   * Resources and modules that depend on the node, directly or not, weighted by
+   * instance count when `--state` resolved it. `"unknown"` when one of them is
+   * a module or a `count`/`for_each` no state resolved: see `hiddenBy`.
+   */
+  resources: number | "unknown";
+  /** `output` blocks that read the node or one of its dependents. */
+  outputs: number;
+  /** Hops to the farthest dependent, outputs included; 0 when nothing depends on it. */
+  depth: number;
+  /**
+   * Of `resources`, those reachable only through a `crossStack` edge (a CDK
+   * `Fn::ImportValue`), weighted the same way. Present only when the graph has
+   * such an edge.
+   */
+  crossStack?: number | "unknown";
+  /** The dependents that make a count `"unknown"`. Present only when one does. */
+  hiddenBy?: string[];
+}
+
+/** The instances `addresses` stand for, or `"unknown"` when one of them hides its contents. */
+export function weigh(index: CarveIndex, addresses: readonly string[]): number | "unknown" {
+  let total = 0;
+  for (const address of addresses) {
+    const node = index.nodes.get(address)!;
+    if (hidesContents(node)) return "unknown";
+    total += node.instances;
+  }
+  return total;
+}
+
+/** The {@link BlastRadius} of `address`: its {@link reach} through dependents, counted. */
+export function blastRadius(graph: TfGraph, address: string): BlastRadius {
+  const index = carveIndex(graph);
+  const r = reach(graph, address);
+  return {
+    resources: weigh(index, r.resources),
+    outputs: r.outputs.length,
+    depth: r.depth,
+    ...(index.crossStack ? { crossStack: weigh(index, r.crossStack) } : {}),
+    ...(r.hidden.length ? { hiddenBy: r.hidden } : {}),
+  };
+}

package/src/terraform/score.ts

@@ -30,9 +30,11 @@
  * shared verbatim.
  */
 
-import { inboundEdges, outboundEdges } from "./graph";
-import { foldParentOf, resolveTier, type TierInfo } from "./tier-map";
-import type { TfGraph, TfNode } from "./types";
+import { adjacencyOf, type Adjacency } from "../graph-walk";
+import { computeFolds } from "./folds";
+import { blastRadius, type BlastRadius } from "./reach";
+import { resolveTier, type TierInfo } from "./tier-map";
+import type { TfEdge, TfGraph, TfNode } from "./types";
 
 export type PeelabilityBand = "clean leaf" | "carvable w/ edits" | "leave in Terraform";
 
@@ -96,6 +98,12 @@ export interface Peelability {
   notes?: string[];
   /** The source units folded into this node (#1056). */
   members?: CarveUnitMember[];
+  /**
+   * How far a change to this node reaches through its dependents (#2326). Its
+   * own axis: it never feeds `score`, so `100 + sum(breakdown.penalties)`
+   * still reproduces the score.
+   */
+  radius?: BlastRadius;
 }
 
 /**
@@ -125,6 +133,12 @@ export interface ScoreOptions {
    */
   tierOf?: (type: string) => TierInfo | null;
   signalsFor?: (node: TfNode) => ScoreSignals;
+  /**
+   * Compute each node's blast radius (#2326). Default true; a caller that only
+   * wants the score (`boundaryReport`) turns it off rather than walk the graph
+   * once per node for a field it drops.
+   */
+  radius?: boolean;
 }
 
 const clamp = (n: number): number => Math.max(0, Math.min(100, n));
@@ -144,40 +158,18 @@ export function bandFor(score: number): PeelabilityBand {
 /** Module tier: a module maps to a chant composite — reshaping, so tier 2 by default. */
 const MODULE_TIER = 2 as const;
 
-/**
- * Build the set of addresses that fold into a parent present in the estate, plus
- * the reverse lookup (parent → its folded children), so a parent can discount
- * inbound edges coming from its own folded sub-resources.
- */
-function computeFolds(graph: TfGraph): { folded: Set<string>; childrenOf: Map<string, Set<string>> } {
-  const byAddress = new Map(graph.nodes.map((n) => [n.address, n]));
-  const folded = new Set<string>();
-  const childrenOf = new Map<string, Set<string>>();
-  for (const node of graph.nodes) {
-    if (node.kind !== "resource" || !node.type) continue;
-    const parentType = foldParentOf(node.type);
-    if (!parentType) continue;
-    const parentAddress = `${parentType}.${node.name}`;
-    if (!byAddress.has(parentAddress)) continue; // sub-resource without its parent → score it on its own
-    folded.add(node.address);
-    if (!childrenOf.has(parentAddress)) childrenOf.set(parentAddress, new Set());
-    childrenOf.get(parentAddress)!.add(node.address);
-  }
-  return { folded, childrenOf };
-}
-
 function scoreNode(
   node: TfNode,
-  graph: TfGraph,
+  adj: Adjacency<TfEdge>,
   foldedChildren: Set<string>,
   opts: ScoreOptions,
 ): Peelability {
   // Inbound excludes edges from this node's own folded sub-resources, and
   // counts output blocks separately — they cost less to bridge (#1638).
-  const inboundAll = inboundEdges(graph, node.address).filter((e) => !foldedChildren.has(e.from));
+  const inboundAll = (adj.in.get(node.address) ?? []).filter((e) => !foldedChildren.has(e.from));
   const inbound = inboundAll.filter((e) => e.fromKind !== "output").length;
   const outputs = inboundAll.length - inbound;
-  const outbound = outboundEdges(graph, node.address).length;
+  const outbound = (adj.out.get(node.address) ?? []).length;
 
   const signals = opts.signalsFor?.(node) ?? {};
   const extra = { ...(signals.penalties ?? {}) };
@@ -247,11 +239,17 @@ function scoreNode(
 /**
  * Score every carvable node in the estate, ranked most-peelable first. Folded
  * sub-resources are omitted (they carve with their parent, not on their own).
+ * Each carries its blast radius (#2326) beside the score, not in it.
  */
 export function scoreEstate(graph: TfGraph, opts: ScoreOptions = {}): Peelability[] {
   const { folded, childrenOf } = computeFolds(graph);
+  // One edge index for the whole pass: a per-node edge filter is O(E) each, O(V·E) in all (#4391).
+  const adj = adjacencyOf(graph.edges);
   return graph.nodes
     .filter((n) => !folded.has(n.address))
-    .map((n) => scoreNode(n, graph, childrenOf.get(n.address) ?? new Set(), opts))
+    .map((n) => {
+      const scored = scoreNode(n, adj, childrenOf.get(n.address) ?? new Set(), opts);
+      return opts.radius === false ? scored : { ...scored, radius: blastRadius(graph, n.address) };
+    })
     .sort((a, b) => b.score - a.score || (a.address < b.address ? -1 : a.address > b.address ? 1 : 0));
 }

package/src/terraform/state.ts

@@ -81,7 +81,9 @@ export function readStateInstanceCounts(statePath: string): Map<string, number>
 export function applyStateCounts(graph: TfGraph, counts: Map<string, number>): TfGraph {
   for (const node of graph.nodes) {
     const n = counts.get(node.address);
-    if (n !== undefined) node.instances = Math.max(1, n);
+    if (n === undefined) continue;
+    node.instances = Math.max(1, n);
+    node.instancesFrom = "state";
   }
   return graph;
 }

package/src/terraform/types.ts

@@ -28,6 +28,14 @@ export interface TfNode {
   instances: number;
   /** `count`, `for_each`, a `data` source, or an unresolved interpolation is present. */
   hasDynamic: boolean;
+  /**
+   * The block's own expansion meta-argument, when it has one (#2325). Unlike
+   * `hasDynamic`, which a `data` read also sets, this says the node stands for
+   * an unknown number of instances until state resolves it.
+   */
+  expansion?: "count" | "for_each";
+  /** `"state"` once `applyStateCounts` read this node's instance count from a `.tfstate` (#2325). */
+  instancesFrom?: "state";
   /**
    * The resource's physical name, when it is a plain literal in the HCL (e.g.
    * `bucket = "myapp-assets-prod"`). Used to build the live-import selector on

package/src/wave-blocked.ts

@@ -44,7 +44,7 @@
  * later member is blocked by `wave-<k>`.
  */
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 export const WAVE_OUTCOME_VERSION = 1;
 
@@ -239,7 +239,8 @@ function outcomeFiles(dirs: readonly string[]): string[] {
  * The outcome of each member of the waves before `wave`, as their jobs wrote
  * them under `dirs`, and the earliest such wave that holds every later
  * member, if any. For a member more than one job wrote (a re-run, or a split
- * wave's deciding job and the share that applied it), the newest. A file
+ * wave's deciding job and the share that applied it), the newest, and on a
+ * tie the share's rather than the deciding job's `decided`. A file
  * that does not parse, or is of another version, is skipped.
  */
 export function earlierWaveOutcomes(
@@ -260,7 +261,8 @@ export function earlierWaveOutcomes(
     if (typeof members !== "object" || members === null) continue;
     for (const [member, o] of Object.entries(members)) {
       const had = out.get(member);
-      if (had && had.at > f.at) continue;
+      // #4322: at the same time, what a share reported wins over its deciding job's `decided`.
+      if (had && (had.at > f.at || (had.at === f.at && o.status === "decided" && had.status !== "decided"))) continue;
       out.set(member, { ...o, wave: f.wave!, at: f.at });
     }
     const n = newest.get(f.wave!);
@@ -269,3 +271,26 @@ export function earlierWaveOutcomes(
   const holding = [...newest].filter(([, n]) => n.holdsAll).map(([k]) => k).sort((a, b) => a - b);
   return { members: out, ...(holding.length ? { holdsAll: holding[0] } : {}) };
 }
+
+/**
+ * The newest outcome file named `name` under `dirs` (#4322), as
+ * {@link waveOutcomeFileName} names one job's: a split wave's share job
+ * reads its deciding job's, `outcome-wave-<k>.json`, to learn which runs that
+ * job decided and which it blocked. Undefined when there is none, or none
+ * that parses at this version.
+ */
+export function readWaveOutcomeFile(dirs: readonly string[], name: string): WaveOutcomeFile | undefined {
+  let newest: WaveOutcomeFile | undefined;
+  for (const file of outcomeFiles(dirs)) {
+    if (basename(file) !== name) continue;
+    let f: Partial<WaveOutcomeFile>;
+    try {
+      f = JSON.parse(readFileSync(file, "utf-8"));
+    } catch {
+      continue;
+    }
+    if (f?.version !== WAVE_OUTCOME_VERSION || typeof f.at !== "string" || typeof f.members !== "object" || f.members === null) continue;
+    if (!newest || newest.at <= f.at) newest = f as WaveOutcomeFile;
+  }
+  return newest;
+}

package/src/wave-loop-golden.test.ts

@@ -262,9 +262,10 @@ describe("Op waves golden transcripts (#3766)", () => {
       { wave: 1, label: "waits" },
       { wave: 1, label: "approved", gates: memoryGateLedgerPort({ resolutions: [resolution("tf-apply", "wave-1", set)] }) },
       { wave: 1, label: "another digest approved", gates: memoryGateLedgerPort({ resolutions: [resolution("tf-apply", "wave-1", digest("9"))] }) },
-      { wave: 2, decide: true, label: "decide a wide never wave" },
-      { wave: 2, share: 1, label: "share 1" },
-      { wave: 2, share: 2, label: "share 2" },
+      // #4322: wave 1's last job here waits, which would stop wave 2; the wide wave keeps its outcomes apart to show its own jobs.
+      { wave: 2, decide: true, label: "decide a wide never wave", outcomeDir: "wide-outcomes" },
+      { wave: 2, share: 1, label: "share 1", outcomeDir: "wide-outcomes" },
+      { wave: 2, share: 2, label: "share 2", outcomeDir: "wide-outcomes" },
     ]);
   });
 

package/src/workspace/__fixtures__/import/spacelift.json

@@ -0,0 +1,9 @@
+{
+  "account": "acme",
+  "stacks": [
+    { "id": "vpc", "name": "VPC", "space": "root", "projectRoot": "terraform/vpc", "vendor": "terraform", "labels": ["env:prod"] },
+    { "id": "db", "name": "Database", "projectRoot": "terraform/db", "labels": ["env:prod"], "policies": ["p1"], "dependsOn": [{ "stack": "vpc", "references": [{ "outputName": "subnet_ids", "inputName": "TF_VAR_subnets" }] }] },
+    { "id": "cfg", "name": "ansible-config", "vendor": "ansible", "projectRoot": "ansible", "dependsOn": [{ "stack": "db" }, { "stack": "nope" }], "contexts": ["c1"] }
+  ],
+  "policies": [{ "id": "p1", "name": "approval", "type": "APPROVAL" }]
+}

package/src/workspace/__fixtures__/import/tfc.json

@@ -0,0 +1,13 @@
+{
+  "organization": "acme",
+  "projects": [{ "id": "prj-1", "name": "platform" }],
+  "workspaces": [
+    { "id": "ws-net", "name": "network-prod", "project": "prj-1", "workingDirectory": "infra/network", "tags": ["env:prod"], "variables": [{ "key": "region" }, { "key": "token", "sensitive": true }], "vcsRepo": "acme/infra" },
+    { "id": "ws-app", "name": "app-prod", "project": "prj-1", "workingDirectory": "infra/app", "tags": ["env:prod"], "runTriggers": ["ws-net", "ws-gone"] },
+    { "id": "ws-app-dev", "name": "app-dev", "workingDirectory": "infra/app", "tags": ["environment:dev"], "runTriggers": ["network-prod"] }
+  ],
+  "policySets": [
+    { "name": "no-public-s3", "kind": "sentinel", "enforcement": "hard-mandatory", "workspaces": ["ws-app"] },
+    { "name": "tags-required", "global": true }
+  ]
+}

package/src/workspace/behold-kinds.test.ts

@@ -46,6 +46,7 @@ function install(root: string, from: string): string {
   mkdirSync(dir, { recursive: true });
   cpSync(join(from, "package.json"), join(dir, "package.json"));
   cpSync(join(from, "workspace-kinds.json"), join(dir, "workspace-kinds.json"));
+  if (existsSync(join(from, "schemas"))) cpSync(join(from, "schemas"), join(dir, "schemas"), { recursive: true });
   const targets = new Set<string>(["./index.js"]);
   const collect = (entry: unknown): void => {
     if (typeof entry === "string") targets.add(entry.replace("*", "workspace-kinds"));
@@ -153,6 +154,6 @@ describe("behold's member kinds from their packages (#2545)", () => {
     await runWorkspaceLs({ args: parseArgs(["workspace", "ls", root, "--json"]), plugins: [] } as never);
     const doc = JSON.parse(out.join("\n")) as Extract<LsDocument, { members: unknown }>;
     expect(doc.members.map((m) => m.reason?.code ?? null)).toEqual(["unknown-kind", "unknown-kind", "unknown-kind", null]);
-    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, design, other, workspace$/);
+    expect(doc.members[0].reason?.message).toMatch(/known kinds: chant, design, other, repo, workspace$/);
   });
 });