@contraagent/ui 0.0.0-stage → 0.2.0

package/src/adapters/graph/input.ts

@@ -0,0 +1,236 @@
+// A layer of the run's flow as `<cae-layered-graph>` takes it, and a loop's passes
+// as `<cae-mark-matrix>` takes them: the pipeline graph's words on the generic model.
+import { deriveRun, type JournalRow, type Plan } from '@contraagent/api';
+import type { GraphClusterInput, GraphInput, GraphMark, GraphNodeInput, GraphOrder } from '@contraagent/elements/graph';
+import type { MarkMatrixInput, MatrixHeadCell, MatrixMark } from '@contraagent/elements/matrix';
+import type { Fact } from '@contraagent/elements/primitives';
+import { msg, str } from '@lit/localize';
+import { facts, listText } from '../../words/format.js';
+import { loopLabel, notStartedCause, passCount, passLabel, passSpread } from '../../words/index.js';
+import type { TaskLinks } from './highlight.js';
+import { passMatrix, sortRows, type MatrixSort, type PassMatrix } from './matrix.js';
+import { edgeStyle, project, type Projection } from './project.js';
+import { markSel } from './selection.js';
+import type { GraphNode, LayerMark, LayerModel, LoopBox } from './types.js';
+import { doneOf, exceptions, executorWord, markText, nodeLabel, nodeTip, where, type ExceptionClass, type MarkContext } from './words.js';
+
+/** What the words of the marks read: the run's tasks, why a task did not start, and the run being live. */
+export interface GraphWordsContext {
+  plan: Plan;
+  journal: readonly JournalRow[];
+  /** The run id: paths in a cause are shown relative to it. */
+  run: string;
+  live: boolean;
+  links: TaskLinks;
+}
+
+/** A note's tone by the class of a node's fact. */
+const NOTE_TONE: Record<ExceptionClass, Fact['tone']> = { err: 'failed', warn: 'attention', live: 'running', mut: 'muted' };
+
+
+/** Why a task did not start, in words ('' when it is not known). */
+export function causeOf(x: Pick<GraphWordsContext, 'plan' | 'journal' | 'run'>): (key: string) => string {
+  return (key) => {
+    const { outcomes } = deriveRun(x.journal, x.plan);
+    const t = outcomes.get(key);
+    return t ? notStartedCause(t, outcomes, x.run) : '';
+  };
+}
+
+const markContext = (x: GraphWordsContext): ((m: LayerMark) => MarkContext) => {
+  const cause = causeOf(x);
+  return (m) => ({ task: x.links.byKey.get(m.key), causeOf: cause, live: x.live });
+};
+
+/** Where a loop is, as its box and its passes name it: "Loop at flow.py:12". */
+const loopAt = (b: Pick<LoopBox, 'loop' | 'file'>): string => msg(str`Loop at ${where(b.loop, b.file)}`);
+
+/** The executors' icons, as `executorIcon` draws them: `agent`, `python`. */
+const iconsOf = (n: GraphNode): string[] => (n.executor === 'mixed' ? ['agent', 'python'] : n.executor ? [n.executor] : []);
+
+/**
+ * The layer as the generic graph takes it: a node per kind or function (an agent
+ * task's node with an accent, a function node with an inner view), a cluster per
+ * loop box (it cycles: its return is the loop's next pass), a solid edge per
+ * `after` and a dashed one per `created_from`, and the units as the series. Its
+ * nodes are in the plan's order, as `arrange` reads them. With `open`, a function node
+ * can be drawn open (`toggle`), and each function drawn open (`LayerModel.fns`) is a
+ * cluster named by its path, each part a link to its own layer.
+ */
+export function graphInput(m: LayerModel, x: GraphWordsContext, open = false): GraphInput {
+  const ctx = markContext(x);
+  const mark = (n: GraphNode, mk: LayerMark): GraphMark => {
+    const { name, parts } = markText(n.label, mk, ctx(mk));
+    return {
+      id: markSel(n.id, mk),
+      state: mk.state,
+      label: facts(name, ...parts),
+      tip: [name, parts[0] ?? ''].filter(Boolean).join('\n'),
+      ...(mk.passes ? { badge: String(mk.passes) } : {}),
+      name: mk.unit || mk.key,
+      drill: !!mk.flow,
+    };
+  };
+  const nodes = m.nodes.map((n): GraphNodeInput => {
+    const c = n.counts;
+    return {
+      id: n.id,
+      label: n.label,
+      tip: nodeTip(n),
+      summary: nodeLabel(n, m, x.live),
+      cluster: n.box,
+      icons: iconsOf(n),
+      accent: n.executor === 'agent',
+      drill: n.type === 'flow',
+      marks: n.units.map((mk) => mk && mark(n, mk)),
+      loose: n.single.map((mk) => mark(n, mk)),
+      counts: c,
+      progress: { done: c.done, total: c.total, label: doneOf(c) },
+      notes: exceptions(n, x.live).map(([cls, text]) => ({ text, tone: NOTE_TONE[cls] })),
+      // Finished (done and skipped) only sets the frame's look; the count is of the tasks done.
+      look: c.failed || n.errors ? 'failed' : c.running ? 'running' : c.done + c.skipped === c.total ? 'done' : undefined,
+      // A function can be drawn open, where the layer is drawn with its functions (not in a loop's passes).
+      ...(n.type === 'flow' && open ? { toggle: 'closed' as const } : {}),
+    };
+  });
+  // A function drawn open: a cluster named by its path, its count and what is not done under its name.
+  const fns = m.fns.map((f): GraphClusterInput => {
+    const first = (f.parts[0] as (typeof f.parts)[number]).node;
+    const label = f.parts.map((p) => p.node.label).join(' › ');
+    const c = first.counts;
+    const notes = exceptions(first, x.live).map(([, text]) => text);
+    return {
+      id: f.id,
+      parent: f.parent,
+      label,
+      tip: first.name,
+      note: `${c.done}/${c.total}`,
+      ...(notes.length ? { detail: facts(...notes) } : {}),
+      summary: facts(label, nodeLabel(first, m, x.live)),
+      chipLabel: msg(str`Inside ${label}`),
+      chipTip: facts(msg('Function'), label),
+      drill: true,
+      cycle: false,
+      toggle: 'open',
+      path: f.parts.map((p) => ({ id: p.id, label: p.node.label, tip: p.node.name })),
+    };
+  });
+  const clusters = m.boxes.map((b): GraphClusterInput => {
+    const at = loopAt(b);
+    const spread = b.spread.length > 1 ? passSpread(b.spread) : '';
+    const passes = passCount(b.passes);
+    return {
+      id: b.id,
+      parent: b.parent,
+      label: loopLabel(),
+      tip: facts(loopLabel(), at),
+      note: passes,
+      ...(spread ? { detail: spread, detailTip: msg('Units by number of passes') } : {}),
+      summary: facts(at, passes, spread),
+      chipLabel: facts(msg(str`Passes of the loop at ${where(b.loop, b.file)}`), passes),
+      chipTip: facts(at, passes),
+      drill: true,
+      cycle: true,
+    };
+  });
+  return {
+    series: m.units,
+    nodes,
+    clusters: [...clusters, ...fns],
+    edges: m.edges.map((e) => ({ from: e.from, to: e.to, style: edgeStyle(e.type), weight: e.tasks, ranks: e.samePass })),
+    stubs: m.stubs.map((s) => ({ id: s.id, label: s.label, to: s.to, style: edgeStyle(s.type), weight: s.tasks })),
+  };
+}
+
+/** The layer `path` of the plan, as the generic graph takes it, and its projection (for the card's facts and a loop's passes). */
+export function graphFromPlan(plan: Plan, path: readonly string[], x: Omit<GraphWordsContext, 'plan'>): { input: GraphInput; proj: Projection } {
+  const proj = project(plan, path);
+  return { input: graphInput(proj.model, { ...x, plan }), proj };
+}
+
+/** How a loop's units can be sorted, and the words for each. */
+export const matrixSorts = (): { id: MatrixSort; label: string }[] => [
+  { id: 'order', label: msg('Scheduled order') },
+  { id: 'passes', label: msg('Number of passes') },
+  { id: 'state', label: msg('Status', { id: 'status', desc: 'The status of a task: done, failed, not started' }) },
+];
+
+/**
+ * A loop's passes as the generic mark matrix takes them: a row per unit (sorted by
+ * `sort`), a column per node and pass under a group per pass (a nested loop's passes
+ * as groups inside each pass of the outer one).
+ */
+export function matrixInput(mx: PassMatrix, sort: MatrixSort, x: GraphWordsContext): MarkMatrixInput {
+  const ctx = markContext(x);
+  const box = mx.box;
+  const caption = loopAt(box);
+  const units = mx.rows.filter((r) => r.unit).length;
+  const cell = (ci: number, mk: LayerMark): MatrixMark => {
+    const col = mx.columns[ci];
+    const label = col?.node.label ?? '';
+    const passes = col?.passes ?? [];
+    const { name, parts } = markText(label, mk, ctx(mk), listText(passes.map(passLabel)));
+    return { id: markSel(col?.node.id ?? '', mk, passes), state: mk.state, label: facts(name, ...parts), tip: [name, parts[0] ?? ''].filter(Boolean).join('\n'), drill: !!mk.flow };
+  };
+  const head = mx.head.map((row) =>
+    row.map((hd): MatrixHeadCell => {
+      if (hd.type === 'pass')
+        return {
+          id: `${hd.box.id}|${hd.pass}`,
+          label: passLabel(hd.pass),
+          tip: hd.box.id === box.id ? loopAt(hd.box) : msg(str`Nested loop at ${where(hd.box.loop, hd.box.file)}`),
+          span: hd.span,
+          rows: hd.rows,
+          type: 'group',
+        };
+      if (hd.type === 'loop')
+        return { id: hd.box.id, label: loopLabel(), tip: msg(str`Nested loop at ${where(hd.box.loop, hd.box.file)}`), code: true, span: hd.span, rows: hd.rows, type: 'group' };
+      const n = hd.node;
+      const flow = n.type === 'flow';
+      return {
+        id: `${n.id}|${hd.passes.join('.')}`,
+        label: n.label,
+        tip: flow ? msg(str`Function ${n.name}`) : facts(n.label, executorWord(n)),
+        summary: flow ? n.label : facts(n.label, executorWord(n)),
+        icons: n.executor && n.executor !== 'mixed' ? [n.executor] : [],
+        span: hd.span,
+        rows: hd.rows,
+        type: 'column',
+      };
+    }),
+  );
+  return {
+    caption,
+    ...(box.file ? { captionTip: `${box.file}:${box.loop}` } : {}),
+    label: facts(caption, passCount(box.passes)),
+    facts: [passCount(box.passes), box.spread.length > 1 ? passSpread(box.spread) : '', units === 1 ? msg('1 unit') : msg(str`${units} units`)].filter(Boolean),
+    head,
+    columns: mx.columns.map((c) => ({ id: `${c.node.id}|${c.passes.join('.')}`, groups: c.passes.map((_, k) => c.passes.slice(0, k + 1).join('.')) })),
+    rows: sortRows(mx.rows, sort).map((r) => ({
+      id: r.unit,
+      label: r.unit || msg('No unit'),
+      tip: r.unit || msg('Tasks that run once per run, not once per unit'),
+      muted: !r.unit,
+      value: r.passes,
+      strong: r.passes > 1,
+      cells: r.cells.map((mk, ci) => mk && cell(ci, mk)),
+    })),
+    value: { label: msg('Passes'), tip: msg('Passes of this loop') },
+    sorts: matrixSorts(),
+    sort,
+  };
+}
+
+/** The loop box `box` of layer `path` with its passes unrolled (`passMatrix`), as the generic mark matrix takes it; null when the layer has no such box. */
+export function matrixFromPlan(
+  plan: Plan,
+  path: readonly string[],
+  box: string,
+  prev: GraphOrder | undefined,
+  sort: MatrixSort,
+  x: Omit<GraphWordsContext, 'plan'>,
+  proj?: Projection,
+): { input: MarkMatrixInput; matrix: PassMatrix } | null {
+  const matrix = passMatrix(plan, path, box, prev, proj);
+  return matrix && { input: matrixInput(matrix, sort, { ...x, plan }), matrix };
+}

