@revenexx/studio-integrations 2.8.0 → 2.9.0

package/dist/runtime/data/canvasShapes.d.ts

@@ -0,0 +1,139 @@
+import type { WorkflowEdge, WorkflowNode, WorkflowTrigger } from '../types/integrations.js';
+import type { ShapeRule } from './graphShapes.js';
+/**
+ * What a canvas draws of a workflow's splits and merges (PO-750, rules in PO-746).
+ *
+ * Three things, all read from the analysis the save check runs (`graphShapes.ts`):
+ *
+ * - a **splitter** — an output port with more than one connection leaving it — is
+ *   drawn as a box instead of a dot, on that port only;
+ * - a **merger** — an input whose connections come from the branches of one
+ *   splitter — is drawn as a box instead of a dot. A converging input (the
+ *   branches of a condition, several triggers) keeps its dot;
+ * - a **virtual merger** — each intermediate level the analysis needed to break a
+ *   nested shape down — is a small box in front of the input, and the connections
+ *   of that level arrive at it rather than at the input dot.
+ *
+ * **Drawn, never stored.** The virtual merger is a second connection dot on the
+ * node card that owns the input, placed relative to that input: auto-layout never
+ * sees it, nobody can select, drag or delete it, and the workflow keeps naming the
+ * node the connection arrives at, nothing else. A connection routed through it is
+ * the same connection with the same id — selecting, deleting, re-pointing and the
+ * replay's colouring all keep working, because none of them read which dot an end
+ * sits on. The other way to draw it, a node of its own on the canvas, would have
+ * had to be kept out of every path that walks the canvas's nodes: select-all,
+ * copy, delete, tidy up, the minimap, the fit.
+ *
+ * One function for all three canvases (editor, run replay, history preview), so
+ * that they cannot disagree about a workflow, and called per sync like
+ * {@link nodeLoopData}: the shapes are a function of the connections.
+ */
+/**
+ * One branch arriving at an input, as its tooltip names it: the step it ends in,
+ * the output it leaves by, and how the receiving step reads what it hands on
+ * (rules of PO-746, the run-time half in PO-502).
+ */
+export interface BranchLine {
+    /** The step's name, or the trigger's. */
+    label: string;
+    /**
+     * The output it leaves by — `null` for a trigger, which has only the one. Its
+     * label is looked up when the line is written (`branchLineText`), not here: the
+     * catalogue can arrive after the canvas first syncs, and a label read then would
+     * stay the bare port name.
+     */
+    port: {
+        nodeSlug: string;
+        nodeVersion: string;
+        output: string;
+    } | null;
+    /**
+     * Where the receiving step finds it in an expression: `in.<step id>` when the
+     * branch is gathered with others (a merger hands each one on by the step it
+     * ends in), plain `in` when it is the one alternative that arrived.
+     */
+    address: string;
+}
+/** The output as its dot names it — the manifest's label — with the port name beside it where that reads differently. */
+export declare function portLabelText(port: NonNullable<BranchLine['port']>): string;
+/** One branch as one tooltip line: `Price lines · Out → ${{ in.price }}`. */
+export declare function branchLineText(b: BranchLine): string;
+/** A level of a merge drawn in front of an input. */
+export interface VirtualMergerMark {
+    /** The dot the connections of this level arrive at. */
+    handleId: string;
+    /** 1 directly in front of the input, 2 in front of that, and so on. */
+    level: number;
+    /**
+     * The virtual merger this one stands in front of, as an index into the same
+     * list — `null` on level 1, which stands in front of the input itself.
+     */
+    parent: number | null;
+    /** `merger`: every branch of one splitter (AND). `converging`: one of several (OR). */
+    kind: 'merger' | 'converging';
+    /**
+     * Where the box stands across from the input, in steps of one box width: `-1`
+     * one step left of what it feeds, `2` two steps right. Never `0` — a box straight
+     * in front of the input would sit on the connections that pass it by to arrive
+     * at the input itself.
+     */
+    offset: number;
+    /** The steps whose connections this level gathers, by the name the canvas shows. */
+    members: string[];
+    /** The same, by id — what decides which connection arrives here. */
+    memberIds: string[];
+    /** Each connection this level gathers, in the order the workflow stores them. */
+    branches: BranchLine[];
+}
+/** The rules of how branches come back together, which the canvas says as it is drawn. */
+export type JoinRule = Extract<ShapeRule, 'merger-across-splitters' | 'splitter-bypassed' | 'undecomposable-shape'>;
+/**
+ * An input the save will refuse because of how branches arrive at it (decided
+ * 19 Oct 2026), with the connection where one branch of a split crosses into
+ * another when the analysis found it — the one to change, rarely at this step.
+ */
+export interface ShapeRefusal {
+    rule: JoinRule;
+    crossing?: {
+        edgeId: string;
+        /** The step the crossing leaves, as its card names it … */
+        from: string;
+        /** … by which output, as its dot names it … */
+        output: string;
+        /** … and the step it crosses into. */
+        to: string;
+    };
+}
+/** What one node card draws of the shapes. Absent from the map: nothing to draw. */
+export interface NodeShapeData {
+    /** The output ports with more than one connection leaving them. */
+    splitPorts?: string[];
+    /** The input merges the branches of one splitter. */
+    merger?: boolean;
+    /** The input converges: several alternatives, of which the one that ran arrives. */
+    converging?: boolean;
+    /** On a merger or a converging input: every connection arriving, in stored order. */
+    inputBranches?: BranchLine[];
+    /** Levels drawn in front of the input, level 1 first. */
+    virtualMergers?: VirtualMergerMark[];
+    /** The input is refused by the rules for joining branches; it is then neither merger nor converging. */
+    refused?: ShapeRefusal;
+}
+export interface CanvasShapes {
+    byNode: Map<string, NodeShapeData>;
+    /** Trigger ids whose one output splits. */
+    splitTriggers: Set<string>;
+    /** Ids of the connections where branches of a split cross, to draw as the ones to change. */
+    crossingEdges: Set<string>;
+    /** Every refused input, in the analysis's order — what a change is compared by. */
+    refusals: (ShapeRefusal & {
+        nodeId: string;
+    })[];
+    /**
+     * The dot a connection arrives at when it is not the input dot: the deepest
+     * virtual merger in front of its target whose level gathers its source. `null`
+     * means the input dot, which is every connection but those.
+     */
+    arrivalHandle: (edge: Pick<WorkflowEdge, 'from' | 'to'>) => string | null;
+}
+export declare function canvasShapes(nodes: readonly WorkflowNode[], edges: readonly WorkflowEdge[], triggers?: readonly WorkflowTrigger[]): CanvasShapes;

