Story navigation and details

Source-grounded

The @topo/graph layout session requests a projection because it needs the visible graph before placing nodes. Local code and indexed data reduce the view while retaining evidence membership. Directory/cycle derivation is an input preparation step, not rerun by every projection. Coordinate placement follows the returned projection and is outside this diagram. This is not Archify/Graphviz layout, the separate Repository page index, or the hand-curated module map.

  • Layout session

    @topo/graph.createLayoutSession prepares the view data needed to place nodes. It creates a projection session once, then calls session.project(options) for each layout request. The returned visible entities and relationships are passed to layoutProjection to compute coordinates. This diagram shows that initiating layout unit asking for membership and relationships, not the downstream coordinate-placement algorithm. The one-shot layoutGraphWithArchitecture path uses the same projection core without retaining a session.

    packages/graph/src/layout.ts:385-396
    export function createLayoutSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): LayoutSession {
  const session = createProjectionSession(graph, architecture);
  return Object.freeze({
    layout(optionsValue?: unknown): LayoutResult {
      const options = validateOptions(optionsValue);
      return layoutProjection(session.graphRef, session.project(options), options);
    },
  });
}
    packages/graph/src/layout.ts:368-383
    export function layoutGraphWithArchitecture(
  graph: unknown,
  architecture: ArchitectureDocument,
  optionsValue?: unknown,
): LayoutResult {
  const options = validateOptions(optionsValue);
  const projection = projectGraph(graph, architecture, options);
  const graphDocument = graph as GraphDocument;
  return layoutProjection({
    graphId: architecture.graphId,
    schemaVersion: graphDocument.schemaVersion ?? GRAPH_SCHEMA_VERSION,
    ...(graphDocument.repository.revision === undefined
      ? {}
      : { revision: graphDocument.repository.revision }),
  }, projection, options);
}
    packages/graph/src/project.ts:367-374
    export function projectGraph(
  graph: unknown,
  architecture: ArchitectureDocument,
  optionsValue?: unknown,
): GraphProjection {
  assertGraphDocument(graph);
  return projectIndexedGraph(indexGraph(graph, architecture), optionsValue);
}
  • Indexed snapshot Open Dependency context by role: Build, test, docsOpen Dependency context by role: Development toolsOpen Topocode internal modules: @topo/graph

    createProjectionSession copies the fields needed for projection, validates graph/architecture identity, and indexes nodes, directory ancestors, cycle groups and spine-edge IDs. The returned session closes over that index and exposes a frozen graph reference. The architecture input was prepared earlier by deriveArchitecture. Its cycle grouping uses Tarjan-style strongly connected components; that detection is not called anew for every expand/collapse request.

    packages/graph/src/project.ts:376-438
    export function createProjectionSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): ProjectionSession {
  assertGraphDocument(graph);
  validateArchitecture(graph.graphId, architecture);
  const snapshot: {
    graph: ProjectionGraph;
    architecture: ProjectionArchitecture;
  } = {
    graph: {
      graphId: graph.graphId,
      schemaVersion: graph.schemaVersion,
      repository: { ...graph.repository },
      nodes: graph.nodes.map((node) => ({
        ...node,
        identity: { ...node.identity },
      })),
      edges: graph.edges.map(({ id, sourceId, targetId, type }) => ({
        id,
        sourceId,
        targetId,
        type,
      })),
    },
    architecture: {
      version: architecture.version,
      graphId: architecture.graphId,
      rootContainerId: architecture.rootContainerId,
      scalePolicy: { ...architecture.scalePolicy },
      directoryContainers: architecture.directoryContainers.map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        childContainerIds: [...container.childContainerIds],
        memberNodeIds: [...container.memberNodeIds],
      })),
      stronglyConnectedComponents: architecture.stronglyConnectedComponents.map(
        (component) => ({
          id: component.id,
          memberNodeIds: [...component.memberNodeIds],
          collapsed: {
            id: component.collapsed.id,
            label: component.collapsed.label,
          },
        }),
      ),
      spineFindings: architecture.spineFindings.map(({ edgeId }) => ({ edgeId })),
    },
  };
  const index = indexGraph(snapshot.graph, snapshot.architecture);
  const project = (options?: unknown) => projectIndexedGraph(index, options);
  const graphRef = Object.freeze({
    graphId: snapshot.graph.graphId,
    schemaVersion: snapshot.graph.schemaVersion,
    ...(snapshot.graph.repository.revision === undefined
      ? {}
      : { revision: snapshot.graph.repository.revision }),
  });
  return Object.freeze({ graphRef, project });
}
    packages/graph/src/project.ts:107-160
    function indexGraph(
  graph: ProjectionGraph,
  architecture: ProjectionArchitecture,
) {
  validateArchitecture(graph.graphId, architecture);
  const containers = new Map(
    architecture.directoryContainers.map((container) => [container.id, container]),
  );
  const tangles = new Map(
    architecture.stronglyConnectedComponents.map((component) => [
      component.id,
      component,
    ]),
  );
  const tangleByCollapsedId = new Map<
    string,
    ProjectionArchitecture["stronglyConnectedComponents"][number]
  >();
  for (const component of tangles.values()) {
    if (!tangleByCollapsedId.has(component.collapsed.id)) {
      tangleByCollapsedId.set(component.collapsed.id, component);
    }
  }
  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
  const ancestorsByNodeId = new Map<string, string[]>();
  for (const container of architecture.directoryContainers) {
    for (const nodeId of container.memberNodeIds) {
      const ancestors: string[] = [];
      let current: typeof container | undefined = container;
      while (current) {
        ancestors.push(current.id);
        current =
          current.parentId === undefined
            ? undefined
            : containers.get(current.parentId);
      }
      ancestorsByNodeId.set(nodeId, ancestors.reverse());
    }
  }
  const spineEdgeIds = new Set(
    architecture.spineFindings.map((finding) => finding.edgeId),
  );

  return {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  };
}
    packages/graph/src/derive.ts:441-488
    export function deriveArchitecture(graph: unknown): ArchitectureDocument {
  assertGraphDocument(graph);
  const directories = buildDirectories(graph);
  const directoryByPath = new Map(
    directories.map((directory) => [directory.path, directory]),
  );
  const { components, findings } = deriveComponents(graph);
  const representatives = new Map(
    graph.nodes.map((node) => [
      node.id,
      topLevelRepresentative(node, directoryByPath),
    ]),
  );
  const spineEdgeIds = new Set(findings.map((finding) => finding.edgeId));
  const levels = new Map<number, string[]>();
  for (const directory of directories) {
    const ids = levels.get(directory.depth) ?? [];
    ids.push(directory.id);
    levels.set(directory.depth, ids);
  }

  return {
    version: "1.0",
    graphId: graph.graphId,
    rootContainerId: ROOT_CONTAINER_ID,
    directoryContainers: directories,
    directoryLevels: [...levels.entries()]
      .map(([depth, containerIds]) => ({
        depth,
        containerIds: containerIds.sort(compareText),
      }))
      .sort((left, right) => left.depth - right.depth),
    aggregatedEdges: aggregateDirectedEdges(
      graph.edges,
      representatives,
      spineEdgeIds,
    ),
    stronglyConnectedComponents: components,
    spineFindings: findings,
    nodeVisualValues: deriveNodeVisualValues(graph),
    scalePolicy: {
      edgeThickness: "log1p",
      nodeProminence: "rank",
      tangleProminence: "log1p",
      sparseEdgeCoverage: SPARSE_EDGE_COVERAGE,
    },
  };
}
    packages/graph/src/derive.ts:121-185
    function stronglyConnectedSets(
  nodeIds: readonly string[],
  edges: readonly GraphEdge[],
  excludedEdgeId?: string,
): string[][] {
  const allowed = new Set(nodeIds);
  const outgoing = new Map<string, string[]>();
  for (const nodeId of nodeIds) outgoing.set(nodeId, []);
  for (const edge of edges) {
    if (
      edge.id !== excludedEdgeId &&
      allowed.has(edge.sourceId) &&
      allowed.has(edge.targetId)
    ) {
      outgoing.get(edge.sourceId)!.push(edge.targetId);
    }
  }
  for (const targets of outgoing.values()) targets.sort(compareText);

  let nextIndex = 0;
  const indices = new Map<string, number>();
  const lowLinks = new Map<string, number>();
  const stack: string[] = [];
  const onStack = new Set<string>();
  const components: string[][] = [];

  function visit(nodeId: string): void {
    const index = nextIndex++;
    indices.set(nodeId, index);
    lowLinks.set(nodeId, index);
    stack.push(nodeId);
    onStack.add(nodeId);

    for (const targetId of outgoing.get(nodeId) ?? []) {
      if (!indices.has(targetId)) {
        visit(targetId);
        lowLinks.set(
          nodeId,
          Math.min(lowLinks.get(nodeId)!, lowLinks.get(targetId)!),
        );
      } else if (onStack.has(targetId)) {
        lowLinks.set(
          nodeId,
          Math.min(lowLinks.get(nodeId)!, indices.get(targetId)!),
        );
      }
    }

    if (lowLinks.get(nodeId) !== indices.get(nodeId)) return;
    const component: string[] = [];
    while (stack.length > 0) {
      const member = stack.pop()!;
      onStack.delete(member);
      component.push(member);
      if (member === nodeId) break;
    }
    component.sort(compareText);
    components.push(component);
  }

  for (const nodeId of [...nodeIds].sort(compareText)) {
    if (!indices.has(nodeId)) visit(nodeId);
  }
  return components.sort((left, right) => compareText(left[0]!, right[0]!));
}
    packages/graph/package.json:1-28
    {
  "name": "@topo/graph",
  "version": "0.0.0",
  "private": true,
  "type": "module",
  "files": [
    "dist"
  ],
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc -b",
    "typecheck": "tsc -b --pretty false",
    "test": "vitest run"
  },
  "dependencies": {
    "@topo/schema": "workspace:*"
  },
  "devDependencies": {
    "typescript": "^7.0.2",
    "vite": "8.2.2",
    "vitest": "^5.0.0"
  }
}
  • Projection

    projectIndexedGraph validates options and requested member/cycle IDs. For each included node, choose its collapsed cycle representative, otherwise its first closed directory ancestor, otherwise itself. External exclusions are explicit. Build visible entities and containers, ask for directed aggregates, and separately account for original edges whose endpoints collapse inside the same visible group. IDs/order remain stable for the same inputs and options.

    packages/graph/src/project.ts:162-365
    function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}
    packages/graph/src/project.ts:43-83
    function validateOptions(value: unknown): ProjectionOptions {
  if (value === undefined) return {};
  if (!isRecord(value)) {
    throw new GraphEngineValidationError([
      { path: "$", message: "Projection options must be an object." },
    ]);
  }
  const issues: { path: string; message: string }[] = [];
  for (const key of [
    "memberNodeIds",
    "expandedContainerIds",
    "collapsedTangleIds",
  ] as const) {
    const child = value[key];
    if (
      child !== undefined &&
      (!Array.isArray(child) ||
        child.some((entry) => typeof entry !== "string" || entry.length === 0))
    ) {
      issues.push({
        path: `$.${key}`,
        message: "Expected an array of non-empty identifiers.",
      });
    } else if (child !== undefined && new Set(child).size !== child.length) {
      issues.push({
        path: `$.${key}`,
        message: "Identifiers must be unique.",
      });
    }
  }
  for (const key of ["includeExternal", "sparseEdgesOnly"] as const) {
    if (value[key] !== undefined && typeof value[key] !== "boolean") {
      issues.push({ path: `$.${key}`, message: "Expected a boolean." });
    }
  }
  if (value.viewId !== undefined && (typeof value.viewId !== "string" || value.viewId.length === 0)) {
    issues.push({ path: "$.viewId", message: "Expected a non-empty string." });
  }
  if (issues.length > 0) throw new GraphEngineValidationError(issues);
  return value as ProjectionOptions;
}
  • Edge aggregation

    aggregateDirectedEdges maps every original edge through the representative map, groups equal directed endpoint pairs, and retains original edge IDs, directions, types and weights. Opposite directions remain distinct. Same-representative edges are accounted for by Projection instead of drawn as misleading cross-group arrows. Optional sparse selection retains weighted coverage plus spine edges; the default policy is 83% of represented edge weight, not 83% of nodes. It is not a minimum spanning tree or automatic community/architecture discovery.

    packages/graph/src/project.ts:162-365
    function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}
    packages/graph/src/derive.ts:293-408
    export function aggregateDirectedEdges(
  edges: readonly Pick<GraphEdge, "id" | "sourceId" | "targetId" | "type">[],
  representativeByNodeId: ReadonlyMap<string, string>,
  spineEdgeIds: ReadonlySet<string> = new Set(),
  sparseCoverage = SPARSE_EDGE_COVERAGE,
): AggregatedEdge[] {
  const groups = new Map<
    string,
    {
      sourceId: string;
      targetId: string;
      edges: Array<(typeof edges)[number]>;
    }
  >();
  let maximumWeight = 1;
  for (const edge of [...edges].sort((left, right) =>
    compareText(left.id, right.id),
  )) {
    const sourceId = representativeByNodeId.get(edge.sourceId);
    const targetId = representativeByNodeId.get(edge.targetId);
    if (sourceId === undefined || targetId === undefined || sourceId === targetId) {
      continue;
    }
    const key = `${sourceId}\0${targetId}`;
    const group = groups.get(key) ?? { sourceId, targetId, edges: [] };
    group.edges.push(edge);
    maximumWeight = Math.max(maximumWeight, group.edges.length);
    groups.set(key, group);
  }

  const thicknessByWeight = new Map<number, number>();
  function thickness(weight: number): number {
    let value = thicknessByWeight.get(weight);
    if (value === undefined) {
      value = logScale(weight, maximumWeight, 1, 8);
      thicknessByWeight.set(weight, value);
    }
    return value;
  }
  const aggregates: AggregatedEdge[] = [...groups.values()].map((group) => {
    if (group.edges.length === 1) {
      const edge = group.edges[0]!;
      return {
        id: stableId("aggregate-edge", [group.sourceId, group.targetId]),
        sourceId: group.sourceId,
        targetId: group.targetId,
        memberEdgeIds: [edge.id],
        directions: [{
          sourceId: edge.sourceId,
          targetId: edge.targetId,
          edgeIds: [edge.id],
        }],
        edgeTypes: [edge.type],
        weight: 1,
        visual: { thickness: thickness(1), scale: "log1p", derived: true },
        sparse: false,
        spine: spineEdgeIds.has(edge.id),
      };
    }
    const memberEdgeIds = group.edges.map((edge) => edge.id);
    const directionGroups = new Map<string, string[]>();
    for (const edge of group.edges) {
      const key = `${edge.sourceId}\0${edge.targetId}`;
      const ids = directionGroups.get(key) ?? [];
      ids.push(edge.id);
      directionGroups.set(key, ids);
    }
    const aggregate: AggregatedEdge = {
      id: stableId("aggregate-edge", [group.sourceId, group.targetId]),
      sourceId: group.sourceId,
      targetId: group.targetId,
      memberEdgeIds,
      directions: [...directionGroups.entries()]
        .map(([key, edgeIds]) => {
          const [sourceId, targetId] = key.split("\0");
          return {
            sourceId: sourceId!,
            targetId: targetId!,
            edgeIds,
          };
        })
        .sort(
          (left, right) =>
            compareText(left.sourceId, right.sourceId) ||
            compareText(left.targetId, right.targetId),
        ),
      edgeTypes: sorted(new Set(group.edges.map((edge) => edge.type))),
      weight: group.edges.length,
      visual: {
        thickness: thickness(group.edges.length),
        scale: "log1p",
        derived: true,
      },
      sparse: false,
      spine: memberEdgeIds.some((edgeId) => spineEdgeIds.has(edgeId)),
    };
    return aggregate;
  });

  aggregates.sort((left, right) => compareText(left.id, right.id));
  const ranked = maximumWeight === 1
    ? aggregates
    : [...aggregates].sort(
        (left, right) =>
          right.weight - left.weight || compareText(left.id, right.id),
      );
  const totalWeight = ranked.reduce((total, edge) => total + edge.weight, 0);
  let retainedWeight = 0;
  for (const edge of ranked) {
    if (retainedWeight / Math.max(1, totalWeight) < sparseCoverage || edge.spine) {
      edge.sparse = true;
      retainedWeight += edge.weight;
    }
  }
  return aggregates;
}
    packages/graph/src/derive.ts:441-488
    export function deriveArchitecture(graph: unknown): ArchitectureDocument {
  assertGraphDocument(graph);
  const directories = buildDirectories(graph);
  const directoryByPath = new Map(
    directories.map((directory) => [directory.path, directory]),
  );
  const { components, findings } = deriveComponents(graph);
  const representatives = new Map(
    graph.nodes.map((node) => [
      node.id,
      topLevelRepresentative(node, directoryByPath),
    ]),
  );
  const spineEdgeIds = new Set(findings.map((finding) => finding.edgeId));
  const levels = new Map<number, string[]>();
  for (const directory of directories) {
    const ids = levels.get(directory.depth) ?? [];
    ids.push(directory.id);
    levels.set(directory.depth, ids);
  }

  return {
    version: "1.0",
    graphId: graph.graphId,
    rootContainerId: ROOT_CONTAINER_ID,
    directoryContainers: directories,
    directoryLevels: [...levels.entries()]
      .map(([depth, containerIds]) => ({
        depth,
        containerIds: containerIds.sort(compareText),
      }))
      .sort((left, right) => left.depth - right.depth),
    aggregatedEdges: aggregateDirectedEdges(
      graph.edges,
      representatives,
      spineEdgeIds,
    ),
    stronglyConnectedComponents: components,
    spineFindings: findings,
    nodeVisualValues: deriveNodeVisualValues(graph),
    scalePolicy: {
      edgeThickness: "log1p",
      nodeProminence: "rank",
      tangleProminence: "log1p",
      sparseEdgeCoverage: SPARSE_EDGE_COVERAGE,
    },
  };
}
    packages/graph/src/derive.ts:24-24
    SPARSE_EDGE_COVERAGE = 0.83

