feat(projection): derived sequence fragments, message elements and view inverses

README.md

@@ -49,7 +49,7 @@ Configuration lives at exactly one of two levels: in the package (`eslint.config
 | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`graph-dag`](packages/core/graph/dag/README.md)                                       | Model-independent dependency-graph primitives over a node set and a `needs` accessor: layers, ancestors, descendants, cycles, transitive reduction, critical path.                                                                                |
 | [`graph-schema`](packages/core/graph/schema/README.md)                                 | The process model: typed identifier spaces, `defineModel` with compile-time reference checking, structural validation.                                                                                                                            |
-| [`graph-projection`](packages/core/graph/projection/README.md)                         | Projections of the model into a flowchart, swimlane, state machine and sequence diagram, plus derived hand-offs.                                                                                                                                  |
+| [`graph-projection`](packages/core/graph/projection/README.md)                         | Projections of the model into a flowchart, swimlane, state machine and sequence diagram, plus derived hand-offs, and the inverses that turn an edited view into a diff against the model.                                                         |
 | [`graph-domain`](packages/core/graph/domain/README.md)                                 | Reasoning over the model and a run overlay: control graph, illegal cycles, three-valued status, ready set, blocked-by, impact, what-if and critical path.                                                                                         |
 | [`graph-layout`](packages/core/graph/layout/README.md)                                 | Layered layout of a projected flowchart, swimlane or state machine into positions in the model's `views` shape.                                                                                                                                   |
 | [`graph-source-contract`](packages/core/graph/source-contract/README.md)               | The `GraphSource` port as an oRPC contract: versioned, paged and streamed sync of bound activities, participants, transitions and run state, resumable by cursor, with an in-memory fake and a conformance kit.                                   |

packages/core/graph/dag/README.md

@@ -40,15 +40,17 @@ Nothing is absorbed silently:
 
 ## API
 
-| Function                    | Returns                                                          | With a cycle                                                                          |
-| --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `buildDag(nodes, needs)`    | An immutable `Dag`: nodes, needs, dependents, unknown references | Builds normally.                                                                      |
-| `topologicalLayers(dag)`    | `levels`, `layers`, `unlayered`                                  | Layers the acyclic part; nodes on a cycle or needing one are returned in `unlayered`. |
-| `ancestorsOf(dag, id)`      | Transitive needs, in node order                                  | Includes `id` itself when it is on a cycle.                                           |
-| `descendantsOf(dag, id)`    | Transitive dependents, in node order                             | Includes `id` itself when it is on a cycle.                                           |
-| `findCycles(dag)`           | One closed path per cyclic strongly connected component          | Not applicable; this is the report.                                                   |
-| `transitiveReduction(dag)`  | A `Dag` without redundant edges                                  | Throws `CycleError`: with a cycle the reduction is not unique.                        |
-| `criticalPath(dag, weight)` | `{ path, weight }`, the heaviest chain                           | Throws `CycleError`: a chain through a cycle has no greatest weight.                  |
+| Function                           | Returns                                                                                             | With a cycle                                                                           |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `buildDag(nodes, needs)`           | An immutable `Dag`: nodes, needs, dependents, unknown references                                    | Builds normally.                                                                       |
+| `topologicalLayers(dag)`           | `levels`, `layers`, `unlayered`                                                                     | Layers the acyclic part; nodes on a cycle or needing one are returned in `unlayered`.  |
+| `ancestorsOf(dag, id)`             | Transitive needs, in node order                                                                     | Includes `id` itself when it is on a cycle.                                            |
+| `descendantsOf(dag, id)`           | Transitive dependents, in node order                                                                | Includes `id` itself when it is on a cycle.                                            |
+| `findCycles(dag)`                  | One closed path per cyclic strongly connected component                                             | Not applicable; this is the report.                                                    |
+| `stronglyConnectedComponents(dag)` | Every strongly connected component, each node in exactly one, a component before those that need it | Not applicable; a cycle is a component of several nodes or of one node needing itself. |
+| `immediateDominators(dag, root)`   | Each node reachable from `root` along `needs` mapped to its immediate dominator                     | Allowed; dominance is defined on any graph.                                            |
+| `transitiveReduction(dag)`         | A `Dag` without redundant edges                                                                     | Throws `CycleError`: with a cycle the reduction is not unique.                         |
+| `criticalPath(dag, weight)`        | `{ path, weight }`, the heaviest chain                                                              | Throws `CycleError`: a chain through a cycle has no greatest weight.                   |
 
 `ancestorsOf` and `descendantsOf` throw `UnknownNodeError` for an id that is not a node. `criticalPath` throws `RangeError` for a negative or non-finite weight.
 

packages/core/graph/dag/src/cycles.ts

@@ -7,9 +7,13 @@ interface TarjanFrame<Id extends NodeId> {
 }
 
 /**
- * Every strongly connected component of the graph, found with an explicit stack so depth is bounded by memory, not by the call stack.
+ * Every strongly connected component of the graph: the maximal sets of nodes in which each node reaches every other along `needs` edges. Every node is in exactly one component, and a node on no cycle is a component of its own. Found by Tarjan's algorithm with an explicit stack, so depth is bounded by memory, not by the call stack, and each node and edge is visited once.
+ *
+ * A component lists its nodes in the order Tarjan's algorithm completes them, its root last. Components come out in reverse topological order of the condensed graph along `needs`: a component appears before every component that needs it. Since mutual reachability is symmetric, the components are the same whichever direction the edges are read in.
+ * @param dag - The graph to partition.
+ * @returns Every component, each a non-empty list of nodes.
  */
-function stronglyConnectedComponents<Id extends NodeId>(
+export function stronglyConnectedComponents<Id extends NodeId>(
   dag: Dag<Id>,
 ): readonly (readonly Id[])[] {
   const index = new Map<Id, number>();

packages/core/graph/dag/src/cycles.unit.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it } from "vitest";
-import { assertAcyclic, findCycles } from "./cycles.ts";
+import {
+  assertAcyclic,
+  findCycles,
+  stronglyConnectedComponents,
+} from "./cycles.ts";
 import { CycleError } from "./errors.ts";
 import { dagOf } from "./test-support/dag-of.ts";
 
@@ -130,3 +134,34 @@ describe("assertAcyclic", () => {
     ]);
   });
 });
+
+describe("stronglyConnectedComponents", () => {
+  it("puts every node in exactly one component, mutually reachable nodes together", () => {
+    const components = stronglyConnectedComponents(
+      dagOf({ p: ["q"], q: ["p"], m: [], r: ["s"], s: ["r", "t"], t: ["t"] }),
+    );
+
+    const sorted = components
+      .map((component) => component.toSorted((a, b) => a.localeCompare(b)))
+      .toSorted((a, b) => a.join().localeCompare(b.join()));
+
+    expect(sorted).toEqual([["m"], ["p", "q"], ["r", "s"], ["t"]]);
+  });
+
+  it("lists a component before every component that needs it", () => {
+    expect(
+      stronglyConnectedComponents(dagOf({ a: [], b: ["a"], c: ["b"] })),
+    ).toEqual([["a"], ["b"], ["c"]]);
+  });
+
+  it("partitions a ring deeper than any call stack without recursing", () => {
+    const ring = Object.fromEntries(
+      Array.from({ length: deepRingLength }, (_, index) => [
+        `n${String(index)}`,
+        [`n${String((index + 1) % deepRingLength)}`],
+      ]),
+    );
+
+    expect(stronglyConnectedComponents(dagOf(ring))).toHaveLength(1);
+  });
+});

packages/core/graph/dag/src/dominators.ts

@@ -0,0 +1,114 @@
+import { type Dag, type NodeId, lookup } from "./dag.ts";
+
+/**
+ * The immediate dominator of every node reachable from `root` along `needs` edges. A node `d` dominates `n` when every path from `root` to `n` passes through `d`; the immediate dominator is the dominator closest to `n` other than `n` itself. Read with `needs` edges pointing from a step to the steps before it and `root` a virtual end every last step needs, this gives post-dominators: where every way forward from a step meets again.
+ *
+ * Found by the Lengauer-Tarjan algorithm with path compression, so the work is the number of reachable nodes and edges times a slowly growing factor, and every walk uses an explicit stack, so depth is bounded by memory, not the call stack. Cycles are allowed.
+ * @param dag - The graph to read.
+ * @param root - Where every path starts.
+ * @returns Each node reachable from `root` other than `root`, mapped to its immediate dominator, in the order a depth-first walk from `root` first reaches the nodes. A node `root` does not reach has no entry.
+ * @throws UnknownNodeError when `root` is not a node of `dag`.
+ */
+export function immediateDominators<Id extends NodeId>(
+  dag: Dag<Id>,
+  root: Id,
+): ReadonlyMap<Id, Id> {
+  lookup(dag.needs, root);
+
+  // Depth-first numbering from the root: `order[i]` is the node numbered i, and `parent[i]` the number of the node it was reached from.
+  const number = new Map<Id, number>();
+  const order: Id[] = [];
+  const parent: number[] = [];
+  const frames: { readonly node: Id; next: number }[] = [];
+  const enter = (node: Id, from: number): void => {
+    number.set(node, order.length);
+    order.push(node);
+    parent.push(from);
+    frames.push({ node, next: 0 });
+  };
+  enter(root, -1);
+  for (let frame = frames.at(-1); frame !== undefined; frame = frames.at(-1)) {
+    const target = lookup(dag.needs, frame.node)[frame.next];
+    if (target === undefined) {
+      frames.pop();
+      continue;
+    }
+    frame.next += 1;
+    if (!number.has(target)) {
+      enter(target, lookup(number, frame.node));
+    }
+  }
+
+  // Predecessors of each numbered node among the numbered nodes, by number.
+  const predecessors: number[][] = order.map(() => []);
+  for (const [index, node] of order.entries()) {
+    for (const target of lookup(dag.needs, node)) {
+      predecessors[lookup(number, target)]?.push(index);
+    }
+  }
+
+  const semi = order.map((_, index) => index);
+  const idom = order.map(() => 0);
+  const ancestor = order.map(() => -1);
+  const label = order.map((_, index) => index);
+  const bucket: number[][] = order.map(() => []);
+
+  /** Path compression up the forest built by `link`, done with an explicit stack. */
+  const compress = (start: number): void => {
+    const path: number[] = [];
+    for (
+      let node = start;
+      (ancestor[ancestor[node] ?? -1] ?? -1) !== -1;
+      node = ancestor[node] ?? -1
+    ) {
+      path.push(node);
+    }
+    for (const node of path.toReversed()) {
+      const up = ancestor[node] ?? -1;
+      const upLabel = label[up] ?? up;
+      if ((semi[upLabel] ?? 0) < (semi[label[node] ?? node] ?? 0)) {
+        label[node] = upLabel;
+      }
+      ancestor[node] = ancestor[up] ?? -1;
+    }
+  };
+  /** The node with the least semidominator on the forest path to `node`. */
+  const evaluate = (node: number): number => {
+    if (ancestor[node] === -1) {
+      return node;
+    }
+    compress(node);
+
+    return label[node] ?? node;
+  };
+
+  for (let index = order.length - 1; index > 0; index -= 1) {
+    for (const from of predecessors[index] ?? []) {
+      const least = semi[evaluate(from)] ?? index;
+      if (least < (semi[index] ?? index)) {
+        semi[index] = least;
+      }
+    }
+    bucket[semi[index] ?? index]?.push(index);
+    const up = parent[index] ?? 0;
+    ancestor[index] = up;
+    for (const waiting of bucket[up] ?? []) {
+      const least = evaluate(waiting);
+      idom[waiting] = (semi[least] ?? 0) < (semi[waiting] ?? 0) ? least : up;
+    }
+    bucket[up] = [];
+  }
+  const dominators = new Map<Id, Id>();
+  for (let index = 1; index < order.length; index += 1) {
+    if (idom[index] !== semi[index]) {
+      idom[index] = idom[idom[index] ?? 0] ?? 0;
+    }
+    const node = order[index];
+    const dominator = order[idom[index] ?? 0];
+    if (node !== undefined && dominator !== undefined) {
+      dominators.set(node, dominator);
+    }
+  }
+
+  return dominators;
+}

packages/core/graph/dag/src/dominators.unit.test.ts

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import { type Dag, lookup } from "./dag.ts";
+import { immediateDominators } from "./dominators.ts";
+import { dagOf } from "./test-support/dag-of.ts";
+
+/** Far deeper than any call stack tolerates in a recursive walk, so an accidental recursion fails here. */
+const deepChainLength = 100_000;
+/** Enough small random graphs to meet diamonds, loops, irreducible cycles and unreachable nodes. */
+const randomGraphs = 300;
+/** Nodes per random graph: small enough that the reference's set intersections stay cheap. */
+const randomNodes = 9;
+/** Edges per node, on average, in a random graph: dense enough for several paths between most nodes. */
+const randomDensity = 2;
+
+/**
+ * The reference: every node's dominators as a set, by the textbook fixed point (a node's dominators are itself plus the intersection of its predecessors'), then the immediate dominator as the strict dominator that every other strict dominator dominates.
+ */
+const referenceDominators = (
+  dag: Dag<string>,
+  root: string,
+): ReadonlyMap<string, string> => {
+  const reachable = new Set<string>([root]);
+  const stack = [root];
+  for (let next = stack.pop(); next !== undefined; next = stack.pop()) {
+    for (const target of lookup(dag.needs, next)) {
+      if (!reachable.has(target)) {
+        reachable.add(target);
+        stack.push(target);
+      }
+    }
+  }
+  const nodes = dag.nodes.filter((node) => reachable.has(node));
+  const predecessors = new Map<string, string[]>(
+    nodes.map((node) => [node, []]),
+  );
+  for (const node of nodes) {
+    for (const target of lookup(dag.needs, node)) {
+      lookup(predecessors, target).push(node);
+    }
+  }
+  const dominators = new Map<string, Set<string>>(
+    nodes.map((node) => [
+      node,
+      node === root ? new Set([root]) : new Set(nodes),
+    ]),
+  );
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const node of nodes) {
+      if (node === root) {
+        continue;
+      }
+      const sets = lookup(predecessors, node).map((from) =>
+        lookup(dominators, from),
+      );
+      const next = new Set<string>([
+        node,
+        ...[...(sets[0] ?? [])].filter((candidate) =>
+          sets.every((set) => set.has(candidate)),
+        ),
+      ]);
+      if (next.size !== lookup(dominators, node).size) {
+        dominators.set(node, next);
+        changed = true;
+      }
+    }
+  }
+  const immediate = new Map<string, string>();
+  for (const node of nodes) {
+    const strict = [...lookup(dominators, node)].filter(
+      (other) => other !== node,
+    );
+    const closest = strict.find((candidate) =>
+      strict.every((other) => lookup(dominators, candidate).has(other)),
+    );
+    if (closest !== undefined) {
+      immediate.set(node, closest);
+    }
+  }
+
+  return immediate;
+};
+
+/** The multiplier, increment and modulus of the ANSI C linear congruential generator, a well-known full-period choice. */
+const lcgMultiplier = 1_103_515_245;
+const lcgIncrement = 12_345;
+const lcgModulus = 2_147_483_648;
+
+/** A deterministic sequence of pseudo-random integers below `bound`, so a failing graph can be rebuilt. */
+const sequence = (seed: number): ((bound: number) => number) => {
+  let state = seed;
+
+  return (bound) => {
+    state = (state * lcgMultiplier + lcgIncrement) % lcgModulus;
+
+    return state % bound;
+  };
+};
+
+const randomGraph = (seed: number): Dag<string> => {
+  const next = sequence(seed);
+  const names = Array.from(
+    { length: randomNodes },
+    (_, index) => `n${String(index)}`,
+  );
+  const table: Record<string, string[]> = Object.fromEntries(
+    names.map((name) => [name, []]),
+  );
+  for (let edge = 0; edge < randomNodes * randomDensity; edge += 1) {
+    const from = names[next(randomNodes)];
+    const to = names[next(randomNodes)];
+    if (from !== undefined && to !== undefined) {
+      table[from]?.push(to);
+    }
+  }
+
+  return dagOf(table);
+};
+
+describe("immediateDominators", () => {
+  it("finds where both sides of a diamond meet", () => {
+    expect(
+      immediateDominators(
+        dagOf({
+          start: ["left", "right"],
+          left: ["join"],
+          right: ["join"],
+          join: [],
+        }),
+        "start",
+      ),
+    ).toEqual(
+      new Map([
+        ["left", "start"],
+        ["join", "start"],
+        ["right", "start"],
+      ]),
+    );
+  });
+
+  it("dominates a loop's body by its entry and leaves unreachable nodes out", () => {
+    expect(
+      immediateDominators(
+        dagOf({ a: ["b"], b: ["c", "d"], c: ["b"], d: [], orphan: ["a"] }),
+        "a",
+      ),
+    ).toEqual(
+      new Map([
+        ["b", "a"],
+        ["c", "b"],
+        ["d", "b"],
+      ]),
+    );
+  });
+
+  it("agrees with the textbook fixed point on many random graphs", () => {
+    for (let seed = 1; seed <= randomGraphs; seed += 1) {
+      const graph = randomGraph(seed);
+
+      expect(immediateDominators(graph, "n0")).toEqual(
+        referenceDominators(graph, "n0"),
+      );
+    }
+  });
+
+  it("walks a chain deeper than any call stack without recursing", () => {
+    const table = Object.fromEntries(
+      Array.from({ length: deepChainLength }, (_, index) => [
+        `n${String(index)}`,
+        index + 1 < deepChainLength ? [`n${String(index + 1)}`] : [],
+      ]),
+    );
+    const dominators = immediateDominators(dagOf(table), "n0");
+
+    expect(dominators.get(`n${String(deepChainLength - 1)}`)).toBe(
+      `n${String(deepChainLength - 2)}`,
+    );
+  });
+});