package/dist/runtime/data/canvasShapes.js

@@ -0,0 +1,130 @@
+import { nodeDisplayLabel } from "../utils/validationFindings.js";
+import { resolveDisplayName, resolveLocalized } from "../utils/localize.js";
+import { findManifest, triggerTypeLabel } from "./integrationNodeCatalog.js";
+import { isTerminalManifest } from "./nodeInputData.js";
+import { analyzeGraphShapes } from "./graphShapes.js";
+import { iteratorNodeIds } from "./loopBody.js";
+import { virtualMergerHandleId } from "./handleId.js";
+export function portLabelText(port) {
+  const declared = findManifest(port.nodeSlug, port.nodeVersion)?.outputs?.find((o) => o.name === port.output);
+  const label = resolveLocalized(declared?.label) || port.output;
+  return label.toLowerCase() === port.output.toLowerCase() ? label : `${label} (${port.output})`;
+}
+export function branchLineText(b) {
+  return `${b.port ? `${b.label} \xB7 ${portLabelText(b.port)}` : b.label} \u2192 \${{ ${b.address} }}`;
+}
+const JOIN_RULES = /* @__PURE__ */ new Set(["merger-across-splitters", "splitter-bypassed", "undecomposable-shape"]);
+function splittersOf(nodeIds, edges) {
+  const count = /* @__PURE__ */ new Map();
+  for (const e of edges) {
+    if (!nodeIds.has(e.to.nodeId)) continue;
+    const key = `${e.from.nodeId}\0${e.from.output}`;
+    const entry = count.get(key) ?? { nodeId: e.from.nodeId, port: e.from.output, n: 0 };
+    entry.n += 1;
+    count.set(key, entry);
+  }
+  return [...count.values()].filter((p) => p.n > 1).map(({ nodeId, port }) => ({ nodeId, port }));
+}
+export function canvasShapes(nodes, edges, triggers = []) {
+  const byNode = /* @__PURE__ */ new Map();
+  const splitTriggers = /* @__PURE__ */ new Set();
+  const nodeIds = new Set(nodes.map((n) => n.id));
+  const entry = (id) => {
+    const found = byNode.get(id);
+    if (found) return found;
+    const fresh = {};
+    byNode.set(id, fresh);
+    return fresh;
+  };
+  const terminals = nodes.filter((n) => isTerminalManifest(findManifest(n.nodeSlug, n.nodeVersion))).map((n) => n.id);
+  const shapes = analyzeGraphShapes({ nodes: [...nodes], edges: [...edges] }, { iterators: iteratorNodeIds(nodes), terminals });
+  for (const { nodeId, port } of splittersOf(nodeIds, edges)) {
+    if (nodeIds.has(nodeId)) (entry(nodeId).splitPorts ??= []).push(port);
+    else splitTriggers.add(nodeId);
+  }
+  for (const merger of shapes.mergers) entry(merger.nodeId).merger = true;
+  for (const id of shapes.converging) entry(id).converging = true;
+  const labelOf = new Map([
+    ...triggers.map((t) => [t.id, resolveDisplayName(t.name) || triggerTypeLabel(t.type)]),
+    ...nodes.map((n) => [n.id, nodeDisplayLabel(n)])
+  ]);
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  const portOf = (nodeId, output) => {
+    const n = nodeById.get(nodeId);
+    return n ? { nodeSlug: n.nodeSlug, nodeVersion: n.nodeVersion, output } : null;
+  };
+  const keyedAt = /* @__PURE__ */ new Map();
+  for (const vm of shapes.virtualMergers) {
+    if (vm.kind !== "merger") continue;
+    const keyed = keyedAt.get(vm.input) ?? /* @__PURE__ */ new Set();
+    vm.members.forEach((m) => keyed.add(m));
+    keyedAt.set(vm.input, keyed);
+  }
+  const mergerIds = new Set(shapes.mergers.map((m) => m.nodeId));
+  const branchesInto = (input, sources) => edges.filter((e) => e.to.nodeId === input && (!sources || sources.includes(e.from.nodeId))).map((e) => ({
+    label: labelOf.get(e.from.nodeId) ?? e.from.nodeId,
+    port: portOf(e.from.nodeId, e.from.output),
+    address: mergerIds.has(input) || keyedAt.get(input)?.has(e.from.nodeId) ? `in.${e.from.nodeId}` : "in"
+  }));
+  for (const id of [...mergerIds, ...shapes.converging]) entry(id).inputBranches = branchesInto(id);
+  const xOf = new Map(nodes.filter((n) => n.position).map((n) => [n.id, n.position.x]));
+  const meanX = (ids) => {
+    const xs = ids.map((id) => xOf.get(id)).filter((x) => x !== void 0);
+    return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null;
+  };
+  for (const vm of shapes.virtualMergers) {
+    const list = entry(vm.input).virtualMergers ??= [];
+    const found = list.findIndex((p) => p.level === vm.level - 1 && vm.members.every((m) => p.memberIds.includes(m)));
+    const parent = found < 0 ? null : found;
+    const around = parent === null ? edges.filter((e) => e.to.nodeId === vm.input).map((e) => e.from.nodeId) : list[parent].memberIds;
+    const mine = meanX(vm.members);
+    const rest = meanX(around.filter((id) => !vm.members.includes(id)));
+    const side = mine !== null && rest !== null && mine > rest ? 1 : -1;
+    const taken = list.filter((o) => o.parent === parent && Math.sign(o.offset - (parent === null ? 0 : list[parent].offset)) === side).length;
+    list.push({
+      handleId: virtualMergerHandleId(list.length + 1, "top"),
+      level: vm.level,
+      parent,
+      offset: (parent === null ? 0 : list[parent].offset) + side * (1 + taken),
+      kind: vm.kind,
+      members: vm.members.map((id) => labelOf.get(id) ?? id),
+      memberIds: vm.members,
+      branches: branchesInto(vm.input, vm.members)
+    });
+  }
+  const arrivalHandle = (edge) => {
+    const levels = byNode.get(edge.to.nodeId)?.virtualMergers;
+    if (!levels) return null;
+    let deepest = null;
+    for (const vm of levels) {
+      if (vm.memberIds.includes(edge.from.nodeId) && (!deepest || vm.level > deepest.level)) deepest = vm;
+    }
+    return deepest?.handleId ?? null;
+  };
+  const outputLabel = (nodeId, output) => {
+    const n = nodeById.get(nodeId);
+    const declared = n ? findManifest(n.nodeSlug, n.nodeVersion)?.outputs?.find((o) => o.name === output) : void 0;
+    return resolveLocalized(declared?.label) || output;
+  };
+  const crossingEdges = /* @__PURE__ */ new Set();
+  const refusals = [];
+  for (const v of shapes.violations) {
+    if (!JOIN_RULES.has(v.rule) || !nodeIds.has(v.nodeId)) continue;
+    const e = v.edgeIndex === void 0 ? void 0 : edges[v.edgeIndex];
+    const refused = {
+      rule: v.rule,
+      ...e ? {
+        crossing: {
+          edgeId: e.id,
+          from: labelOf.get(e.from.nodeId) ?? e.from.nodeId,
+          output: outputLabel(e.from.nodeId, e.from.output),
+          to: labelOf.get(e.to.nodeId) ?? e.to.nodeId
+        }
+      } : {}
+    };
+    if (e) crossingEdges.add(e.id);
+    entry(v.nodeId).refused = refused;
+    refusals.push({ nodeId: v.nodeId, ...refused });
+  }
+  return { byNode, splitTriggers, crossingEdges, refusals, arrivalHandle };
+}