package/src/adapters/graph/layer.ts

@@ -0,0 +1,92 @@
+// The layers of the run's flow: the graph of one, the one the graph opens on, and
+// the layer a view route's segments name.
+import type { Plan } from '@contraagent/api';
+import { arrange, type GraphOrder } from '@contraagent/elements/graph';
+import { indexOf, instanceOf, placeOf, shortName, startsWith, type FlowTask } from './flow-index.js';
+import { arranged, project, shapeOf } from './project.js';
+import { LOOP_SEGMENT, type LayerGraph } from './types.js';
+
+/**
+ * The layer `path` of the plan's flow. Pass the `order` of the last graph of this layer as
+ * `prev` to keep its nodes in place; `down` lays out the edge paths for a drawing top to bottom
+ * (a box's label is then on the side its edges come in).
+ */
+export function layerGraph(plan: Plan, path: readonly string[] = [], prev?: GraphOrder, down = false): LayerGraph {
+  const { model } = project(plan, path);
+  return arranged(model, arrange(shapeOf(model), prev, down));
+}
+
+/**
+ * The layer the graph opens on: from the top, down while a layer has a single
+ * node and it is a function's. It stops at a single function node whose flow call
+ * raised or was closed, so a run that failed inside a flow opens on the node that
+ * shows it, not inside it. A failed or not started task does not stop it: the layer
+ * below shows that task's own mark. A static flow lands on its kinds.
+ */
+export function autoLayer(plan: Plan): string[] {
+  const ix = indexOf(plan);
+  const path: string[] = [];
+  // The failure sites: flow calls that raised or were closed with no raised descendant.
+  // The graph stops on the node that shows one, not inside it. A plan with no flow calls
+  // cannot tell its failure sites, so it descends as if there were none.
+  const raised = new Set<string>();
+  if (ix.calls) for (const c of ix.calls.values()) if (c.state === 'raised' || c.state === 'closed') raised.add(c.id);
+  const isSite = (id: string): boolean => raised.has(id) && ![...raised].some((r) => r !== id && r.startsWith(`${id}.`));
+  for (;;) {
+    let only: { id: string; name: string } | null = null;
+    let one = true;
+    const mine: FlowTask[] = [];
+    for (const t of ix.tasks) {
+      if (!startsWith(t.path, path)) continue;
+      const p = placeOf(t, path.length);
+      if (p.type === 'kind' || (only && only.id !== p.id)) {
+        one = false;
+        break;
+      }
+      only = p;
+      mine.push(t);
+    }
+    // Stop before entering a single function node that is itself a failure site.
+    const atSite = mine.some((t) => isSite(instanceOf(t, path.length, ix.calls).id));
+    if (!one || !only || atSite) return path;
+    path.push(only.name);
+  }
+}
+
+/** A layer's segments: its path, and the loop box entered at its end (null when none). */
+export function splitLayer(segments: readonly string[]): { path: string[]; loop: string | null } {
+  const last = segments[segments.length - 1];
+  return last?.startsWith(LOOP_SEGMENT) ? { path: segments.slice(0, -1), loop: last } : { path: [...segments], loop: null };
+}
+
+/**
+ * The layer `segments` names, as the plan has it: the segments themselves when the
+ * plan has that layer (a prefix of a task's flow path, and the loop box after it);
+ * else, when the last function is named by its `module.qualname` (or, failing that,
+ * its name) and the plan reaches it by one flow path only, that flow path, with the
+ * loop box when the layer there has it. Null when the plan has no such layer.
+ */
+export function resolveLayer(plan: Plan, segments: readonly string[]): string[] | null {
+  const { path, loop } = splitLayer(segments);
+  const ix = indexOf(plan);
+  const hasLoop = (p: readonly string[]) => !loop || project(plan, p).model.boxes.some((b) => b.id === loop);
+  if (ix.tasks.some((t) => startsWith(t.path, path))) return hasLoop(path) ? [...segments] : null;
+  const name = path[path.length - 1];
+  if (name === undefined) return null;
+  const found = (match: (fn: string) => boolean): string[][] => {
+    const by = new Map<string, string[]>();
+    for (const t of ix.tasks) t.path.forEach((fn, i) => match(fn) && by.set(t.path.slice(0, i + 1).join('/'), t.path.slice(0, i + 1)));
+    return [...by.values()];
+  };
+  const exact = found((fn) => fn === name);
+  const named = exact.length ? exact : found((fn) => shortName(fn) === name);
+  const only = named.length === 1 ? (named[0] as string[]) : null;
+  return only && hasLoop(only) ? (loop ? [...only, loop] : only) : null;
+}
+
+/** One level up from `segments`: null at the top (the layer the graph opens on, `auto`), [] for that layer. */
+export function parentLayer(segments: readonly string[], auto: readonly string[]): string[] | null {
+  if (segments.length <= auto.length) return null;
+  const up = segments.slice(0, -1);
+  return up.length <= auto.length ? [] : up;
+}