source-traced: Prepare a graph for layout

createLayoutSession supplies graph and derived architecture to createProjectionSession so repeated layout requests can reuse indexed evidence.

packages/graph/src/layout.ts:385-396
export function createLayoutSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): LayoutSession {
  const session = createProjectionSession(graph, architecture);
  return Object.freeze({
    layout(optionsValue?: unknown): LayoutResult {
      const options = validateOptions(optionsValue);
      return layoutProjection(session.graphRef, session.project(options), options);
    },
  });
}
packages/graph/src/project.ts:376-438
export function createProjectionSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): ProjectionSession {
  assertGraphDocument(graph);
  validateArchitecture(graph.graphId, architecture);
  const snapshot: {
    graph: ProjectionGraph;
    architecture: ProjectionArchitecture;
  } = {
    graph: {
      graphId: graph.graphId,
      schemaVersion: graph.schemaVersion,
      repository: { ...graph.repository },
      nodes: graph.nodes.map((node) => ({
        ...node,
        identity: { ...node.identity },
      })),
      edges: graph.edges.map(({ id, sourceId, targetId, type }) => ({
        id,
        sourceId,
        targetId,
        type,
      })),
    },
    architecture: {
      version: architecture.version,
      graphId: architecture.graphId,
      rootContainerId: architecture.rootContainerId,
      scalePolicy: { ...architecture.scalePolicy },
      directoryContainers: architecture.directoryContainers.map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        childContainerIds: [...container.childContainerIds],
        memberNodeIds: [...container.memberNodeIds],
      })),
      stronglyConnectedComponents: architecture.stronglyConnectedComponents.map(
        (component) => ({
          id: component.id,
          memberNodeIds: [...component.memberNodeIds],
          collapsed: {
            id: component.collapsed.id,
            label: component.collapsed.label,
          },
        }),
      ),
      spineFindings: architecture.spineFindings.map(({ edgeId }) => ({ edgeId })),
    },
  };
  const index = indexGraph(snapshot.graph, snapshot.architecture);
  const project = (options?: unknown) => projectIndexedGraph(index, options);
  const graphRef = Object.freeze({
    graphId: snapshot.graph.graphId,
    schemaVersion: snapshot.graph.schemaVersion,
    ...(snapshot.graph.repository.revision === undefined
      ? {}
      : { revision: snapshot.graph.repository.revision }),
  });
  return Object.freeze({ graphRef, project });
}