package/dist/runtime/data/connectionRules.d.ts

@@ -0,0 +1,110 @@
+import type { WorkflowEdge, WorkflowNode } from '../types/integrations.js';
+/**
+ * Which connections the canvas refuses while they are being drawn (PO-750, rule 11
+ * of PO-746).
+ *
+ * **Only one that no added connection can make valid** — only removing one that
+ * already stands could:
+ *
+ * - one that **closes a cycle** — adding connections never takes a cycle out;
+ * - one that **crosses a loop's boundary for good** — a connection into a loop's
+ *   body from a step that can never join that body, or out of the body into a step
+ *   the rest of the workflow already reaches. Only `item` leads in and only `done`
+ *   leads out.
+ *
+ * Everything else — a merger across two splitters, a branch that bypasses its
+ * splitter, a shape that does not break down, a reference to a sibling branch, and
+ * a crossing the author can still close by drawing more — is left to the save,
+ * which names what is wrong. Refusing more while drawing would make the verdict
+ * depend on the order things are drawn in, because a shape is often invalid halfway
+ * through being drawn.
+ *
+ * **When a crossing can still be closed.** A loop's body is everything its Item
+ * output reaches — the definition the save check's `graphShapes.ts` uses. A
+ * connection from a step outside it into it crosses; but if that step is fed by
+ * nothing, connecting the body to it pulls it in, and the crossing is gone. In
+ * general a crossing can be closed by additions alone exactly when everything that
+ * would have to join the body with its source — the source, what feeds it and what
+ * it leads to, outward until the body is met — holds neither a trigger nor the loop
+ * itself. That is a property of the graph, not of the order its connections were
+ * drawn in: `x → body` drawn before `body → x` or after it ends in the same verdict.
+ *
+ * Only a violation the change *adds* refuses it. A workflow that already carries
+ * one — saved before the rules existed — can still be edited everywhere else, and a
+ * cycle already in it does not stop the loop boundaries from being judged.
+ */
+export type NeverValid = 'cycle' | 'loop-boundary';
+interface Graph {
+    nodes: readonly Pick<WorkflowNode, 'id'>[];
+    edges: readonly WorkflowEdge[];
+}
+/**
+ * The ids of the connections crossing a loop's boundary that no added connection
+ * can close. Exported for the writers that place several connections at once
+ * (duplicate, paste), which judge the finished set rather than each in turn.
+ */
+export declare function lastingCrossings(graph: Graph, iterators: readonly string[]): Set<string>;
+/**
+ * Why a change was refused, with what the explanation names (PO-750): the steps a
+ * cycle would run through, or the loop whose boundary is crossed — and how: into
+ * its steps from outside, out of them into a step something else reaches as well,
+ * or from its own Item output to a step something outside reaches.
+ */
+export type Refusal = {
+    reason: 'cycle';
+    from?: string;
+    to?: string;
+} | {
+    reason: 'loop-boundary';
+    iterator: string;
+    direction: 'into';
+    inside: string;
+} | {
+    reason: 'loop-boundary';
+    iterator: string;
+    direction: 'out';
+    inside: string;
+    outside: string;
+} | {
+    reason: 'loop-boundary';
+    iterator: string;
+    direction: 'item';
+    outside: string;
+};
+/** {@link neverValidChange}, with what the explanation names. */
+export declare function refusalOfChange(before: Graph, after: Graph, iterators: readonly string[]): Refusal | null;
+/**
+ * What a change to the workflow's connections adds that no added connection can
+ * make valid, or `null` when it adds nothing. `before` and `after` are the same
+ * workflow; connections are told apart by id.
+ */
+export declare function neverValidChange(before: Graph, after: Graph, iterators: readonly string[]): NeverValid | null;
+export type Candidate = {
+    from: {
+        nodeId: string;
+        output: string;
+    };
+    to: {
+        nodeId: string;
+    };
+};
+/**
+ * A judge for the connections drawn in one gesture. The workflow as it stands does
+ * not change while a connection is dragged, so what is known about it — who reaches
+ * whom, which crossings already stand — is worked out once, here, and each dot the
+ * drag passes only adds its one connection (review of #297: Vue Flow asks on every
+ * pointer move near a dot).
+ *
+ * `replacing` names a connection the new one takes the place of: an end of an
+ * existing connection being re-pointed. It is judged as gone, so the connection
+ * does not stand in its own way.
+ */
+export declare function refusalJudge(graph: Graph, iterators: readonly string[], replacing?: string | null): (candidate: Candidate) => Refusal | null;
+/**
+ * Why the connection from `from` to `to` can never become valid by drawing more,
+ * with what the explanation names — or `null` when it may be drawn.
+ */
+export declare function connectionRefusal(graph: Graph, iterators: readonly string[], candidate: Candidate, replacing?: string | null): Refusal | null;
+/** {@link connectionRefusal}, the reason alone. */
+export declare function connectionNeverValid(graph: Graph, iterators: readonly string[], candidate: Candidate, replacing?: string | null): NeverValid | null;
+export {};