package/src/adapters/graph/matrix.ts

@@ -0,0 +1,133 @@
+// A loop's passes: a loop box unrolled into units by (node, pass).
+import type { Plan, TaskState } from '@contraagent/api';
+import { arrange, type GraphOrder } from '@contraagent/elements/graph';
+import { cmpPasses, passesAt, push, type FlowTask } from './flow-index.js';
+import { arranged, flowMarks, project, shapeOf, taskMark, type Draft, type Projection } from './project.js';
+import { SEVERITY, worstOf } from './states.js';
+import { LOOP_SEGMENT, type LayerMark, type GraphNode, type LoopBox } from './types.js';
+
+/** A column of a loop's passes: one node, in one pass of each loop from the unrolled box down to the node's own box. */
+export interface MatrixColumn {
+  node: GraphNode;
+  /** The passes, the unrolled box's loop first. */
+  passes: number[];
+}
+
+/** A header cell over the columns: a pass of a loop, a nested loop, or a node. */
+export type MatrixHead =
+  | { type: 'pass'; box: LoopBox; pass: number; span: number; rows: number }
+  | { type: 'loop'; box: LoopBox; span: number; rows: number }
+  | { type: 'node'; node: GraphNode; passes: number[]; span: number; rows: number };
+
+export interface MatrixRow {
+  /** The unit, or '' for the tasks without one. */
+  unit: string;
+  /** How many passes of the unrolled loop it ran (in every run of the loop). */
+  passes: number;
+  /** The most severe state of its marks. */
+  state: TaskState;
+  /** One per column: its mark, or null where it has none. */
+  cells: (LayerMark | null)[];
+}
+
+/** A loop box with its passes unrolled: a row per unit, a column per (node, pass), nested loops as nested column groups. */
+export interface PassMatrix {
+  box: LoopBox;
+  columns: MatrixColumn[];
+  /** The header rows, outermost first; a node's cell spans down to the last. */
+  head: MatrixHead[][];
+  /** The units that have a task in the box, in the layer's order; the tasks without a unit last. */
+  rows: MatrixRow[];
+}
+
+type ColTree = { type: 'pass'; box: LoopBox; pass: number; kids: ColTree[] } | { type: 'loop'; box: LoopBox; kids: ColTree[] } | { type: 'node'; node: GraphNode; passes: number[] };
+
+/**
+ * The loop box `box` of layer `path` with its passes unrolled; null when the layer has
+ * no such box. Each task is in the column of its node and of its passes of the box's
+ * loop and of every loop nested in it, so an inner loop's passes are counted within
+ * each pass of the outer one. A column no task reached is left out. The columns
+ * follow the order of the layer drawn left to right with `prev` (its graph's order);
+ * `proj` is the layer's projection when the caller has it.
+ */
+export function passMatrix(plan: Plan, path: readonly string[], box: string, prev?: GraphOrder, proj: Projection = project(plan, path)): PassMatrix | null {
+  const { drafts, ix } = proj;
+  const graph = arranged(proj.model, arrange(shapeOf(proj.model), prev, false));
+  const b = graph.boxes.find((x) => x.id === box);
+  if (!b) return null;
+  const d = path.length;
+  const i0 = b.id.slice(LOOP_SEGMENT.length).split('.').length - 1;
+  const byBox = new Map(graph.boxes.map((x) => [x.id, x]));
+  const byNode = new Map(graph.nodes.map((n) => [n.id, n]));
+  const rel = (t: FlowTask) => passesAt(t, d).slice(i0);
+  const leaves = (x: LoopBox): string[] => x.layers.flat().flatMap((id) => (byBox.has(id) ? leaves(byBox.get(id) as LoopBox) : [id]));
+  const tasksOf = (x: LoopBox): FlowTask[] => leaves(x).flatMap((id) => drafts.get(id)?.tasks ?? []);
+  const same = (a: readonly number[], p: readonly number[]) => a.length === p.length && cmpPasses(a, p) === 0;
+  const build = (x: LoopBox, prefix: number[]): ColTree[] => {
+    const k = prefix.length;
+    const passes = [...new Set(tasksOf(x).map(rel).filter((v) => v.length > k && cmpPasses(v.slice(0, k), prefix) === 0).map((v) => v[k] as number))].sort((a, c) => a - c);
+    return passes.flatMap((p): ColTree[] => {
+      const at = [...prefix, p];
+      const kids = x.layers.flat().flatMap((id): ColTree[] => {
+        const inner = byBox.get(id);
+        if (inner) {
+          const sub = build(inner, at);
+          return sub.length ? [{ type: 'loop', box: inner, kids: sub }] : [];
+        }
+        const node = byNode.get(id);
+        return node && drafts.get(id)?.tasks.some((t) => same(rel(t), at)) ? [{ type: 'node', node, passes: at }] : [];
+      });
+      return kids.length ? [{ type: 'pass', box: x, pass: p, kids }] : [];
+    });
+  };
+  const tree = build(b, []);
+  const columns: MatrixColumn[] = [];
+  const width = (t: ColTree): number => (t.type === 'node' ? 1 : t.kids.reduce((a, k) => a + width(k), 0));
+  const depthOf = (t: ColTree): number => (t.type === 'node' ? 1 : 1 + Math.max(0, ...t.kids.map(depthOf)));
+  const rowsN = Math.max(1, ...tree.map(depthOf));
+  const head: MatrixHead[][] = Array.from({ length: rowsN }, () => []);
+  const walk = (t: ColTree, level: number): void => {
+    const row = head[level] as MatrixHead[];
+    if (t.type === 'node') {
+      row.push({ type: 'node', node: t.node, passes: t.passes, span: 1, rows: rowsN - level });
+      columns.push({ node: t.node, passes: t.passes });
+      return;
+    }
+    row.push(t.type === 'pass' ? { type: 'pass', box: t.box, pass: t.pass, span: width(t), rows: 1 } : { type: 'loop', box: t.box, span: width(t), rows: 1 });
+    for (const k of t.kids) walk(k, level + 1);
+  };
+  for (const t of tree) walk(t, 0);
+
+  const mine = tasksOf(b);
+  const unitsIn = new Set(mine.map((t) => t.n.unit || ''));
+  const rowUnits = [...graph.units.filter((u) => unitsIn.has(u)), ...(unitsIn.has('') ? [''] : [])];
+  const cellTasks = new Map<string, FlowTask[]>(); // `${column}\0${unit}`
+  columns.forEach((c, ci) => {
+    for (const t of drafts.get(c.node.id)?.tasks ?? []) if (same(rel(t), c.passes)) push(cellTasks, `${ci}\u0000${t.n.unit || ''}`, t);
+  });
+  const markOf = (c: MatrixColumn, ts: readonly FlowTask[], unit: string): LayerMark | null => {
+    const x = drafts.get(c.node.id) as Draft;
+    if (x.type === 'kind') return taskMark(ts, unit);
+    const m = flowMarks(ts, d, x.name, ix.calls);
+    return unit ? (m.byUnit.get(unit) ?? m.single[0] ?? null) : (m.single[0] ?? null);
+  };
+  const rows = rowUnits.map((unit): MatrixRow => {
+    const cells = columns.map((c, ci) => {
+      const ts = cellTasks.get(`${ci}\u0000${unit}`);
+      return ts?.length ? markOf(c, ts, unit) : null;
+    });
+    const passes = new Set(mine.filter((t) => (t.n.unit || '') === unit).map((t) => passesAt(t, d).slice(0, i0 + 1).join('.'))).size;
+    return { unit, passes, state: worstOf(cells.filter((m): m is LayerMark => m !== null).map((m) => m.state)), cells };
+  });
+  return { box: b, columns, head, rows };
+}
+
+/** How a loop's units are sorted: as scheduled, most passes first, or the most severe state first. */
+export type MatrixSort = 'order' | 'passes' | 'state';
+
+/** `rows` sorted by `by`; a tie keeps the scheduled order. */
+export function sortRows(rows: readonly MatrixRow[], by: MatrixSort): MatrixRow[] {
+  const ix = new Map(rows.map((r, i) => [r, i]));
+  const key = (r: MatrixRow) => (by === 'passes' ? -r.passes : by === 'state' ? -SEVERITY[r.state] : 0);
+  return [...rows].sort((a, b) => key(a) - key(b) || (ix.get(a) ?? 0) - (ix.get(b) ?? 0));
+}

