deepline 0.3.258 → 0.3.260

package/dist/bundling-sources/shared_libs/plays/docflow-unreached-reason.ts

@@ -0,0 +1,611 @@
+/**
+ * WHY a docflow node carries no run material.
+ *
+ * "Not reached in the latest run" is a true sentence and a useless one. The
+ * graph and the run's node states already say WHY — the reader just never got
+ * told. This derives that answer generally: walk the executed frontier back
+ * from the node and name the first place the run went somewhere else.
+ *
+ * Nothing here is play-specific and nothing here is invented. Every field is
+ * read off the persisted docflow (nodes / edges / branch labels / subgraphs) or
+ * off the run's own node states. When the graph cannot support an answer the
+ * result says so in its own case rather than guessing a plausible one.
+ */
+
+import type { PlayDocflow, PlayDocflowNode } from './docflow';
+
+/**
+ * The slice of a run's node state the walk reads. Structural, so the run read
+ * (the Run Snapshot's node states) and the canvas (its metrics' statuses) feed
+ * the same walk.
+ */
+export type DocflowReasonNodeState = {
+  nodeId: string;
+  status: string;
+  error?: string | null;
+  nodeIo?: {
+    outputs?: Record<string, { kind: string; value?: unknown }>;
+  } | null;
+};
+
+/** A graph endpoint the reason points at — a real node, nameable and focusable. */
+export type DocflowReasonNode = {
+  id: string;
+  label: string;
+  kind: PlayDocflowNode['kind'];
+};
+
+export type DocflowUnreachedReason =
+  /** The node DID run. Callers must render run material, not this. */
+  | { kind: 'reached' }
+  /** No node in the graph carries run state: nothing has run on this revision. */
+  | { kind: 'no_run' }
+  /**
+   * The selected run's node states have not loaded yet, and nothing loaded so
+   * far says this node ran. No claim is possible — "Not run yet" and every
+   * "Not reached" case are read off the ABSENCE of state, and an unloaded run
+   * has no state to be absent from.
+   */
+  | { kind: 'loading' }
+  /**
+   * The nearest upstream decision that ran took a different arm. The canonical
+   * case, and the only one that can name an arm and a deciding value.
+   */
+  | {
+      kind: 'branch_not_taken';
+      decision: DocflowReasonNode;
+      /** Label of the arm the run DID take (edge label, else target label). */
+      takenArm: string;
+      /** The node that arm leads to. */
+      takenTarget: DocflowReasonNode | null;
+      /** Label of the arm that leads (eventually) to the focused node. */
+      skippedArm: string;
+      /** The decision's own recorded output value, when the run captured one. */
+      decidedBy: { path: string; value: string } | null;
+    }
+  /**
+   * The nearest upstream decision ran, the run carried on past it, and NEITHER
+   * arm carries node state. That is what a per-row decision inside a map looks
+   * like from the graph: the choice was made once per row and recorded on the
+   * row, so no arm node can be "the one that ran". The answer exists — in the
+   * row's own trace — and this case is how the pane points at it instead of
+   * inventing a graph-level story.
+   */
+  | {
+      kind: 'row_grain_branch';
+      decision: DocflowReasonNode;
+      /** The arm this node sits on, when the edge is labelled. */
+      arm: string | null;
+    }
+  /**
+   * The runtime recorded this node as `skipped` and the graph offers no
+   * diverging decision to explain it. The run's own word, restated.
+   */
+  | { kind: 'skipped_by_run' }
+  /**
+   * Something DOWNSTREAM of this node ran, and it is the only way there — so
+   * the run did come through here and simply left no state under this id.
+   *
+   * Not every node is instrumented, and an absent record is not an absent
+   * event. Without this case the walk called `Accounts to score` "Skipped"
+   * while its own dataset sat on screen full of rows, which is the same class
+   * of lie as calling it "Queued".
+   */
+  | { kind: 'not_recorded' }
+  /**
+   * The run reached the frontier, went on past it by some other path, and never
+   * came through here. Not a branch (the frontier is no decision) and not a
+   * stop (the run kept going).
+   */
+  | { kind: 'bypassed'; frontier: DocflowReasonNode }
+  /** An upstream node that ran FAILED, so the run never continued to here. */
+  | {
+      kind: 'upstream_failed';
+      upstream: DocflowReasonNode;
+      error: string | null;
+    }
+  /** The run is still moving; the frontier has not arrived here yet. */
+  | { kind: 'run_in_progress'; frontier: DocflowReasonNode | null }
+  /** The run stopped at an upstream node without failing and without branching. */
+  | { kind: 'run_ended_early'; lastReached: DocflowReasonNode | null }
+  /**
+   * Nothing upstream of this node ran at all. The node is disconnected from the
+   * executed region of the graph — a different revision's shape, a
+   * presentation-only node with no path from the entry, or a run whose states
+   * name none of its ancestors.
+   */
+  | { kind: 'no_executed_upstream' };
+
+/** Run states name a node either bare or namespaced. One spelling, here. */
+function bareNodeId(nodeId: string): string {
+  return nodeId.replace(/^docflow:/, '');
+}
+
+/**
+ * REACHED means the run actually arrived: it started work here.
+ *
+ * `idle` never started. `skipped` is the runtime SAYING it declined this node —
+ * the branch-not-taken signal itself — so counting it as reached would make the
+ * arm the run refused look like the arm it took. Everything else (running,
+ * completed, failed) is the run having been here.
+ */
+export function isDocflowNodeReached(
+  state: Pick<DocflowReasonNodeState, 'status'> | null | undefined,
+): boolean {
+  return state != null && state.status !== 'idle' && state.status !== 'skipped';
+}
+
+/**
+ * Graph endpoints include subgraph ids, because edges connect to them. A
+ * subgraph is "reached" when any member is, and it is the structural
+ * predecessor of each of its members: a loop member is only reachable through
+ * its region.
+ */
+type ReasonGraph = {
+  /** endpoint id -> the endpoints that feed it. */
+  predecessors: Map<string, string[]>;
+  /** endpoint id -> the endpoints it feeds, with the authored branch label. */
+  successors: Map<string, { to: string; label: string | null }[]>;
+  /** Every endpoint the run touched. */
+  reached: Set<string>;
+  nodeById: Map<string, PlayDocflowNode>;
+};
+
+function buildReasonGraph(
+  docflow: PlayDocflow,
+  nodeStates: readonly DocflowReasonNodeState[],
+): ReasonGraph {
+  const predecessors = new Map<string, string[]>();
+  const successors = new Map<string, { to: string; label: string | null }[]>();
+  const push = <T>(map: Map<string, T[]>, key: string, value: T) => {
+    const existing = map.get(key);
+    if (existing) existing.push(value);
+    else map.set(key, [value]);
+  };
+  for (const edge of docflow.edges) {
+    push(predecessors, edge.to, edge.from);
+    push(successors, edge.from, {
+      to: edge.to,
+      label: edge.label?.trim() || null,
+    });
+  }
+  // Containment reads as an edge for this purpose: a region owns its members.
+  for (const subgraph of docflow.subgraphs ?? []) {
+    for (const memberId of subgraph.memberIds) {
+      push(predecessors, memberId, subgraph.id);
+      push(successors, subgraph.id, { to: memberId, label: null });
+    }
+  }
+
+  const reached = new Set(
+    nodeStates
+      .filter((state) => isDocflowNodeReached(state))
+      .map((state) => bareNodeId(state.nodeId)),
+  );
+  // A region inherits its members' reach, so a decision that branches into a
+  // loop is answerable without per-region run state.
+  for (const subgraph of docflow.subgraphs ?? []) {
+    if (subgraph.memberIds.some((memberId) => reached.has(memberId))) {
+      reached.add(subgraph.id);
+    }
+  }
+
+  return {
+    predecessors,
+    successors,
+    reached,
+    nodeById: new Map(docflow.nodes.map((node) => [node.id, node])),
+  };
+}
+
+function stateFor(
+  nodeStates: readonly DocflowReasonNodeState[],
+  endpointId: string,
+): DocflowReasonNodeState | null {
+  return (
+    nodeStates.find((state) => bareNodeId(state.nodeId) === endpointId) ?? null
+  );
+}
+
+function reasonNode(
+  graph: ReasonGraph,
+  docflow: PlayDocflow,
+  endpointId: string,
+): DocflowReasonNode | null {
+  const node = graph.nodeById.get(endpointId);
+  if (node) return { id: node.id, label: node.label, kind: node.kind };
+  const subgraph = (docflow.subgraphs ?? []).find(
+    (candidate) => candidate.id === endpointId,
+  );
+  // A region is not a docflow node, but it is nameable and it is a real place
+  // in the diagram, so it may still be the answer.
+  return subgraph
+    ? { id: subgraph.id, label: subgraph.label, kind: 'conceptual' }
+    : null;
+}
+
+/**
+ * Did the run get ANYWHERE past this endpoint?
+ *
+ * The one guard that keeps the pane from reporting a stop that never happened.
+ * A frontier with reached descendants means the run went on — by another arm,
+ * by a row-grain path, by a join — and the honest sentence is "it went
+ * elsewhere", never "it ended here".
+ */
+function hasReachedDescendant(graph: ReasonGraph, endpointId: string): boolean {
+  const visited = new Set<string>([endpointId]);
+  const queue: string[] = [endpointId];
+  for (let head = 0; head < queue.length; head += 1) {
+    for (const edge of graph.successors.get(queue[head]!) ?? []) {
+      if (visited.has(edge.to)) continue;
+      if (graph.reached.has(edge.to)) return true;
+      visited.add(edge.to);
+      queue.push(edge.to);
+    }
+  }
+  return false;
+}
+
+/**
+ * The decision's own recorded value, when the run captured one. This is the
+ * SAME material the node inspector shows for a decision, read from the node's
+ * captured outputs — never re-derived and never inferred from the arm.
+ */
+function decidedByValue(
+  state: DocflowReasonNodeState | null,
+): { path: string; value: string } | null {
+  const outputs = state?.nodeIo?.outputs;
+  if (!outputs) return null;
+  for (const [path, preview] of Object.entries(outputs)) {
+    if (preview.kind === 'scalar') {
+      return { path, value: String(preview.value) };
+    }
+  }
+  return null;
+}
+
+/**
+ * Why the run carries nothing for `nodeId`.
+ *
+ * THE RULE, in one paragraph. Breadth-first from the node, backwards over
+ * edges (and region containment), find the nearest endpoints that DID run —
+ * the executed frontier behind this node. That frontier is where the run and
+ * this node parted ways. At that boundary, in this precedence:
+ *
+ *   1. a decision that ran and whose taken arm is not the one leading here →
+ *      `branch_not_taken` (name the decision, both arms, the deciding value);
+ *   2. a decision that ran with NO arm carrying node state, while the run went
+ *      on past it → `row_grain_branch` (the choice was made per row, not once);
+ *   3. the run's own `skipped` mark on this node → `skipped_by_run`;
+ *   4. a successor of THIS node that ran, with no other way in → `not_recorded`
+ *      (the run came through and left no state under this id);
+ *      — or a loop region with no member recorded, fed by a completed step;
+ *   5. a node that ran and FAILED → `upstream_failed`;
+ *   6. a node still running → `run_in_progress`;
+ *   7. a frontier the run continued past by another path → `bypassed`;
+ *   8. a frontier with nothing reached after it → `run_ended_early`.
+ *
+ * Precedence is fixed rather than positional because a branch is an ANSWER
+ * ("the run chose otherwise") while a stop is an absence of one; when both sit
+ * on the same frontier the answer wins. When the walk finds no executed
+ * endpoint at all, that is its own case and is reported as such.
+ *
+ * WHY 2 AND 6 EXIST. Both are guards against the pane claiming a stop that did
+ * not happen. A per-row decision inside a map records state on the decision and
+ * on the dataset after it, and NONE on its arm nodes — verified against a real
+ * `prov-09-tier-decision` run, whose snapshot names `docflow:tier` and
+ * `docflow:track` but neither tier arm. Reading that as "the run stopped at
+ * Priority tier?" is false: the run completed. So a stop is only ever claimed
+ * when nothing downstream of the frontier ran either.
+ */
+export function deriveDocflowUnreachedReason(input: {
+  docflow: PlayDocflow;
+  nodeStates: readonly DocflowReasonNodeState[];
+  nodeId: string;
+  /** The selected run's node states are still loading. See `loading`. */
+  nodeStatesLoading?: boolean;
+}): DocflowUnreachedReason {
+  const { docflow, nodeStates, nodeId } = input;
+  const graph = buildReasonGraph(docflow, nodeStates);
+  if (graph.reached.has(nodeId)) return { kind: 'reached' };
+  // Checked AFTER `reached`: a state the run already reported is a fact even
+  // mid-load, but every case below is inferred from missing state.
+  if (input.nodeStatesLoading) return { kind: 'loading' };
+  if (graph.reached.size === 0) return { kind: 'no_run' };
+
+  // Reverse BFS. `frontier` collects every reached endpoint adjacent to the
+  // unreached region behind this node, in discovery (nearest-first) order.
+  const visited = new Set<string>([nodeId]);
+  const queue: string[] = [nodeId];
+  const boundary: { reachedId: string; skippedId: string }[] = [];
+  for (let head = 0; head < queue.length; head += 1) {
+    const current = queue[head]!;
+    for (const predecessor of graph.predecessors.get(current) ?? []) {
+      if (graph.reached.has(predecessor)) {
+        boundary.push({ reachedId: predecessor, skippedId: current });
+        continue;
+      }
+      if (visited.has(predecessor)) continue;
+      visited.add(predecessor);
+      queue.push(predecessor);
+    }
+  }
+  if (boundary.length === 0) return { kind: 'no_executed_upstream' };
+
+  // 1. The nearest diverging decision.
+  for (const { reachedId, skippedId } of boundary) {
+    const node = graph.nodeById.get(reachedId);
+    if (!node || node.kind !== 'decision') continue;
+    const outgoing = graph.successors.get(reachedId) ?? [];
+    if (outgoing.length < 2) continue;
+    const taken = outgoing.find((edge) => graph.reached.has(edge.to));
+    const skipped = outgoing.find((edge) => edge.to === skippedId);
+    if (!taken || !skipped || taken.to === skippedId) continue;
+    const takenTarget = reasonNode(graph, docflow, taken.to);
+    const skippedTarget = reasonNode(graph, docflow, skipped.to);
+    return {
+      kind: 'branch_not_taken',
+      decision: { id: node.id, label: node.label, kind: node.kind },
+      takenArm: taken.label ?? takenTarget?.label ?? taken.to,
+      takenTarget,
+      skippedArm: skipped.label ?? skippedTarget?.label ?? skipped.to,
+      decidedBy: decidedByValue(stateFor(nodeStates, reachedId)),
+    };
+  }
+
+  // 2. A decision whose arms carry no node state at all, with the run still
+  //    going after it: the choice was made per ROW, and the row is where the
+  //    answer lives. Never "the run stopped here", which would be false.
+  for (const { reachedId, skippedId } of boundary) {
+    const node = graph.nodeById.get(reachedId);
+    if (!node || node.kind !== 'decision') continue;
+    const outgoing = graph.successors.get(reachedId) ?? [];
+    if (outgoing.length < 2) continue;
+    if (outgoing.some((edge) => graph.reached.has(edge.to))) continue;
+    if (!hasReachedDescendant(graph, reachedId)) continue;
+    const skipped = outgoing.find((edge) => edge.to === skippedId);
+    return {
+      kind: 'row_grain_branch',
+      decision: { id: node.id, label: node.label, kind: node.kind },
+      arm:
+        skipped?.label ??
+        (skipped ? reasonNode(graph, docflow, skipped.to)?.label : null) ??
+        null,
+    };
+  }
+
+  // 3. The run's own word for this node, when it left one.
+  if (stateFor(nodeStates, nodeId)?.status === 'skipped') {
+    return { kind: 'skipped_by_run' };
+  }
+
+  // 4. Evidence the run came THROUGH here without recording it: a direct
+  //    successor ran, and no other reached node feeds that successor, so this
+  //    node was the way in. An absent record is not an absent event.
+  for (const edge of graph.successors.get(nodeId) ?? []) {
+    if (!graph.reached.has(edge.to)) continue;
+    const otherWayIn = (graph.predecessors.get(edge.to) ?? []).some(
+      (predecessor) => predecessor !== nodeId && graph.reached.has(predecessor),
+    );
+    if (otherWayIn) continue;
+    return { kind: 'not_recorded' };
+  }
+
+  // 4b. A loop region whose per-row work is not instrumented per member: NO
+  //     member carries state, and the step feeding the region completed. The
+  //     region's work ran inside that step (a dataset's `.withColumn` steps
+  //     run in its map), so the run came through every member and recorded
+  //     none of them. Calling them "Skipped" was the same lie as case 4.
+  for (const subgraph of docflow.subgraphs ?? []) {
+    if (!subgraph.memberIds.includes(nodeId)) continue;
+    if (subgraph.memberIds.some((memberId) => graph.reached.has(memberId))) {
+      continue;
+    }
+    const feeders = graph.predecessors.get(subgraph.id) ?? [];
+    if (
+      feeders.length > 0 &&
+      feeders.every(
+        (feeder) => stateFor(nodeStates, feeder)?.status === 'completed',
+      )
+    ) {
+      return { kind: 'not_recorded' };
+    }
+  }
+
+  // 5. A failure upstream.
+  for (const { reachedId } of boundary) {
+    if (stateFor(nodeStates, reachedId)?.status !== 'failed') continue;
+    const upstream = reasonNode(graph, docflow, reachedId);
+    if (!upstream) continue;
+    return {
+      kind: 'upstream_failed',
+      upstream,
+      error: stateFor(nodeStates, reachedId)?.error?.trim() || null,
+    };
+  }
+
+  // 6. Still moving.
+  for (const { reachedId } of boundary) {
+    if (stateFor(nodeStates, reachedId)?.status !== 'running') continue;
+    return {
+      kind: 'run_in_progress',
+      frontier: reasonNode(graph, docflow, reachedId),
+    };
+  }
+
+  // 7. The run carried on past the frontier by some other path. Not a stop.
+  for (const { reachedId } of boundary) {
+    if (!hasReachedDescendant(graph, reachedId)) continue;
+    const frontier = reasonNode(graph, docflow, reachedId);
+    if (!frontier) continue;
+    return { kind: 'bypassed', frontier };
+  }
+
+  // 8. Nothing ran after the frontier either, so the run really did stop.
+  return {
+    kind: 'run_ended_early',
+    lastReached: reasonNode(graph, docflow, boundary[0]!.reachedId),
+  };
+}
+
+/**
+ * What this node would have produced downstream — the blast radius of the arm
+ * not taken. Forward reachability from the node, keeping only endpoints the
+ * run ALSO never reached, so the list is exactly "what is missing because this
+ * is missing" and never restates something the run already has.
+ */
+export function docflowUnreachedDownstream(input: {
+  docflow: PlayDocflow;
+  nodeStates: readonly DocflowReasonNodeState[];
+  nodeId: string;
+}): DocflowReasonNode[] {
+  const { docflow, nodeStates, nodeId } = input;
+  const graph = buildReasonGraph(docflow, nodeStates);
+  const visited = new Set<string>([nodeId]);
+  const queue: string[] = [nodeId];
+  const out: DocflowReasonNode[] = [];
+  for (let head = 0; head < queue.length; head += 1) {
+    for (const edge of graph.successors.get(queue[head]!) ?? []) {
+      if (visited.has(edge.to)) continue;
+      visited.add(edge.to);
+      queue.push(edge.to);
+      if (graph.reached.has(edge.to)) continue;
+      const node = reasonNode(graph, docflow, edge.to);
+      if (node) out.push(node);
+    }
+  }
+  return out;
+}
+
+/**
+ * The symbols a node declares it writes — what the reader loses when the node
+ * is skipped. Declared, so it is answerable with no run at all.
+ */
+export function docflowDeclaredOutputs(
+  docflow: PlayDocflow,
+  nodeId: string,
+): string[] {
+  return (
+    docflow.bindings.find((binding) => binding.nodeId === nodeId)?.outputs ?? []
+  );
+}
+
+/**
+ * The most recent EARLIER run that reached this node, answered only from run
+ * details already in memory.
+ *
+ * Per-run node states arrive with a run's DETAIL, not with the runs list, so
+ * asking this of every run would be one fetch per run. The pane refuses to pay
+ * that: it reads the runs it already has and returns null otherwise. Callers
+ * must render nothing on null — never a spinner, never a claim.
+ */
+export function findEarlierRunReachingNode<
+  TRun extends {
+    playId: string;
+    createdAt: number;
+    nodeStates?: readonly DocflowReasonNodeState[] | undefined;
+  },
+>(input: {
+  runs: readonly TRun[];
+  nodeId: string;
+  excludeRunId: string | null;
+}): TRun | null {
+  const candidates = input.runs
+    .filter((run) => run.playId !== input.excludeRunId)
+    .filter((run) =>
+      (run.nodeStates ?? []).some(
+        (state) =>
+          bareNodeId(state.nodeId) === input.nodeId &&
+          isDocflowNodeReached(state),
+      ),
+    );
+  if (candidates.length === 0) return null;
+  return candidates.reduce((latest, run) =>
+    run.createdAt > latest.createdAt ? run : latest,
+  );
+}
+
+/**
+ * The nodes the run can NEVER come through — the canvas's own question.
+ *
+ * A card with no run material is one of two very different things, and the
+ * canvas was calling both of them "Queued": a node the run has not got to YET,
+ * and a node the run already decided against. "Queued" on the arm a decision
+ * declined is a lie in the same family as every other one this module exists to
+ * remove — it says "about to run" about work that will never happen.
+ *
+ * So the split is made here, off the same walk the pane uses: a node is still
+ * coming only while the frontier behind it is genuinely moving
+ * (`run_in_progress`), or while no run has started at all. Everything else the
+ * run has already passed by.
+ */
+export function docflowDefinitivelySkippedNodeIds(input: {
+  docflow: PlayDocflow;
+  nodeStates: readonly DocflowReasonNodeState[];
+  /**
+   * The run is still going. Until it ends, only the run's own answers make a
+   * node skipped: a decision that took the other arm, or the run marking the
+   * node skipped. Every inference from what has not happened YET (a frontier
+   * that completed while the next step has not reported, "the run ended
+   * early") is premature: "Return the rows" read Skipped while its run was
+   * still writing rows.
+   */
+  runActive?: boolean;
+}): {
+  skipped: Set<string>;
+  notReached: Set<string>;
+  indeterminate: Set<string>;
+} {
+  const skipped = new Set<string>();
+  const notReached = new Set<string>();
+  const indeterminate = new Set<string>();
+  for (const node of input.docflow.nodes) {
+    const reason = deriveDocflowUnreachedReason({
+      docflow: input.docflow,
+      nodeStates: input.nodeStates,
+      nodeId: node.id,
+    });
+    const verdict = docflowUnreachedVerdict({
+      reason: reason.kind,
+      runTerminal: !input.runActive,
+    });
+    if (verdict === 'skipped') skipped.add(node.id);
+    else if (verdict === 'not_reached') notReached.add(node.id);
+    else if (verdict === 'unknown') indeterminate.add(node.id);
+  }
+  return { skipped, notReached, indeterminate };
+}
+
+/**
+ * The ONE rule for what a node the run carries no state for is — the canvas
+ * pill and `deepline runs get` both read it (through
+ * `nodeExecutionForUnreachedReason` in run-execution-state.ts). `null` makes no
+ * claim: the node ran, nothing has run, or the run is still moving toward it.
+ *
+ *  - a decision took another arm, or the run marked it skipped → `skipped`;
+ *  - a per-row branch (some rows went there) or a node the run passed through
+ *    without recording → `unknown`: no true word at node grain;
+ *  - once the run is over, every other reason (an upstream failure, a stop, a
+ *    bypass, no executed upstream) → `not_reached`. While it runs, none of
+ *    those is a fact yet.
+ */
+export function docflowUnreachedVerdict(input: {
+  reason: DocflowUnreachedReason['kind'] | string;
+  runTerminal: boolean;
+}): 'skipped' | 'not_reached' | 'unknown' | null {
+  switch (input.reason) {
+    case 'reached':
+    case 'no_run':
+    case 'loading':
+    case 'run_in_progress':
+      return null;
+    case 'branch_not_taken':
+    case 'skipped_by_run':
+      return 'skipped';
+    case 'row_grain_branch':
+    case 'not_recorded':
+      return 'unknown';
+    default:
+      return input.runTerminal ? 'not_reached' : null;
+  }
+}