package/dist/runtime/data/connectionRules.js

@@ -0,0 +1,110 @@
+import { ITEM_PORT } from "./loopBody.js";
+function adjacency(graph) {
+  const nodeIds = new Set(graph.nodes.map((n) => n.id));
+  const out = /* @__PURE__ */ new Map();
+  const into = /* @__PURE__ */ new Map();
+  const add = (map, key, e) => {
+    const list = map.get(key);
+    if (list) list.push(e);
+    else map.set(key, [e]);
+  };
+  for (const e of graph.edges) {
+    if (!nodeIds.has(e.to.nodeId)) continue;
+    add(out, e.from.nodeId, e);
+    add(into, e.to.nodeId, e);
+  }
+  return { nodeIds, out, into };
+}
+function reach(adj, start) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [...start];
+  for (let i = 0; i < queue.length; i++) {
+    const id = queue[i];
+    if (seen.has(id)) continue;
+    seen.add(id);
+    for (const e of adj.out.get(id) ?? []) queue.push(e.to.nodeId);
+  }
+  return seen;
+}
+function closesCycle(adj, from, to) {
+  return from === to || reach(adj, [to]).has(from);
+}
+function closable(adj, iterator, body, source) {
+  const seen = /* @__PURE__ */ new Set();
+  const queue = [source];
+  for (let i = 0; i < queue.length; i++) {
+    const id = queue[i];
+    if (seen.has(id) || body.has(id)) continue;
+    if (id === iterator || !adj.nodeIds.has(id)) return false;
+    seen.add(id);
+    for (const e of adj.into.get(id) ?? []) queue.push(e.from.nodeId);
+    for (const e of adj.out.get(id) ?? []) queue.push(e.to.nodeId);
+  }
+  return true;
+}
+function crossingsOf(adj, iterators) {
+  const lasting = /* @__PURE__ */ new Map();
+  for (const it of iterators) {
+    if (!adj.nodeIds.has(it)) continue;
+    const items = (adj.out.get(it) ?? []).filter((e) => e.from.output === ITEM_PORT);
+    const body = reach(adj, items.map((e) => e.to.nodeId));
+    if (body.has(it)) continue;
+    for (const id of body) {
+      for (const e of adj.into.get(id) ?? []) {
+        if (body.has(e.from.nodeId)) continue;
+        if (e.from.nodeId === it && e.from.output === ITEM_PORT) continue;
+        if (!closable(adj, it, body, e.from.nodeId) && !lasting.has(e.id)) lasting.set(e.id, { edge: e, iterator: it, body });
+      }
+    }
+  }
+  return lasting;
+}
+export function lastingCrossings(graph, iterators) {
+  return new Set(crossingsOf(adjacency(graph), iterators).keys());
+}
+export function refusalOfChange(before, after, iterators) {
+  const was = new Set(before.edges.map((e) => e.id));
+  const adjAfter = adjacency(after);
+  for (const e of after.edges) {
+    if (was.has(e.id) || !adjAfter.nodeIds.has(e.to.nodeId)) continue;
+    const without = adjacency({ nodes: after.nodes, edges: after.edges.filter((x) => x.id !== e.id) });
+    if (closesCycle(without, e.from.nodeId, e.to.nodeId)) return { reason: "cycle" };
+  }
+  const crossed = lastingCrossings(before, iterators);
+  const added = [...crossingsOf(adjAfter, iterators).values()].find((c) => !crossed.has(c.edge.id));
+  return added ? { reason: "loop-boundary", iterator: added.iterator, direction: "into", inside: added.edge.to.nodeId } : null;
+}
+export function neverValidChange(before, after, iterators) {
+  return refusalOfChange(before, after, iterators)?.reason ?? null;
+}
+const CANDIDATE_ID = "\0candidate";
+export function refusalJudge(graph, iterators, replacing) {
+  const kept = replacing ? graph.edges.filter((e) => e.id !== replacing) : graph.edges;
+  const adjBefore = adjacency({ nodes: graph.nodes, edges: kept });
+  const crossed = new Set(crossingsOf(adjBefore, iterators).keys());
+  return (candidate) => {
+    const ends = { from: candidate.from.nodeId, to: candidate.to.nodeId };
+    if (closesCycle(adjBefore, ends.from, ends.to)) return { reason: "cycle", ...ends };
+    const adjAfter = adjacency({
+      nodes: graph.nodes,
+      edges: [...kept, { id: CANDIDATE_ID, from: candidate.from, to: { nodeId: ends.to } }]
+    });
+    const crossings = [...crossingsOf(adjAfter, iterators).values()];
+    const added = crossings.find((c) => !crossed.has(c.edge.id));
+    if (!added) return null;
+    const { iterator } = added;
+    if (ends.from === iterator && candidate.from.output === ITEM_PORT) {
+      return { reason: "loop-boundary", iterator, direction: "item", outside: ends.to };
+    }
+    if (added.body.has(ends.from)) {
+      return { reason: "loop-boundary", iterator, direction: "out", inside: ends.from, outside: ends.to };
+    }
+    return { reason: "loop-boundary", iterator, direction: "into", inside: added.edge.to.nodeId };
+  };
+}
+export function connectionRefusal(graph, iterators, candidate, replacing) {
+  return refusalJudge(graph, iterators, replacing)(candidate);
+}
+export function connectionNeverValid(graph, iterators, candidate, replacing) {
+  return connectionRefusal(graph, iterators, candidate, replacing)?.reason ?? null;
+}