package/src/adapters/graph/plans.fixture.ts

@@ -0,0 +1,194 @@
+// Synthetic plans for the graph's tests, as a run writes them: a task's flow path
+// (outermost first) with the loops around each call site, what its flow call had
+// received when it was created, and its flow call. Test code only: the build leaves
+// `*.fixture.ts` out.
+import type { FlowCallNode, Frame, Plan, PlanNode } from '@contraagent/api';
+
+export const node = (key: string, unit: string, group: string, state: PlanNode['state'], extra: Partial<PlanNode> = {}): PlanNode => ({
+  key, kind: group, unit, group, state, level: 0, ...extra,
+});
+export const group = (id: string, counts: Partial<Plan['groups'][number]> = {}): Plan['groups'][number] => ({
+  id, label: id, total: 0, done: 0, partial: 0, failed: 0, running: 0, pending: 0, skipped: 0, blocked: 0, ...counts,
+});
+
+/** A frame of a flow path, with the loops around its call site (each at pass 1). */
+export const F = (fn: string, ...loops: number[]): Frame => ({ function: fn, file: 'flow.py', line: 1, loops: loops.map((line) => ({ line, pass: 1 })) });
+
+/**
+ * A task created by a flow. `pass` is the pass of the innermost loop around the
+ * task's own call site; `passes`, one pass per loop around it, outermost first.
+ */
+export const ft = (
+  key: string,
+  unit: string,
+  kind: string,
+  state: PlanNode['state'],
+  flow: Frame[],
+  { pass = 1, passes, ...extra }: Partial<PlanNode> & { pass?: number; passes?: number[] } = {},
+): PlanNode => {
+  const last = flow[flow.length - 1];
+  const loops = last?.loops ?? [];
+  const at = (i: number) => passes?.[i] ?? (i === loops.length - 1 ? pass : 1);
+  const own = last && loops.length ? [...flow.slice(0, -1), { ...last, loops: loops.map((l, i) => ({ ...l, pass: at(i) })) }] : flow;
+  return node(key, unit, kind, state, { flow: own, flow_call: '0', created_from: [], ...extra });
+};
+export const planOf = (nodes: PlanNode[], flow_calls?: FlowCallNode[]): Plan => {
+  const groups = [...new Set(nodes.map((n) => n.group))].map((g) => group(g));
+  return flow_calls ? { nodes, groups, flow_calls } : { nodes, groups };
+};
+export const call = (id: string, fn: string, state: FlowCallNode['state'] = 'returned'): FlowCallNode => ({
+  id, parent: id.includes('.') ? id.slice(0, id.lastIndexOf('.')) : null, function: fn, flow: [], state,
+});
+
+export const RUN = 'flows.run_all';
+export const LOOP = 'flows.review_loop';
+export const AT = 7; // the line of review_loop's `while`
+
+/**
+ * run_all: prepare each unit (Python), then review_loop(u) for every unit as one batch,
+ * then report on what they returned. review_loop: summarize, check, and while the review
+ * is not ok: fix, score (Python), check. `passes[u]` is how many times u went round.
+ */
+export function reviewRun(passes: Record<string, number>, opts: { calls?: boolean; failed?: string } = {}): Plan {
+  const nodes: PlanNode[] = [];
+  const top = [F(RUN)];
+  const inLoop = [F(RUN), F(LOOP)];
+  const looped = [F(RUN), F(LOOP, AT)];
+  const finals: string[] = [];
+  const lastChecks: string[] = [];
+  Object.entries(passes).forEach(([u, n], i) => {
+    const c = `0.${i + 1}`;
+    const bad = opts.failed === u;
+    nodes.push(ft(`prepare-${u}`, u, 'prepare', 'done', top, { executor: 'python' }));
+    nodes.push(ft(`summarize-${u}`, u, 'summarize', 'done', inLoop, { flow_call: c, after: [`prepare-${u}`], created_from: [`prepare-${u}`] }));
+    let summary = `summarize-${u}`;
+    let check = `check-${u}`;
+    nodes.push(ft(check, u, 'check', 'done', inLoop, { flow_call: c, after: [summary], created_from: [summary] }));
+    for (let p = 1; p <= n; p++) {
+      const sfx = p === 1 ? '' : `~${p}`;
+      const fix = `fix-${u}${sfx}`;
+      const score = `score-${u}${sfx}`;
+      const last = p === n;
+      nodes.push(ft(fix, u, 'fix', bad && last ? 'failed' : 'done', looped, { flow_call: c, pass: p, after: [summary, check], created_from: [check] }));
+      if (bad && last) break;
+      nodes.push(ft(score, u, 'score', 'done', looped, { flow_call: c, pass: p, executor: 'python', after: [fix], created_from: [fix] }));
+      const next = `check-${u}~${p + 1}`;
+      nodes.push(ft(next, u, 'check', 'done', looped, { flow_call: c, pass: p, after: [fix], created_from: [score] }));
+      summary = fix;
+      check = next;
+    }
+    finals.push(summary);
+    lastChecks.push(check);
+  });
+  const failed = opts.failed !== undefined;
+  if (!failed) nodes.push(ft('report', '', 'report', 'done', top, { after: finals, created_from: lastChecks }));
+  const units = Object.keys(passes);
+  const calls = [call('0', RUN, failed ? 'raised' : 'returned'), ...units.map((u, i) => call(`0.${i + 1}`, LOOP, opts.failed === u ? 'raised' : 'returned'))];
+  return planOf(nodes, opts.calls ? calls : undefined);
+}
+
+export const UNITS = ['alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta'];
+
+/** The demo as a static flow: prepare -> summarize -> { review, write_note }, review -> report (one task, no unit). */
+export function staticDemo(stateOf: (key: string) => PlanNode['state'] = (k) => (k.endsWith('zeta') ? 'blocked' : 'done'), flow?: Frame[]): Plan {
+  const extra = (x: Partial<PlanNode>): Partial<PlanNode> => (flow ? { ...x, flow, flow_call: '0' } : x);
+  const nodes: PlanNode[] = [];
+  for (const u of UNITS) {
+    nodes.push(node(`prepare-${u}`, u, 'prepare', u === 'zeta' ? 'failed' : stateOf(`prepare-${u}`), extra({})));
+    nodes.push(node(`summarize-${u}`, u, 'summarize', stateOf(`summarize-${u}`), extra({ after: [`prepare-${u}`] })));
+    nodes.push(node(`review-${u}`, u, 'review', stateOf(`review-${u}`), extra({ after: [`summarize-${u}`] })));
+    nodes.push(node(`write_note-${u}`, u, 'write_note', stateOf(`write_note-${u}`), extra({ after: [`summarize-${u}`] })));
+  }
+  nodes.push(node('report', '', 'report', 'blocked', extra({ after: UNITS.map((u) => `review-${u}`) })));
+  return { groups: ['prepare', 'summarize', 'review', 'write_note', 'report'].map((g) => group(g)), nodes };
+}
+
+/** scan(u): for each column (the outer `for`, line 30), propose it, then while not ok verify and refine it (the inner `while`, line 33). */
+export const SCAN = 'flows.scan';
+export function nestedLoops(): Plan {
+  const outer = 30;
+  const inner = 33;
+  const at = (loops: number[]) => [F(RUN), F(SCAN, ...loops)];
+  return planOf(
+    [
+      ft('propose-a', 'a', 'propose', 'done', at([outer]), { flow_call: '0.1', passes: [1] }),
+      ft('verify-a', 'a', 'verify', 'done', at([outer, inner]), { flow_call: '0.1', passes: [1, 1], executor: 'python', after: ['propose-a'] }),
+      ft('refine-a', 'a', 'refine', 'done', at([outer, inner]), { flow_call: '0.1', passes: [1, 1], after: ['verify-a'] }),
+      ft('verify-a~2', 'a', 'verify', 'done', at([outer, inner]), { flow_call: '0.1', passes: [1, 2], executor: 'python', after: ['refine-a'] }),
+      ft('propose-a~2', 'a', 'propose', 'done', at([outer]), { flow_call: '0.1', passes: [2] }),
+      ft('verify-a~3', 'a', 'verify', 'failed', at([outer, inner]), { flow_call: '0.1', passes: [2, 1], executor: 'python', after: ['propose-a~2'] }),
+      ft('propose-b', 'b', 'propose', 'done', at([outer]), { flow_call: '0.2', passes: [1] }),
+      ft('verify-b', 'b', 'verify', 'done', at([outer, inner]), { flow_call: '0.2', passes: [1, 1], executor: 'python', after: ['propose-b'] }),
+    ],
+    [call('0', RUN), call('0.1', SCAN), call('0.2', SCAN)],
+  );
+}
+
+/** Plans of every shape the graph draws, by name: the input of the graph's order snapshot. */
+export function shapes(): Record<string, Plan> {
+  const L = [F(RUN), F(LOOP, AT)];
+  const inRL = [F(RUN), F(LOOP)];
+  const REFINE = 'flows.refine';
+  const POLISH = 'flows.polish';
+  const deep = [
+    ft('draft-a', 'a', 'draft', 'done', [F(RUN), F(LOOP), F(REFINE)], { flow_call: '0.1' }),
+    ft('tune-a', 'a', 'tune', 'running', [F(RUN), F(LOOP), F(REFINE), F(POLISH)], { flow_call: '0.1.1', after: ['draft-a'] }),
+    ft('report', '', 'report', 'pending', [F(RUN)], { after: ['tune-a'] }),
+  ];
+  const at = (loops: number[]) => [F(RUN), F(SCAN, ...loops)];
+  return {
+    'static demo': staticDemo(),
+    'static demo, running': staticDemo((k) => (k.startsWith('review') ? 'running' : 'pending')),
+    'static demo under one function': staticDemo(undefined, [F('flows.pipeline')]),
+    'cycle and waits inside a node': planOf([
+      node('a1', 'u', 'a', 'done'),
+      node('a2', 'v', 'a', 'done', { after: ['a1', 'not-yet'] }),
+      node('b1', 'u', 'b', 'done', { after: ['c1'] }),
+      node('c1', 'u', 'c', 'done', { after: ['b1'] }),
+    ]),
+    'long edge': planOf([node('a-u', 'u', 'a', 'done'), node('b-u', 'u', 'b', 'done', { after: ['a-u'] }), node('c-u', 'u', 'c', 'done', { after: ['b-u'] }), node('d-u', 'u', 'd', 'done', { after: ['c-u', 'a-u'] })]),
+    crossing: planOf([
+      node('x1-u', 'u', 'x1', 'done'), node('x2-u', 'u', 'x2', 'done'),
+      node('y1-u', 'u', 'y1', 'done', { after: ['x2-u'] }), node('y2-u', 'u', 'y2', 'done', { after: ['x1-u'] }),
+    ]),
+    'review loop, calls': reviewRun({ a: 0, b: 1 }, { calls: true }),
+    'review loop, 2 passes': reviewRun({ a: 1, b: 2 }),
+    'review loop, spread': reviewRun({ a: 1, b: 3, c: 0, d: 1, e: 2 }),
+    'review loop, failed': reviewRun({ a: 1, b: 3, c: 0, d: 2 }, { failed: 'd' }),
+    'review loop, calls, failed': reviewRun({ a: 0, b: 1, c: 2 }, { calls: true, failed: 'c' }),
+    branch: planOf([
+      ft('check-a', 'a', 'check', 'done', inRL, { flow_call: '0.1' }),
+      ft('check-b', 'b', 'check', 'done', inRL, { flow_call: '0.2' }),
+      ft('publish-a', 'a', 'publish', 'done', inRL, { flow_call: '0.1', created_from: ['check-a'] }),
+      ft('escalate-b', 'b', 'escalate', 'running', inRL, { flow_call: '0.2', created_from: ['check-b'] }),
+    ]),
+    'fan-out': planOf(
+      [
+        ft('part-a/1', 'a/1', 'part', 'done', inRL, { flow_call: '0.1' }),
+        ft('part-a/2', 'a/2', 'part', 'failed', inRL, { flow_call: '0.1' }),
+        ft('part-b/1', 'b/1', 'part', 'done', inRL, { flow_call: '0.2' }),
+        ft('part-b/2', 'b/2', 'part', 'done', inRL, { flow_call: '0.2' }),
+        ft('merge', '', 'merge', 'blocked', [F(RUN)], { after: ['part-a/1', 'part-a/2', 'part-b/1', 'part-b/2'] }),
+      ],
+      [call('0', RUN, 'running'), call('0.1', LOOP, 'raised'), call('0.2', LOOP)],
+    ),
+    'deep, calls': planOf(deep, [call('0', RUN, 'running'), call('0.1', LOOP, 'running'), call('0.1.1', POLISH, 'running')]),
+    'deep, no calls': planOf(deep),
+    'nested loops': nestedLoops(),
+    'nested boxes': planOf([
+      ft('rank-a', 'a', 'rank', 'done', at([])),
+      ft('propose-a', 'a', 'propose', 'done', at([30]), { created_from: ['rank-a'] }),
+      ft('verify-a', 'a', 'verify', 'done', at([30, 33]), { after: ['propose-a'] }),
+      ft('refine-a', 'a', 'refine', 'done', at([30, 33]), { after: ['verify-a', 'propose-a'] }),
+      ft('report-a', 'a', 'report', 'done', at([]), { after: ['refine-a'] }),
+    ]),
+    'into and out of a box': planOf([
+      ft('s-u', 'u', 's', 'done', inRL),
+      ft('a-u', 'u', 'a', 'done', L, { after: ['s-u'] }),
+      ft('b-u', 'u', 'b', 'done', L, { after: ['a-u'] }),
+      ft('c-u', 'u', 'c', 'done', L, { after: ['b-u', 's-u'] }),
+      ft('w-u', 'u', 'w', 'done', inRL, { after: ['b-u', 's-u', 'c-u'] }),
+    ]),
+    'loop of one layer': planOf([ft('a-u', 'u', 'a', 'done', L), ft('a-u~2', 'u', 'a', 'done', L, { pass: 2 })]),
+  };
+}