source-traced: Reusable projection session

The session captures its projection index and returns graphRef plus project(options).

packages/graph/src/project.ts:376-438
export function createProjectionSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): ProjectionSession {
  assertGraphDocument(graph);
  validateArchitecture(graph.graphId, architecture);
  const snapshot: {
    graph: ProjectionGraph;
    architecture: ProjectionArchitecture;
  } = {
    graph: {
      graphId: graph.graphId,
      schemaVersion: graph.schemaVersion,
      repository: { ...graph.repository },
      nodes: graph.nodes.map((node) => ({
        ...node,
        identity: { ...node.identity },
      })),
      edges: graph.edges.map(({ id, sourceId, targetId, type }) => ({
        id,
        sourceId,
        targetId,
        type,
      })),
    },
    architecture: {
      version: architecture.version,
      graphId: architecture.graphId,
      rootContainerId: architecture.rootContainerId,
      scalePolicy: { ...architecture.scalePolicy },
      directoryContainers: architecture.directoryContainers.map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        childContainerIds: [...container.childContainerIds],
        memberNodeIds: [...container.memberNodeIds],
      })),
      stronglyConnectedComponents: architecture.stronglyConnectedComponents.map(
        (component) => ({
          id: component.id,
          memberNodeIds: [...component.memberNodeIds],
          collapsed: {
            id: component.collapsed.id,
            label: component.collapsed.label,
          },
        }),
      ),
      spineFindings: architecture.spineFindings.map(({ edgeId }) => ({ edgeId })),
    },
  };
  const index = indexGraph(snapshot.graph, snapshot.architecture);
  const project = (options?: unknown) => projectIndexedGraph(index, options);
  const graphRef = Object.freeze({
    graphId: snapshot.graph.graphId,
    schemaVersion: snapshot.graph.schemaVersion,
    ...(snapshot.graph.repository.revision === undefined
      ? {}
      : { revision: snapshot.graph.repository.revision }),
  });
  return Object.freeze({ graphRef, project });
}
packages/graph/src/project.ts:107-160
function indexGraph(
  graph: ProjectionGraph,
  architecture: ProjectionArchitecture,
) {
  validateArchitecture(graph.graphId, architecture);
  const containers = new Map(
    architecture.directoryContainers.map((container) => [container.id, container]),
  );
  const tangles = new Map(
    architecture.stronglyConnectedComponents.map((component) => [
      component.id,
      component,
    ]),
  );
  const tangleByCollapsedId = new Map<
    string,
    ProjectionArchitecture["stronglyConnectedComponents"][number]
  >();
  for (const component of tangles.values()) {
    if (!tangleByCollapsedId.has(component.collapsed.id)) {
      tangleByCollapsedId.set(component.collapsed.id, component);
    }
  }
  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
  const ancestorsByNodeId = new Map<string, string[]>();
  for (const container of architecture.directoryContainers) {
    for (const nodeId of container.memberNodeIds) {
      const ancestors: string[] = [];
      let current: typeof container | undefined = container;
      while (current) {
        ancestors.push(current.id);
        current =
          current.parentId === undefined
            ? undefined
            : containers.get(current.parentId);
      }
      ancestorsByNodeId.set(nodeId, ancestors.reverse());
    }
  }
  const spineEdgeIds = new Set(
    architecture.spineFindings.map((finding) => finding.edgeId),
  );

  return {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  };
}