package/dist/bundling-sources/shared_libs/plays/docflow.ts

@@ -97,6 +97,16 @@ export type PlayDocflowSubgraph = {
   id: string;
   label: string;
   memberIds: string[];
+  /**
+   * The subgraph this one is declared inside, when it is nested. `memberIds`
+   * holds only direct members, so without this an outer region could not know
+   * that an inner region belongs inside its frame.
+   *
+   * Omitted (never `null`) at the top level, for the same reason as `arm`
+   * above: a field present on every subgraph would change the contract hash of
+   * every diagrammed play. Only a play that actually nests regions gains it.
+   */
+  parentId?: string;
 };
 
 export type PlayDocflowBinding = {
@@ -794,6 +804,15 @@ function parseDocflowBlockGraph(
       if (existing && existing.label === existing.id && label !== id) {
         existing.label = label;
         existing.kind = kind;
+        // A bare edge endpoint only placed the node provisionally, wherever
+        // it was first named. Its declaration says where it lives: `firmo -->
+        // roster` in a loop, then `roster["…"]` inside a nested subgraph,
+        // left the nested region empty and the card drawn outside it.
+        for (const subgraph of subgraphs.values()) {
+          const at = subgraph.memberIds.indexOf(id);
+          if (at !== -1) subgraph.memberIds.splice(at, 1);
+        }
+        subgraphStack[subgraphStack.length - 1]?.memberIds.push(id);
       } else if (existing && existing.label !== label) {
         errors.push(`Docflow node "${id}" has conflicting labels.`);
       } else if (!existing) {
@@ -815,10 +834,12 @@ function parseDocflowBlockGraph(
           (rawLabel.startsWith("'") && rawLabel.endsWith("'")))
           ? rawLabel.slice(1, -1)
           : rawLabel;
+      const parent = subgraphStack[subgraphStack.length - 1];
       const subgraph: PlayDocflowSubgraph = {
         id,
         label: label || id,
         memberIds: [],
+        ...(parent ? { parentId: parent.id } : {}),
       };
       subgraphs.set(id, subgraph);
       subgraphStack.push(subgraph);

package/dist/bundling-sources/shared_libs/plays/play-exports.ts

@@ -93,14 +93,37 @@ export function isDefinePlayCall(node: AstNode | null): boolean {
   return false;
 }
 
-/** The literal name a `definePlay('…', …)` call declares, when it is one. */
+function stringLiteralValue(node: AstNode | null): string | null {
+  const expression = unwrapStaticExpression(node);
+  return expression?.type === 'Literal' && typeof expression.value === 'string'
+    ? expression.value
+    : null;
+}
+
+/**
+ * The literal name a definePlay call declares, when it is one: the first
+ * argument of `definePlay('…', run)`, or the `id` of `definePlay({ id: '…' })`.
+ */
 function definePlayName(node: AstNode | null): string | null {
   const expression = unwrapStaticExpression(node);
   if (!expression || expression.type !== 'CallExpression') return null;
-  const first = astArray(expression.arguments)[0] ?? null;
-  return first?.type === 'Literal' && typeof first.value === 'string'
-    ? first.value
-    : null;
+  const first = unwrapStaticExpression(
+    astArray(expression.arguments)[0] ?? null,
+  );
+  if (first?.type !== 'ObjectExpression') return stringLiteralValue(first);
+  let id: string | null = null;
+  for (const property of astArray(first.properties)) {
+    if (property.type !== 'Property' || property.computed) continue;
+    const key = isAstNode(property.key) ? property.key : null;
+    const keyName =
+      getIdentifierName(key) ??
+      (key?.type === 'Literal' && typeof key.value === 'string'
+        ? key.value
+        : null);
+    if (keyName !== 'id') continue;
+    id = stringLiteralValue(isAstNode(property.value) ? property.value : null);
+  }
+  return id;
 }
 
 /**