package/dist/runtime/data/graphShapes.d.ts

@@ -0,0 +1,175 @@
+import type { WorkflowEdge, WorkflowNode } from '../types/integrations.js';
+/**
+ * The shapes a workflow graph's joins take (PO-748, rules decided in PO-746):
+ * which output ports split, which inputs merge the branches of one split, which
+ * inputs converge OR-branches, which loop bodies are closed, and which shapes
+ * are refused. Held to `graphShapes.cases.json`, the table the API's save-time
+ * check and the studio canvas port this algorithm against.
+ *
+ * An input is a node's input name (`to.input`, `in` when absent). How an input
+ * with several connections is judged: the graph gets a virtual ROOT above every
+ * origin — each trigger handle, and each node nothing feeds — so that every
+ * vertex has dominators. For the input's connections ("branches"):
+ *
+ *   1. Find the nearest common dominator `n` of the branches' source vertices:
+ *      the deepest vertex every path to every branch passes through. "Same
+ *      splitter" is judged by dominance (decided 15 Oct 2026): a branch that can
+ *      also be reached around a splitter does not belong to it.
+ *   2. For each branch, collect the connections leaving `n` it can be reached
+ *      through, and group branches that share one. One group only means the
+ *      branches do not leave `n` each via their own connection. Through a single
+ *      port of `n` that is `merger-across-splitters`; through several ports (or
+ *      origins), some branch reaches the input around the splitter the others
+ *      share — `splitter-bypassed`, naming that splitter and branch.
+ *   3. A group reached through two ports of `n` mixes "always" with "only if
+ *      this port fired" — `undecomposable-shape`.
+ *   4. All groups on one port: an AND level, a merger at that splitter port.
+ *      Groups on several ports: an OR level, a converging input; ports carrying
+ *      several groups become an AND level beneath it. ROOT's ports are its
+ *      origins, so several triggers always converge.
+ *   5. A group of several branches is decomposed again from step 1. Every level
+ *      between the input and its top level is a virtual merger the canvas
+ *      draws in front of the input (render-only, never stored or run).
+ *
+ * Every part is decomposed even after one is refused, and the input reports
+ * one refusal, picked by precedence: `splitter-bypassed`, then
+ * `merger-across-splitters`, then `undecomposable-shape`, ties broken by the
+ * named splitter and branch. So the verdict cannot depend on edge order.
+ *
+ * Mixed AND/OR at one input (cond.true → a and b, cond.false → d, all into m)
+ * stays a converging input with an AND level in front of it (decided 15 Oct
+ * 2026). At run time it hands on whatever arrived — the inner merger's keyed
+ * object `{a, b}`, or d's output as it is — so its `in.x` is not checked:
+ * `merger-in-reference` applies to inputs whose top level is a merger.
+ *
+ * A loop body ends in exactly one step (`loop-end-not-unique` otherwise). A
+ * terminal step — one whose manifest declares no output ports at all, such as
+ * `revenexx:stop-and-error` — ends the run, not the body, so it is no body end
+ * (decided 15 Oct 2026): it stays a body member, a connection into it does not
+ * keep its source from being the end, and it is never the end itself. That is
+ * what lets a body route each step's error to its own stop step.
+ *
+ * Pure and deterministic: no clock, randomness or IO, and every list it returns
+ * is sorted by Unicode code point (see {@link analyzeGraphShapes}).
+ *
+ * **A port, not a second design (PO-750).** This file is the worker's
+ * `worker/src/graphShapes.ts` in revenexx/integrations (PR #357, PO-748), taken
+ * over almost verbatim: the canvas draws splitters and mergers from it, and the
+ * drag refuses a connection from it (`connectionRules.ts`), so what the canvas
+ * shows must be what the save check decides. The two are held together by one
+ * table, `graphShapes.cases.json`, which `graphShapes.test.ts` runs here from a
+ * byte-identical copy. A change to the algorithm goes to the worker first and
+ * comes back here with the table — never the other way round. The only edits:
+ * the import of the blob types, this paragraph, the repository's code style, and
+ * the non-null assertions this repository's stricter index checking asks for.
+ * No Vue import, so the unit suite reaches it.
+ */
+export interface ShapePort {
+    nodeId: string;
+    port: string;
+}
+export interface MergerBranch {
+    splitter: ShapePort;
+    /** The node whose output the merger receives as `in.<lastNodeId>` — a trigger handle when the branch is the trigger's own connection. */
+    lastNodeId: string;
+}
+export interface ShapeMerger {
+    nodeId: string;
+    /** Only when the node's connections name more than one input. */
+    inputName?: string;
+    branches: MergerBranch[];
+}
+export interface VirtualMerger {
+    /** The node the level is drawn in front of. */
+    input: string;
+    /** Only when the node's connections name more than one input. */
+    inputName?: string;
+    /** 1 is the level directly in front of the input, 2 the one in front of that, and so on. */
+    level: number;
+    kind: 'merger' | 'converging';
+    /** Only on a `merger` level. */
+    splitter?: ShapePort;
+    /** The lastNodeIds of the input's connections this level gathers. */
+    members: string[];
+}
+export interface LoopBody {
+    members: string[];
+    /** Absent when the body has no node, or more than one end. */
+    endNode?: string;
+}
+export type ShapeRule = 'merger-across-splitters' | 'splitter-bypassed' | 'undecomposable-shape' | 'sibling-reference' | 'loop-boundary' | 'loop-end-not-unique' | 'merger-in-reference' | 'cycle';
+export interface ShapeViolation {
+    rule: ShapeRule;
+    nodeId: string;
+    /** Shape rules, only when the node's connections name more than one input. */
+    inputName?: string;
+    /**
+     * The index in `blob.edges` of the connection that crosses: a loop body's
+     * boundary (`loop-boundary`), or from one branch of a split into another
+     * (`merger-across-splitters`, where one is found).
+     */
+    edgeIndex?: number;
+    /** Reference rules: the node id (`nodes.`) or key (`in.`) referenced. */
+    target?: string;
+    /** `splitter-bypassed`: the splitter the other branches pass … */
+    splitter?: ShapePort;
+    /** … and the lastNodeId of the branch that reaches the input around it. */
+    branch?: string;
+}
+/** An `${{ nodes.<target>… }}` or `${{ in.<target>… }}` in a node's settings. */
+export interface ShapeReference {
+    fromNodeId: string;
+    root: 'nodes' | 'in';
+    target: string;
+}
+export interface GraphShapes {
+    splitters: ShapePort[];
+    mergers: ShapeMerger[];
+    /** Nodes with at least one converging input. */
+    converging: string[];
+    virtualMergers: VirtualMerger[];
+    loopBodies: Record<string, LoopBody>;
+    violations: ShapeViolation[];
+}
+export interface GraphShapeAnalysis extends GraphShapes {
+    /**
+     * The merger's branches, or `null` when that input is not a merger. Without
+     * `inputName`, the node's first merging input in code-point order.
+     */
+    mergerBranches(nodeId: string, inputName?: string): MergerBranch[] | null;
+    /** The loop body's one end node, or `null` when it has none or several. */
+    loopEndNode(iteratorId: string): string | null;
+    /** Whether `targetNodeId` lies in a sibling branch of a splitter `fromNodeId` is in (rule 9). */
+    isSiblingReference(fromNodeId: string, targetNodeId: string): boolean;
+}
+export interface GraphShapeOptions {
+    /**
+     * Output ports per node, as its manifest declares them. Informational: the
+     * shapes are read from the ports the connections name, and a declared port
+     * nothing is wired to splits nothing and converges nothing.
+     */
+    ports?: Record<string, string[]>;
+    /** Node ids of iterator nodes (ports `item` and `done`). */
+    iterators: string[];
+    /** Node ids of terminal steps (no declared output ports): never a loop body's end. */
+    terminals?: string[];
+    references?: ShapeReference[];
+}
+export interface GraphShapeBlob {
+    nodes: Pick<WorkflowNode, 'id'>[];
+    edges: Pick<WorkflowEdge, 'from' | 'to'>[];
+}
+/**
+ * Analyses the shapes of `blob`. Sorting, so the result compares as plain data:
+ * splitters by nodeId then port; mergers by nodeId, inputName, their branches
+ * by lastNodeId then splitter; converging ids; virtual mergers by input,
+ * inputName, level, then members; loop members; violations by rule, nodeId,
+ * inputName, edgeIndex, target, branch. Optional fields are omitted, never null.
+ *
+ * A connection from an id that is no node is read as a trigger handle — the
+ * save-time check reports dangling ids on its own. A graph with a cycle is
+ * reported as one `cycle` violation per node on a cycle and nothing else —
+ * dominance is undefined there. An input receiving a connection across a loop
+ * boundary is not classified further: the boundary is the error.
+ */
+export declare function analyzeGraphShapes(blob: GraphShapeBlob, opts: GraphShapeOptions): GraphShapeAnalysis;