source-traced: Select the visible graph

The layout request passes scope and collapse options through session.project to obtain the graph that should be placed.

packages/graph/src/layout.ts:385-396
export function createLayoutSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): LayoutSession {
  const session = createProjectionSession(graph, architecture);
  return Object.freeze({
    layout(optionsValue?: unknown): LayoutResult {
      const options = validateOptions(optionsValue);
      return layoutProjection(session.graphRef, session.project(options), options);
    },
  });
}
packages/graph/src/project.ts:376-438
export function createProjectionSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): ProjectionSession {
  assertGraphDocument(graph);
  validateArchitecture(graph.graphId, architecture);
  const snapshot: {
    graph: ProjectionGraph;
    architecture: ProjectionArchitecture;
  } = {
    graph: {
      graphId: graph.graphId,
      schemaVersion: graph.schemaVersion,
      repository: { ...graph.repository },
      nodes: graph.nodes.map((node) => ({
        ...node,
        identity: { ...node.identity },
      })),
      edges: graph.edges.map(({ id, sourceId, targetId, type }) => ({
        id,
        sourceId,
        targetId,
        type,
      })),
    },
    architecture: {
      version: architecture.version,
      graphId: architecture.graphId,
      rootContainerId: architecture.rootContainerId,
      scalePolicy: { ...architecture.scalePolicy },
      directoryContainers: architecture.directoryContainers.map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        childContainerIds: [...container.childContainerIds],
        memberNodeIds: [...container.memberNodeIds],
      })),
      stronglyConnectedComponents: architecture.stronglyConnectedComponents.map(
        (component) => ({
          id: component.id,
          memberNodeIds: [...component.memberNodeIds],
          collapsed: {
            id: component.collapsed.id,
            label: component.collapsed.label,
          },
        }),
      ),
      spineFindings: architecture.spineFindings.map(({ edgeId }) => ({ edgeId })),
    },
  };
  const index = indexGraph(snapshot.graph, snapshot.architecture);
  const project = (options?: unknown) => projectIndexedGraph(index, options);
  const graphRef = Object.freeze({
    graphId: snapshot.graph.graphId,
    schemaVersion: snapshot.graph.schemaVersion,
    ...(snapshot.graph.repository.revision === undefined
      ? {}
      : { revision: snapshot.graph.repository.revision }),
  });
  return Object.freeze({ graphRef, project });
}
packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}

