@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/tsabre/graph.ts

@@ -0,0 +1,808 @@
+import { assert } from "../assert.ts";
+import {
+  type Edge,
+  EdgeDirectionAlongSegment,
+  type GraphViolation,
+  GraphViolationType,
+  type NodeId,
+  type Segment,
+  type SegmentId,
+  type SmartGraph,
+} from "../types.ts";
+
+/**
+ * @desc Error to throw when a cycle is found setting a parent.
+ */
+export const CYCLE_SETTING_PARENT = "Setting parent that will cause a cycle";
+
+/**
+ * ID for the root node. Implicitly present in _all_ graphs, used internally as
+ * a sigil and never returned to users.
+ */
+export const GRAPH_ROOT = "⌀"; // \u2300
+
+/** Delimiter between parts of an edge's id. */
+export const EDGE_KEY_DELIM = "→"; // \u2192
+const DEFAULT_EDGE_NAME = "⌑"; // \u2311
+const SEGMENT_DELIM = "~";
+
+type EdgeId = string;
+
+// Safer set of constants, but less fun.
+// const GRAPH_NODE = '\x00';
+// const EDGE_KEY_DELIM = '\x01';
+// const DEFAULT_EDGE_NAME = '\x00';
+
+/**
+ * A class to manage a directed graph.
+ */
+export class TsabreGraph<NodeValue = {}, EdgeValue = {}>
+  implements SmartGraph<NodeValue, EdgeValue>
+{
+  get violations(): ReadonlyArray<GraphViolation> {
+    return [...this.graphViolations];
+  }
+
+  get nodeCount(): number {
+    return this.nodesMap.size;
+  }
+
+  get edgeCount(): number {
+    return this.edgeMap.size;
+  }
+
+  get segmentCount(): number {
+    return this.allSegments.size;
+  }
+
+  private readonly graphViolations: GraphViolation[] = [];
+
+  private readonly nodesMap = new Map<NodeId, NodeValue>();
+  private readonly parentMap = new Map<NodeId, NodeId>();
+  private readonly childrenMap = new Map<NodeId, Set<NodeId>>();
+  readonly leaves = new Set<NodeId>();
+  private readonly predMap = new Map<NodeId, Map<NodeId, number>>();
+  private readonly sucsMap = new Map<NodeId, Map<NodeId, number>>();
+  private readonly inMap = new Map<NodeId, Map<EdgeId, Edge>>();
+  private readonly outMap = new Map<NodeId, Map<EdgeId, Edge>>();
+  private readonly edgeMap = new Map<EdgeId, Edge>();
+  private readonly edgeLabelMap = new Map<EdgeId, EdgeValue>();
+  readonly allSegments = new Set<Segment<EdgeValue>>();
+
+  private readonly trackSegments: boolean;
+  private readonly edgeSegmentsMap = new Map<EdgeId, Set<Segment<EdgeValue>>>();
+  private readonly nodeSegmentsMap = new Map<NodeId, Set<Segment<EdgeValue>>>();
+  private readonly childSegmentsMap = new Map<NodeId, Set<Segment<EdgeValue>>>();
+  // Map from sourceid :: targetid :: path :: segment
+  private readonly pathSegmentsMap = new Map<
+    NodeId,
+    Map<NodeId, Map<string, Segment<EdgeValue>>>
+  >();
+
+  get nodes(): Set<NodeId> {
+    return new Set(this.nodesMap.keys());
+  }
+
+  get allNodes(): Iterable<NodeValue> {
+    return this.nodesMap.values();
+  }
+
+  constructor({ trackSegments = true }: { trackSegments?: boolean } = {}) {
+    this.trackSegments = trackSegments;
+  }
+
+  node(id?: NodeId): NodeValue | undefined {
+    return id ? this.nodesMap.get(id) : undefined;
+  }
+
+  hasNode(id?: NodeId): boolean {
+    return id ? this.nodesMap.has(id) : false;
+  }
+
+  setNode(id: NodeId, value: NodeValue): this {
+    if (this.nodesMap.has(id)) {
+      this.nodesMap.set(id, value);
+    } else {
+      this.nodesMap.set(id, value);
+      this.parentMap.set(id, GRAPH_ROOT);
+      this.childrenMap.set(id, new Set<NodeId>());
+      this.children(GRAPH_ROOT).add(id);
+      this.leaves.add(id);
+    }
+    return this;
+  }
+
+  removeNode(id: NodeId): this {
+    if (!this.hasNode(id)) {
+      return this.addViolation({
+        violation: GraphViolationType.REMOVE_NODE_VIOLATION,
+        node: id,
+      });
+    }
+
+    const pid = this.parent(id);
+    this.children(pid).delete(id);
+    this.parentMap.delete(id);
+    for (const child of this.children(id)) {
+      this.setParent(child, pid);
+    }
+    this.childrenMap.delete(id);
+    this.leaves.delete(id);
+
+    if (this.inMap.has(id)) {
+      for (const edge of this.inMap.get(id)!.values()) {
+        this.removeEdge(edge);
+      }
+    }
+
+    if (this.outMap.has(id)) {
+      for (const edge of this.outMap.get(id)!.values()) {
+        this.removeEdge(edge);
+      }
+    }
+    this.inMap.delete(id);
+    this.outMap.delete(id);
+    this.predMap.delete(id);
+    this.sucsMap.delete(id);
+    this.nodesMap.delete(id);
+
+    return this;
+  }
+
+  get allEdges(): Iterable<EdgeValue> {
+    return this.edgeLabelMap.values();
+  }
+
+  edges(id?: NodeId, neighbor?: NodeId): Iterable<Edge> {
+    if (id) {
+      return [...this.inEdges(id, neighbor), ...this.outEdges(id, neighbor)];
+    } else {
+      return this.edgeMap.values();
+    }
+  }
+
+  inEdges(id: NodeId, source?: NodeId): Iterable<Edge> {
+    const ins = this.inMap.get(id) || new Map<EdgeId, Edge>();
+    let edges = Array.from(ins.values());
+    if (source !== undefined) {
+      edges = edges.filter((e) => e.source === source);
+    }
+    return edges;
+  }
+
+  outEdges(id: NodeId, target?: NodeId): Iterable<Edge> {
+    const outs = this.outMap.get(id) || new Map<EdgeId, Edge>();
+    let edges = Array.from(outs.values());
+    if (target !== undefined) {
+      edges = edges.filter((e) => e.target === target);
+    }
+    return edges;
+  }
+
+  private edgeIds(id: NodeId): Iterable<Edge> {
+    const outs = this.outMap.get(id) || new Map<EdgeId, Edge>();
+    const ins = this.inMap.get(id) || new Map<EdgeId, Edge>();
+
+    const edgeIds = new Set<Edge>();
+    for (const edge of outs.values()) edgeIds.add(edge);
+    for (const edge of ins.values()) edgeIds.add(edge);
+    return edgeIds;
+  }
+
+  edge(e: Edge): EdgeValue | undefined {
+    const id = edgeId(e);
+    return this.edgeLabelMap.get(id);
+  }
+
+  hasEdge(e: Edge): boolean {
+    const id = edgeId(e);
+    return this.edgeLabelMap.has(id);
+  }
+
+  setEdge(e: Edge, value: EdgeValue): this {
+    if (!this.hasNode(e.source) || !this.hasNode(e.target)) {
+      return this.addViolation({
+        violation: GraphViolationType.EDGE_VIOLATION,
+        source: e.source,
+        target: e.target,
+        name: e.name,
+      });
+    }
+
+    const id = edgeId(e);
+    if (this.edgeLabelMap.has(id)) {
+      this.edgeLabelMap.set(id, value);
+      return this;
+    }
+
+    this.edgeLabelMap.set(id, value);
+
+    this.edgeMap.set(id, e);
+    incEntry(this.preds(e.target), e.source);
+    incEntry(this.sucs(e.source), e.target);
+    this.in(e.target).set(id, e);
+    this.out(e.source).set(id, e);
+
+    this.updateSegmentsForEdge(e);
+
+    return this;
+  }
+
+  removeEdge(e: Edge): this {
+    const id = edgeId(e);
+    if (!this.edgeMap.has(id)) {
+      return this.addViolation({
+        violation: GraphViolationType.REMOVE_EDGE_VIOLATION,
+        source: e.source,
+        target: e.target,
+        name: e.name,
+      });
+    }
+
+    this.removeSegmentsForEdge(e);
+    this.edgeSegmentsMap.delete(id);
+
+    this.edgeMap.delete(id);
+    this.edgeLabelMap.delete(id);
+    decEntry(this.preds(e.target), e.source);
+    decEntry(this.sucs(e.source), e.target);
+    if (this.inMap.has(e.target)) {
+      this.inMap.get(e.target)!.delete(id);
+    }
+    if (this.outMap.has(e.source)) {
+      this.outMap.get(e.source)!.delete(id);
+    }
+
+    return this;
+  }
+
+  get sources(): Set<NodeId> {
+    return new Set(Array.from(this.nodes).filter((id) => this.in(id).size === 0));
+  }
+
+  get sinks(): Set<NodeId> {
+    return new Set(Array.from(this.nodes).filter((id) => this.out(id).size === 0));
+  }
+
+  parent(id: NodeId): NodeId {
+    return this.parentMap.get(id) || GRAPH_ROOT;
+  }
+
+  setParent(id: NodeId, parent: NodeId = GRAPH_ROOT): this {
+    if (!this.hasNode(id)) {
+      return this.addViolation({
+        violation: GraphViolationType.CHILD_NODE_VIOLATION,
+        node: id,
+      });
+    }
+    if (parent !== GRAPH_ROOT && !this.hasNode(parent)) {
+      return this.addViolation({
+        violation: GraphViolationType.PARENT_NODE_VIOLATION,
+        node: id,
+        parent,
+      });
+    }
+    if (parent !== GRAPH_ROOT) {
+      for (let ancestor = parent; ancestor !== GRAPH_ROOT; ancestor = this.parent(ancestor)) {
+        if (ancestor === id) {
+          throw new Error(CYCLE_SETTING_PARENT);
+        }
+      }
+    }
+
+    this.children(this.parent(id)).delete(id);
+    this.parentMap.set(id, parent);
+    this.children(parent).add(id);
+    this.leaves.delete(parent);
+
+    // Update all edges to nodes who have changed trees
+    if (this.trackSegments) {
+      for (const descendant of [id, ...this.descendants(id)]) {
+        for (const edge of this.edgeIds(descendant)) {
+          this.updateSegmentsForEdge(edge);
+        }
+      }
+    }
+    return this;
+  }
+
+  children(id: NodeId = GRAPH_ROOT): Set<NodeId> {
+    const children = this.childrenMap.get(id) || new Set();
+    this.childrenMap.set(id, children);
+    return children;
+  }
+
+  hasChildren(id: NodeId = GRAPH_ROOT): boolean {
+    return this.children(id).size > 0;
+  }
+
+  hasParent(id: NodeId): boolean {
+    return this.parent(id) !== GRAPH_ROOT;
+  }
+
+  descendants(id: NodeId | undefined = GRAPH_ROOT): Set<NodeId> {
+    const stack = [];
+    // Separate loop rather than initializing stack to id because this does not
+    // include the id. That allows [...ancestors, ...descendants] to not double
+    // cound id.
+    for (const child of this.children(id)) {
+      stack.push(child);
+    }
+
+    const nodes = new Set<NodeId>();
+    while ((id = stack.pop())) {
+      nodes.add(id);
+      for (const child of this.children(id)) {
+        stack.push(child);
+      }
+    }
+    return nodes;
+  }
+
+  ancestors(id: NodeId = GRAPH_ROOT): NodeId[] {
+    const ancestors = [];
+    while (this.hasNode(id)) {
+      ancestors.push(id);
+      id = this.parent(id);
+    }
+    return ancestors;
+  }
+
+  private in(id: NodeId): Map<EdgeId, Edge> {
+    const map = this.inMap.get(id) || new Map<EdgeId, Edge>();
+    this.inMap.set(id, map);
+    return map;
+  }
+
+  private out(id: NodeId): Map<EdgeId, Edge> {
+    const map = this.outMap.get(id) || new Map<EdgeId, Edge>();
+    this.outMap.set(id, map);
+    return map;
+  }
+
+  /**
+   * Utility to get a map, with keys for predecessor (incoming) nodeId, and
+   * and value being the count of edges with that node as its source.
+   */
+  private preds(id: NodeId): Map<NodeId, number> {
+    const preds = this.predMap.get(id) || new Map<EdgeId, number>();
+    this.predMap.set(id, preds);
+    return preds;
+  }
+
+  predecessors(id: NodeId): Set<NodeId> {
+    return new Set(this.preds(id).keys());
+  }
+
+  /**
+   * Utility to get a map, with keys for successor (ioutgoing) nodeId, and
+   * and value being the count of edges with that node as its target.
+   */
+  private sucs(id: NodeId): Map<NodeId, number> {
+    const sucs = this.sucsMap.get(id) || new Map<EdgeId, number>();
+    this.sucsMap.set(id, sucs);
+    return sucs;
+  }
+
+  successors(id: NodeId): Set<NodeId> {
+    return new Set(this.sucs(id).keys());
+  }
+
+  neighbors(id: NodeId): Set<NodeId> {
+    const s = new Set<NodeId>();
+    for (const node of this.predecessors(id)) s.add(node);
+    for (const node of this.successors(id)) s.add(node);
+    return s;
+  }
+
+  isLeaf(id: NodeId): boolean {
+    return this.successors(id).size === 0;
+  }
+
+  hasSegment(s: Segment<EdgeValue>): boolean {
+    return this.pathSegmentsMap.has(s.source) && this.pathSegmentsMap.get(s.source)!.has(s.target);
+  }
+
+  isTopSegment(s: Segment<EdgeValue>): boolean {
+    if (!this.hasSegment(s)) return false;
+    // A node is top-level if the source does not have a parent.
+    return !this.hasParent(s.source);
+  }
+
+  topSegment(source: NodeId, target: NodeId): Segment<EdgeValue> | undefined {
+    if (target < source) {
+      [source, target] = [target, source];
+    }
+
+    const segA = this.pathSegmentsMap.get(source);
+    if (!segA) return undefined;
+    const segB = segA.get(target);
+    if (!segB) return undefined;
+    const path = pathId([source, target]);
+    return segB.get(path);
+  }
+
+  nodeSegments(id: NodeId): Iterable<Segment<EdgeValue>> {
+    return this.nodeSegmentsMap.get(id) || new Set();
+  }
+
+  childSegments(id = GRAPH_ROOT): Iterable<Segment<EdgeValue>> {
+    return this.childSegmentsMap.get(id) || new Set();
+  }
+
+  get topSegments(): Iterable<Segment<EdgeValue>> {
+    return this.childSegments();
+  }
+
+  edgeSegments(edge: Edge): Iterable<Segment<EdgeValue>> {
+    const eid = edgeId(edge);
+    return this.edgeSegmentsMap.get(eid) || new Set();
+  }
+
+  segmentsUnderNode(nodeId = GRAPH_ROOT): Iterable<Segment<EdgeValue>> {
+    const segments = new Set<Segment<EdgeValue>>();
+
+    // Include segments pointing up to this node
+    for (const segment of this.nodeSegments(nodeId)) {
+      if (segment.target === nodeId && this.parent(segment.source) === nodeId) {
+        segments.add(segment);
+      }
+    }
+
+    // Include segments between children of this node
+    for (const id of this.children(nodeId)) {
+      for (const segment of this.nodeSegments(id)) {
+        if (this.parent(segment.source) === nodeId && this.parent(segment.target) === nodeId) {
+          segments.add(segment);
+        }
+      }
+    }
+
+    return segments;
+  }
+
+  successorSegments(id: NodeId): Iterable<Segment<EdgeValue>> {
+    return this.getSegmentNeighbors(id, this.outMap);
+  }
+
+  predecessorSegments(id: NodeId): Iterable<Segment<EdgeValue>> {
+    return this.getSegmentNeighbors(id, this.inMap);
+  }
+
+  segmentNeighborhood(id: NodeId): Iterable<Segment<EdgeValue>> {
+    const neighborhood = new Set<Segment<EdgeValue>>();
+    for (const segment of this.successorSegments(id)) {
+      neighborhood.add(segment);
+    }
+    for (const segment of this.predecessorSegments(id)) {
+      neighborhood.add(segment);
+    }
+    return neighborhood;
+  }
+
+  edgeDirectionAlongSegment(edge: Edge, segment: Segment<EdgeValue>): EdgeDirectionAlongSegment {
+    const spid = this.parent(segment.source);
+    const tpid = this.parent(segment.target);
+
+    const edgeSourceChain = this.ancestors(edge.source);
+    const edgeTargetChain = this.ancestors(edge.target);
+
+    if (spid === tpid) {
+      // This is a segment between two nodes with the same parent. Because
+      // segments are normalized alphabetically, check whether the segment
+      // source and target line up with the edge source and segment
+      // (SOURCE_TARGET) or if the segment is reversed from the edge.
+      if (edgeSourceChain.includes(segment.source) && edgeTargetChain.includes(segment.target)) {
+        return EdgeDirectionAlongSegment.SOURCE_TARGET;
+      }
+      if (edgeSourceChain.includes(segment.target) && edgeTargetChain.includes(segment.source)) {
+        return EdgeDirectionAlongSegment.TARGET_SOURCE;
+      }
+      return EdgeDirectionAlongSegment.NOT_CROSSING;
+    }
+
+    // If the segment is not between siblings, check the direction of each
+    // ancestor chain.
+
+    const sourceChainSourceIndex = edgeSourceChain.indexOf(segment.source);
+    const sourceChainTargetIndex = edgeSourceChain.indexOf(segment.target);
+    if (sourceChainSourceIndex > -1 && sourceChainTargetIndex > -1) {
+      // At this point, because of the rules of segments, scti and scsi are
+      // apart by 1.
+      const direction = sourceChainTargetIndex - sourceChainSourceIndex;
+      assert(direction === 1 || direction === -1, `Invalid segment positions.`);
+      if (direction === 1) return EdgeDirectionAlongSegment.SOURCE_TARGET;
+      if (direction === -1) return EdgeDirectionAlongSegment.TARGET_SOURCE;
+    }
+
+    const targetChainSourceIndex = edgeTargetChain.indexOf(segment.source);
+    const targetChainTargetIndex = edgeTargetChain.indexOf(segment.target);
+    if (targetChainSourceIndex > -1 && targetChainTargetIndex > -1) {
+      // At this point, because of the rules of segments, scti and scsi are
+      // apart by 1.
+      const direction = targetChainTargetIndex - targetChainSourceIndex;
+      assert(direction === 1 || direction === -1, `Invalid segment positions.`);
+      if (direction === 1) return EdgeDirectionAlongSegment.TARGET_SOURCE;
+      if (direction === -1) return EdgeDirectionAlongSegment.SOURCE_TARGET;
+    }
+
+    // If the edge and segment haven't coincided at this point, the edge is not
+    // part of the segment. Should this be an error case?
+
+    return EdgeDirectionAlongSegment.NOT_CROSSING;
+  }
+
+  private getSegmentNeighbors(id: NodeId, map: Map<NodeId, Map<EdgeId, Edge>>) {
+    const segments = this.getAdjacentSegments(map.get(id));
+    for (const descendant of this.descendants(id)) {
+      for (const segment of this.getAdjacentSegments(map.get(descendant))) {
+        segments.add(segment);
+      }
+    }
+    return segments;
+  }
+
+  private getAdjacentSegments(map = new Map<EdgeId, Edge>()) {
+    const edges = map.values();
+
+    const neighborhood = new Set<Segment<EdgeValue>>();
+    for (const edge of edges) {
+      for (const segment of this.edgeSegments(edge)) {
+        neighborhood.add(segment);
+      }
+    }
+
+    return neighborhood;
+  }
+
+  /**
+   * For a given edge, clear any segments it's already part of. Find or create
+   * fresh segments, then add the edge to those. Overall, O(depth of edge).
+   */
+  private updateSegmentsForEdge(e: Edge) {
+    if (!this.trackSegments) return;
+
+    const eid = edgeId(e);
+    if (this.edgeSegmentsMap.has(eid)) {
+      this.removeSegmentsForEdge(e);
+    } else {
+      this.edgeSegmentsMap.set(eid, new Set());
+    }
+
+    const segments = this.buildSegmentsForEdge(e);
+
+    const edgeSegments = this.edgeSegmentsMap.get(eid)!;
+    for (const segment of segments) {
+      this.allSegments.add(segment);
+      edgeSegments.add(segment);
+      segment.edges.add(this.edge(e)!);
+    }
+  }
+
+  private buildSegmentsForEdge(e: Edge): Array<Segment<EdgeValue>> {
+    const segments =
+      this.parent(e.source) === this.parent(e.target)
+        ? [this.createSiblingSegment(e)]
+        : this.createPathSegments(e);
+    return segments;
+  }
+
+  private createSiblingSegment(e: Edge): Segment<EdgeValue> {
+    // Normalize source and target alphabetically for segments between siblings.
+    const sid = e.source;
+    const tid = e.target;
+    const [source, target] = sid > tid ? [tid, sid] : [sid, tid];
+    const segment = this.findOrCreateSegment(source, target, [source, target]);
+
+    const pid = this.parent(sid);
+    const children = this.childSegmentsMap.get(pid) || new Set<Segment<EdgeValue>>();
+    children.add(segment);
+    this.childSegmentsMap.set(pid, children);
+
+    return segment;
+  }
+
+  /**
+   * Create all segments up both legs of the path, as well as a sibling
+   * segment.
+   */
+  private createPathSegments(e: Edge): Array<Segment<EdgeValue>> {
+    const sourcePath = this.ancestors(e.source);
+    const targetPath = this.ancestors(e.target);
+
+    // Remove path segments while they're at the same level
+    while (sourcePath[sourcePath.length - 1] === targetPath[targetPath.length - 1]) {
+      sourcePath.pop();
+      targetPath.pop();
+    }
+
+    const sourceTop = sourcePath[sourcePath.length - 1] || e.source;
+    const targetTop = targetPath[targetPath.length - 1] || e.target;
+
+    sourcePath.push(targetTop);
+    targetPath.push(sourceTop);
+
+    // Begin by creating all path segments which are _not_ sibling segments.
+    // However, the path for the segments must go "over" the top most node.
+    // Given `b { a } d { c } e; a -> c; a -> e` the necessary segments are
+    // `a ~ b -> c`, `a ~ b -> e`, `d ~ c -> b, `b ~ d`, and `b ~ e`. To ensure
+    // a distinction between `a ~ b -> c` and `a ~ b -> e`, the paths include
+    // the final sibling destination, and then segmentsForPath only connects
+    // segments on the path from [0, -2]. After creating the path segments,
+    // they get joined with the topSegment from the sibling nodes, below.
+    const sourceSegments = this.segmentsForPath(sourcePath);
+    const targetSegments = this.segmentsForPath(targetPath);
+
+    const topSegment = this.createSiblingSegment({
+      source: sourceTop,
+      target: targetTop,
+    });
+
+    // Link source path segments and target path segments with topSegment
+    if (sourceSegments.length > 0) {
+      const topSourceSegment = sourceSegments[sourceSegments.length - 1];
+      topSegment.previous.add(topSourceSegment);
+      topSourceSegment.next = topSegment;
+    }
+    if (targetSegments.length > 0) {
+      const topTargetSegment = targetSegments[targetSegments.length - 1];
+      topTargetSegment.next = topSegment;
+      topSegment.previous.add(topTargetSegment);
+    }
+
+    const segments = [...sourceSegments, ...targetSegments, topSegment];
+    return segments;
+  }
+
+  /** Create all segments from a node up to the root. */
+  private segmentsForPath(path: NodeId[]): Array<Segment<EdgeValue>> {
+    const segments: Array<Segment<EdgeValue>> = [];
+
+    // Source is always lower in the hierarchy than target.
+    const height = path.length - 1; // The
+    for (let i = 0; i < height - 1; i++) {
+      segments.push(this.findOrCreateSegment(path[i], path[i + 1], path.slice(i + 2)));
+    }
+
+    for (let i = 0; i < segments.length; i++) {
+      const next = segments[i + 1];
+      const prev = segments[i - 1];
+      if (prev) segments[i].previous.add(prev);
+      if (next) segments[i].next = next;
+    }
+    return segments;
+  }
+
+  /**
+   * Given a source, target, and path, find the segment that it uniquely
+   * identifies, or create it if it doesn't exist yet.
+   */
+  private findOrCreateSegment(
+    source: NodeId,
+    target: NodeId,
+    path: NodeId[] = [],
+  ): Segment<EdgeValue> {
+    if (!this.pathSegmentsMap.has(source)) {
+      this.pathSegmentsMap.set(source, new Map<string, Map<string, Segment<EdgeValue>>>());
+    }
+    const sourceMap = this.pathSegmentsMap.get(source)!;
+
+    if (!sourceMap.has(target)) {
+      sourceMap.set(target, new Map<string, Segment<EdgeValue>>());
+    }
+    const targetMap = sourceMap.get(target)!;
+
+    const pid = pathId(path);
+
+    const segment: Segment<EdgeValue> = (targetMap.get(pid) || {
+      source,
+      target,
+      edges: new Set<EdgeValue>(),
+      previous: new Set<Segment<EdgeValue>>(),
+    }) as Segment<EdgeValue>;
+    targetMap.set(pid, segment);
+
+    if (!this.nodeSegmentsMap.has(source)) {
+      this.nodeSegmentsMap.set(source, new Set());
+    }
+    this.nodeSegmentsMap.get(source)!.add(segment);
+
+    if (!this.nodeSegmentsMap.has(target)) {
+      this.nodeSegmentsMap.set(target, new Set());
+    }
+    this.nodeSegmentsMap.get(target)!.add(segment);
+
+    return targetMap.get(pid) as Segment<EdgeValue>;
+  }
+
+  private removeSegmentsForEdge(e: Edge) {
+    for (const segment of this.edgeSegments(e)) {
+      segment.edges.delete(this.edge(e)!);
+      if (segment.edges.size > 0) {
+        // The segment has other edges left in it, so don't remove it yet.
+        continue;
+      }
+      const parent = this.parent(segment.source);
+      if (!this.hasNode(parent) || parent === segment.target) {
+        const children = this.childSegmentsMap.get(parent);
+        if (children) children.delete(segment);
+      }
+      this.allSegments.delete(segment);
+      if (this.nodeSegmentsMap.has(segment.source)) {
+        this.nodeSegmentsMap.get(segment.source)!.delete(segment);
+      }
+      if (this.nodeSegmentsMap.has(segment.target)) {
+        this.nodeSegmentsMap.get(segment.target)!.delete(segment);
+      }
+      if (this.pathSegmentsMap.has(segment.source)) {
+        const pathSourceMap = this.pathSegmentsMap.get(segment.source)!;
+        if (pathSourceMap.has(segment.target)) {
+          const pathTargetMap = pathSourceMap.get(segment.target)!;
+          const pid = pathId(segmentPath(segment));
+          if (pathTargetMap.has(pid)) {
+            pathTargetMap.delete(pid);
+          }
+        }
+      }
+    }
+  }
+
+  private addViolation(violation: GraphViolation): this {
+    this.graphViolations.push(violation);
+    return this;
+  }
+}
+
+/** Given an edge, return a unique string ID for it. */
+export function edgeId({ source, target, name = DEFAULT_EDGE_NAME }: Edge): EdgeId {
+  return `${source}${EDGE_KEY_DELIM}${target}${EDGE_KEY_DELIM}${name}`;
+}
+
+/** Join a segment path of NodeIds into a unique string. */
+export function pathId(path: NodeId[]): string {
+  return path.join(SEGMENT_DELIM);
+}
+
+/**
+ * Return a list of all node ids in order from the source of the first segment,
+ * up the parent chain, and across the sibling.
+ */
+export function segmentPath(segment: Segment): NodeId[] {
+  const path: NodeId[] = [segment.source];
+  let last: Segment | undefined;
+  let next: Segment | undefined = segment;
+  while (next) {
+    if (!next.next && last && next.target === last.target) {
+      // At the top of the path, possibly un-reverse segments.
+      path.push(next.source);
+    } else {
+      path.push(next.target);
+    }
+    last = next;
+    next = next.next;
+  }
+  return path;
+}
+
+/**
+ * Returns a string suitable to uniquely identify a segment.
+ */
+export function segmentId(segment: Segment): SegmentId {
+  return segmentPath(segment).join(SEGMENT_DELIM);
+}
+
+/** Increment a count in a map, defaulting to 0 if unset. */
+function incEntry<T>(map: Map<T, number>, key: T) {
+  const value = map.get(key) || 0;
+  map.set(key, value + 1);
+}
+
+/** Decrement a count in a map, removing it if $t's empty. */
+function decEntry<T>(map: Map<T, number>, key: T) {
+  const value = (map.get(key) || 0) - 1;
+  if (value <= 0) {
+    map.delete(key);
+  } else {
+    map.set(key, value);
+  }
+}