source-traced: Read nodes, ancestors and cycles

The projection reads local indexed maps; this arrow is a data dependency, not a service call.

packages/graph/src/project.ts:107-160
function indexGraph(
  graph: ProjectionGraph,
  architecture: ProjectionArchitecture,
) {
  validateArchitecture(graph.graphId, architecture);
  const containers = new Map(
    architecture.directoryContainers.map((container) => [container.id, container]),
  );
  const tangles = new Map(
    architecture.stronglyConnectedComponents.map((component) => [
      component.id,
      component,
    ]),
  );
  const tangleByCollapsedId = new Map<
    string,
    ProjectionArchitecture["stronglyConnectedComponents"][number]
  >();
  for (const component of tangles.values()) {
    if (!tangleByCollapsedId.has(component.collapsed.id)) {
      tangleByCollapsedId.set(component.collapsed.id, component);
    }
  }
  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
  const ancestorsByNodeId = new Map<string, string[]>();
  for (const container of architecture.directoryContainers) {
    for (const nodeId of container.memberNodeIds) {
      const ancestors: string[] = [];
      let current: typeof container | undefined = container;
      while (current) {
        ancestors.push(current.id);
        current =
          current.parentId === undefined
            ? undefined
            : containers.get(current.parentId);
      }
      ancestorsByNodeId.set(nodeId, ancestors.reverse());
    }
  }
  const spineEdgeIds = new Set(
    architecture.spineFindings.map((finding) => finding.edgeId),
  );

  return {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  };
}
packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}

source-traced: Indexed membership and hierarchy

Use those maps to choose a visible representative for each included node.

packages/graph/src/project.ts:107-160
function indexGraph(
  graph: ProjectionGraph,
  architecture: ProjectionArchitecture,
) {
  validateArchitecture(graph.graphId, architecture);
  const containers = new Map(
    architecture.directoryContainers.map((container) => [container.id, container]),
  );
  const tangles = new Map(
    architecture.stronglyConnectedComponents.map((component) => [
      component.id,
      component,
    ]),
  );
  const tangleByCollapsedId = new Map<
    string,
    ProjectionArchitecture["stronglyConnectedComponents"][number]
  >();
  for (const component of tangles.values()) {
    if (!tangleByCollapsedId.has(component.collapsed.id)) {
      tangleByCollapsedId.set(component.collapsed.id, component);
    }
  }
  const nodeById = new Map(graph.nodes.map((node) => [node.id, node]));
  const ancestorsByNodeId = new Map<string, string[]>();
  for (const container of architecture.directoryContainers) {
    for (const nodeId of container.memberNodeIds) {
      const ancestors: string[] = [];
      let current: typeof container | undefined = container;
      while (current) {
        ancestors.push(current.id);
        current =
          current.parentId === undefined
            ? undefined
            : containers.get(current.parentId);
      }
      ancestorsByNodeId.set(nodeId, ancestors.reverse());
    }
  }
  const spineEdgeIds = new Set(
    architecture.spineFindings.map((finding) => finding.edgeId),
  );

  return {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  };
}
packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}

source-traced: Original edges + representatives

aggregateDirectedEdges receives original edges, the representative map, spine IDs and the sparse coverage policy.

packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}
packages/graph/src/derive.ts:293-408
export function aggregateDirectedEdges(
  edges: readonly Pick<GraphEdge, "id" | "sourceId" | "targetId" | "type">[],
  representativeByNodeId: ReadonlyMap<string, string>,
  spineEdgeIds: ReadonlySet<string> = new Set(),
  sparseCoverage = SPARSE_EDGE_COVERAGE,
): AggregatedEdge[] {
  const groups = new Map<
    string,
    {
      sourceId: string;
      targetId: string;
      edges: Array<(typeof edges)[number]>;
    }
  >();
  let maximumWeight = 1;
  for (const edge of [...edges].sort((left, right) =>
    compareText(left.id, right.id),
  )) {
    const sourceId = representativeByNodeId.get(edge.sourceId);
    const targetId = representativeByNodeId.get(edge.targetId);
    if (sourceId === undefined || targetId === undefined || sourceId === targetId) {
      continue;
    }
    const key = `${sourceId}\0${targetId}`;
    const group = groups.get(key) ?? { sourceId, targetId, edges: [] };
    group.edges.push(edge);
    maximumWeight = Math.max(maximumWeight, group.edges.length);
    groups.set(key, group);
  }

  const thicknessByWeight = new Map<number, number>();
  function thickness(weight: number): number {
    let value = thicknessByWeight.get(weight);
    if (value === undefined) {
      value = logScale(weight, maximumWeight, 1, 8);
      thicknessByWeight.set(weight, value);
    }
    return value;
  }
  const aggregates: AggregatedEdge[] = [...groups.values()].map((group) => {
    if (group.edges.length === 1) {
      const edge = group.edges[0]!;
      return {
        id: stableId("aggregate-edge", [group.sourceId, group.targetId]),
        sourceId: group.sourceId,
        targetId: group.targetId,
        memberEdgeIds: [edge.id],
        directions: [{
          sourceId: edge.sourceId,
          targetId: edge.targetId,
          edgeIds: [edge.id],
        }],
        edgeTypes: [edge.type],
        weight: 1,
        visual: { thickness: thickness(1), scale: "log1p", derived: true },
        sparse: false,
        spine: spineEdgeIds.has(edge.id),
      };
    }
    const memberEdgeIds = group.edges.map((edge) => edge.id);
    const directionGroups = new Map<string, string[]>();
    for (const edge of group.edges) {
      const key = `${edge.sourceId}\0${edge.targetId}`;
      const ids = directionGroups.get(key) ?? [];
      ids.push(edge.id);
      directionGroups.set(key, ids);
    }
    const aggregate: AggregatedEdge = {
      id: stableId("aggregate-edge", [group.sourceId, group.targetId]),
      sourceId: group.sourceId,
      targetId: group.targetId,
      memberEdgeIds,
      directions: [...directionGroups.entries()]
        .map(([key, edgeIds]) => {
          const [sourceId, targetId] = key.split("\0");
          return {
            sourceId: sourceId!,
            targetId: targetId!,
            edgeIds,
          };
        })
        .sort(
          (left, right) =>
            compareText(left.sourceId, right.sourceId) ||
            compareText(left.targetId, right.targetId),
        ),
      edgeTypes: sorted(new Set(group.edges.map((edge) => edge.type))),
      weight: group.edges.length,
      visual: {
        thickness: thickness(group.edges.length),
        scale: "log1p",
        derived: true,
      },
      sparse: false,
      spine: memberEdgeIds.some((edgeId) => spineEdgeIds.has(edgeId)),
    };
    return aggregate;
  });

  aggregates.sort((left, right) => compareText(left.id, right.id));
  const ranked = maximumWeight === 1
    ? aggregates
    : [...aggregates].sort(
        (left, right) =>
          right.weight - left.weight || compareText(left.id, right.id),
      );
  const totalWeight = ranked.reduce((total, edge) => total + edge.weight, 0);
  let retainedWeight = 0;
  for (const edge of ranked) {
    if (retainedWeight / Math.max(1, totalWeight) < sparseCoverage || edge.spine) {
      edge.sparse = true;
      retainedWeight += edge.weight;
    }
  }
  return aggregates;
}

source-traced: Directed aggregates + provenance

Return weighted, deterministically ordered aggregates. sparseEdgesOnly is applied by the projection when requested.

packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}
packages/graph/src/derive.ts:293-408
export function aggregateDirectedEdges(
  edges: readonly Pick<GraphEdge, "id" | "sourceId" | "targetId" | "type">[],
  representativeByNodeId: ReadonlyMap<string, string>,
  spineEdgeIds: ReadonlySet<string> = new Set(),
  sparseCoverage = SPARSE_EDGE_COVERAGE,
): AggregatedEdge[] {
  const groups = new Map<
    string,
    {
      sourceId: string;
      targetId: string;
      edges: Array<(typeof edges)[number]>;
    }
  >();
  let maximumWeight = 1;
  for (const edge of [...edges].sort((left, right) =>
    compareText(left.id, right.id),
  )) {
    const sourceId = representativeByNodeId.get(edge.sourceId);
    const targetId = representativeByNodeId.get(edge.targetId);
    if (sourceId === undefined || targetId === undefined || sourceId === targetId) {
      continue;
    }
    const key = `${sourceId}\0${targetId}`;
    const group = groups.get(key) ?? { sourceId, targetId, edges: [] };
    group.edges.push(edge);
    maximumWeight = Math.max(maximumWeight, group.edges.length);
    groups.set(key, group);
  }

  const thicknessByWeight = new Map<number, number>();
  function thickness(weight: number): number {
    let value = thicknessByWeight.get(weight);
    if (value === undefined) {
      value = logScale(weight, maximumWeight, 1, 8);
      thicknessByWeight.set(weight, value);
    }
    return value;
  }
  const aggregates: AggregatedEdge[] = [...groups.values()].map((group) => {
    if (group.edges.length === 1) {
      const edge = group.edges[0]!;
      return {
        id: stableId("aggregate-edge", [group.sourceId, group.targetId]),
        sourceId: group.sourceId,
        targetId: group.targetId,
        memberEdgeIds: [edge.id],
        directions: [{
          sourceId: edge.sourceId,
          targetId: edge.targetId,
          edgeIds: [edge.id],
        }],
        edgeTypes: [edge.type],
        weight: 1,
        visual: { thickness: thickness(1), scale: "log1p", derived: true },
        sparse: false,
        spine: spineEdgeIds.has(edge.id),
      };
    }
    const memberEdgeIds = group.edges.map((edge) => edge.id);
    const directionGroups = new Map<string, string[]>();
    for (const edge of group.edges) {
      const key = `${edge.sourceId}\0${edge.targetId}`;
      const ids = directionGroups.get(key) ?? [];
      ids.push(edge.id);
      directionGroups.set(key, ids);
    }
    const aggregate: AggregatedEdge = {
      id: stableId("aggregate-edge", [group.sourceId, group.targetId]),
      sourceId: group.sourceId,
      targetId: group.targetId,
      memberEdgeIds,
      directions: [...directionGroups.entries()]
        .map(([key, edgeIds]) => {
          const [sourceId, targetId] = key.split("\0");
          return {
            sourceId: sourceId!,
            targetId: targetId!,
            edgeIds,
          };
        })
        .sort(
          (left, right) =>
            compareText(left.sourceId, right.sourceId) ||
            compareText(left.targetId, right.targetId),
        ),
      edgeTypes: sorted(new Set(group.edges.map((edge) => edge.type))),
      weight: group.edges.length,
      visual: {
        thickness: thickness(group.edges.length),
        scale: "log1p",
        derived: true,
      },
      sparse: false,
      spine: memberEdgeIds.some((edgeId) => spineEdgeIds.has(edgeId)),
    };
    return aggregate;
  });

  aggregates.sort((left, right) => compareText(left.id, right.id));
  const ranked = maximumWeight === 1
    ? aggregates
    : [...aggregates].sort(
        (left, right) =>
          right.weight - left.weight || compareText(left.id, right.id),
      );
  const totalWeight = ranked.reduce((total, edge) => total + edge.weight, 0);
  let retainedWeight = 0;
  for (const edge of ranked) {
    if (retainedWeight / Math.max(1, totalWeight) < sparseCoverage || edge.spine) {
      edge.sparse = true;
      retainedWeight += edge.weight;
    }
  }
  return aggregates;
}

source-traced: Visible view + hidden-edge accounting

Return GraphProjection with visible entities/containers/edges and explicit collapsed-edge and excluded-external accounting.

packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}

source-traced: Reproject after scope changes

Another layout request can project a different scope/collapse option set over the same indexed input.

packages/graph/src/layout.ts:385-396
export function createLayoutSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): LayoutSession {
  const session = createProjectionSession(graph, architecture);
  return Object.freeze({
    layout(optionsValue?: unknown): LayoutResult {
      const options = validateOptions(optionsValue);
      return layoutProjection(session.graphRef, session.project(options), options);
    },
  });
}
packages/graph/src/project.ts:376-438
export function createProjectionSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): ProjectionSession {
  assertGraphDocument(graph);
  validateArchitecture(graph.graphId, architecture);
  const snapshot: {
    graph: ProjectionGraph;
    architecture: ProjectionArchitecture;
  } = {
    graph: {
      graphId: graph.graphId,
      schemaVersion: graph.schemaVersion,
      repository: { ...graph.repository },
      nodes: graph.nodes.map((node) => ({
        ...node,
        identity: { ...node.identity },
      })),
      edges: graph.edges.map(({ id, sourceId, targetId, type }) => ({
        id,
        sourceId,
        targetId,
        type,
      })),
    },
    architecture: {
      version: architecture.version,
      graphId: architecture.graphId,
      rootContainerId: architecture.rootContainerId,
      scalePolicy: { ...architecture.scalePolicy },
      directoryContainers: architecture.directoryContainers.map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        childContainerIds: [...container.childContainerIds],
        memberNodeIds: [...container.memberNodeIds],
      })),
      stronglyConnectedComponents: architecture.stronglyConnectedComponents.map(
        (component) => ({
          id: component.id,
          memberNodeIds: [...component.memberNodeIds],
          collapsed: {
            id: component.collapsed.id,
            label: component.collapsed.label,
          },
        }),
      ),
      spineFindings: architecture.spineFindings.map(({ edgeId }) => ({ edgeId })),
    },
  };
  const index = indexGraph(snapshot.graph, snapshot.architecture);
  const project = (options?: unknown) => projectIndexedGraph(index, options);
  const graphRef = Object.freeze({
    graphId: snapshot.graph.graphId,
    schemaVersion: snapshot.graph.schemaVersion,
    ...(snapshot.graph.repository.revision === undefined
      ? {}
      : { revision: snapshot.graph.repository.revision }),
  });
  return Object.freeze({ graphRef, project });
}

source-traced: Updated inputs for node placement

Return a new visible view with provenance to the same source graph. The layout session then uses it for coordinate placement; refresh the session for new source evidence.

packages/graph/src/layout.ts:385-396
export function createLayoutSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): LayoutSession {
  const session = createProjectionSession(graph, architecture);
  return Object.freeze({
    layout(optionsValue?: unknown): LayoutResult {
      const options = validateOptions(optionsValue);
      return layoutProjection(session.graphRef, session.project(options), options);
    },
  });
}
packages/graph/src/project.ts:376-438
export function createProjectionSession(
  graph: unknown,
  architecture: ArchitectureDocument,
): ProjectionSession {
  assertGraphDocument(graph);
  validateArchitecture(graph.graphId, architecture);
  const snapshot: {
    graph: ProjectionGraph;
    architecture: ProjectionArchitecture;
  } = {
    graph: {
      graphId: graph.graphId,
      schemaVersion: graph.schemaVersion,
      repository: { ...graph.repository },
      nodes: graph.nodes.map((node) => ({
        ...node,
        identity: { ...node.identity },
      })),
      edges: graph.edges.map(({ id, sourceId, targetId, type }) => ({
        id,
        sourceId,
        targetId,
        type,
      })),
    },
    architecture: {
      version: architecture.version,
      graphId: architecture.graphId,
      rootContainerId: architecture.rootContainerId,
      scalePolicy: { ...architecture.scalePolicy },
      directoryContainers: architecture.directoryContainers.map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        childContainerIds: [...container.childContainerIds],
        memberNodeIds: [...container.memberNodeIds],
      })),
      stronglyConnectedComponents: architecture.stronglyConnectedComponents.map(
        (component) => ({
          id: component.id,
          memberNodeIds: [...component.memberNodeIds],
          collapsed: {
            id: component.collapsed.id,
            label: component.collapsed.label,
          },
        }),
      ),
      spineFindings: architecture.spineFindings.map(({ edgeId }) => ({ edgeId })),
    },
  };
  const index = indexGraph(snapshot.graph, snapshot.architecture);
  const project = (options?: unknown) => projectIndexedGraph(index, options);
  const graphRef = Object.freeze({
    graphId: snapshot.graph.graphId,
    schemaVersion: snapshot.graph.schemaVersion,
    ...(snapshot.graph.repository.revision === undefined
      ? {}
      : { revision: snapshot.graph.repository.revision }),
  });
  return Object.freeze({ graphRef, project });
}
packages/graph/src/project.ts:162-365
function projectIndexedGraph(
  index: ReturnType<typeof indexGraph>,
  optionsValue?: unknown,
): GraphProjection {
  const {
    graph,
    architecture,
    containers,
    tangles,
    tangleByCollapsedId,
    nodeById,
    ancestorsByNodeId,
    spineEdgeIds,
  } = index;
  const options = validateOptions(optionsValue);
  const memberNodeIds =
    options.memberNodeIds === undefined
      ? undefined
      : new Set(options.memberNodeIds);
  if (memberNodeIds) {
    for (const nodeId of memberNodeIds) {
      if (!nodeById.has(nodeId)) {
        throw new GraphEngineValidationError([
          {
            path: "$.memberNodeIds",
            message: `Unknown node identifier "${nodeId}".`,
          },
        ]);
      }
    }
  }
  const expanded = new Set(
    options.expandedContainerIds ?? [architecture.rootContainerId],
  );
  expanded.add(architecture.rootContainerId);
  const collapsedTangles = new Set(options.collapsedTangleIds ?? []);
  const includeExternal = options.includeExternal ?? true;
  const tangleByNodeId = new Map<string, string>();
  for (const tangleId of collapsedTangles) {
    const component = tangles.get(tangleId);
    if (!component) {
      throw new GraphEngineValidationError([
        {
          path: "$.collapsedTangleIds",
          message: `Unknown tangle identifier "${tangleId}".`,
        },
      ]);
    }
    for (const nodeId of component.memberNodeIds) {
      tangleByNodeId.set(nodeId, component.collapsed.id);
    }
  }

  const representativeByNodeId = new Map<string, string>();
  const hiddenExternalNodeIds: string[] = [];
  for (const node of graph.nodes) {
    if (memberNodeIds && !memberNodeIds.has(node.id)) continue;
    if (node.identity.kind === "external" && !includeExternal) {
      hiddenExternalNodeIds.push(node.id);
      continue;
    }
    const collapsedTangleId = tangleByNodeId.get(node.id);
    if (collapsedTangleId) {
      representativeByNodeId.set(node.id, collapsedTangleId);
      continue;
    }
    let representative = node.id;
    for (const containerId of ancestorsByNodeId.get(node.id) ?? []) {
      if (!expanded.has(containerId)) {
        representative = containerId;
        break;
      }
    }
    representativeByNodeId.set(node.id, representative);
  }

  const memberIdsByRepresentative = new Map<string, string[]>();
  for (const [nodeId, representative] of representativeByNodeId) {
    const members = memberIdsByRepresentative.get(representative) ?? [];
    members.push(nodeId);
    memberIdsByRepresentative.set(representative, members);
  }

  const visibleEntities: VisibleEntity[] = [];
  for (const [id, memberNodeIds] of memberIdsByRepresentative) {
    memberNodeIds.sort(compareText);
    const container = containers.get(id);
    const tangle = tangleByCollapsedId.get(id);
    const node = nodeById.get(id);
    visibleEntities.push({
      id,
      kind: container ? "container" : tangle ? "tangle" : "node",
      label: container
        ? container.label
        : tangle
          ? tangle.collapsed.label
          : nodeLabel(node!),
      memberNodeIds,
      external: memberNodeIds.every(
        (nodeId) => nodeById.get(nodeId)?.identity.kind === "external",
      ),
      collapsed: Boolean(container || tangle),
    });
  }
  visibleEntities.sort((left, right) => compareText(left.id, right.id));

  const edges = aggregateDirectedEdges(
    graph.edges,
    representativeByNodeId,
    spineEdgeIds,
    architecture.scalePolicy.sparseEdgeCoverage,
  ).filter((edge) => !options.sparseEdgesOnly || edge.sparse);
  const collapsedGroups = new Map<string, typeof graph.edges>();
  for (const edge of graph.edges) {
    const source = representativeByNodeId.get(edge.sourceId);
    const target = representativeByNodeId.get(edge.targetId);
    if (source === undefined || source !== target) continue;
    const members = collapsedGroups.get(source) ?? [];
    members.push(edge);
    collapsedGroups.set(source, members);
  }

  const relevantContainerIds =
    memberNodeIds === undefined
      ? undefined
      : new Set(
          [...representativeByNodeId.keys()].flatMap(
            (nodeId) => ancestorsByNodeId.get(nodeId) ?? [],
          ),
        );

  return {
    graphId: graph.graphId,
    viewId: options.viewId ?? "directory",
    visibleEntities,
    visibleContainers: architecture.directoryContainers
      .filter(
        (container) =>
          (relevantContainerIds === undefined ||
            relevantContainerIds.has(container.id)) &&
          (expanded.has(container.id) ||
            memberIdsByRepresentative.has(container.id)),
      )
      .map((container) => ({
        id: container.id,
        label: container.label,
        ...(container.parentId === undefined
          ? {}
          : { parentId: container.parentId }),
        collapsed: !expanded.has(container.id),
        childIds: sorted(
          new Set([
            ...container.childContainerIds.filter(
              (id) =>
                relevantContainerIds === undefined ||
                relevantContainerIds.has(id),
            ),
            ...container.memberNodeIds.flatMap((id) => {
              const representative = representativeByNodeId.get(id);
              return representative === undefined ? [] : [representative];
            }),
          ]),
        ),
      }))
      .sort((left, right) => compareText(left.id, right.id)),
    edges,
    collapsedEdgeAccounting: [...collapsedGroups.entries()]
      .map(([endpointId, memberEdges]) => {
        const directionGroups = new Map<string, string[]>();
        for (const edge of memberEdges) {
          const key = `${edge.sourceId}\0${edge.targetId}`;
          const ids = directionGroups.get(key) ?? [];
          ids.push(edge.id);
          directionGroups.set(key, ids);
        }
        return {
          endpointId,
          memberEdgeIds: memberEdges
            .map((edge) => edge.id)
            .sort(compareText),
          directions: [...directionGroups.entries()]
            .map(([key, edgeIds]) => {
              const [sourceId, targetId] = key.split("\0");
              return {
                sourceId: sourceId!,
                targetId: targetId!,
                edgeIds: edgeIds.sort(compareText),
              };
            })
            .sort(
              (left, right) =>
                compareText(left.sourceId, right.sourceId) ||
                compareText(left.targetId, right.targetId),
            ),
          edgeTypes: sorted(new Set(memberEdges.map((edge) => edge.type))),
          weight: memberEdges.length,
        };
      })
      .sort((left, right) => compareText(left.endpointId, right.endpointId)),
    hiddenExternalNodeIds: hiddenExternalNodeIds.sort(compareText),
    expandedContainerIds: sorted(expanded),
    collapsedTangleIds: sorted(collapsedTangles),
  };
}