refactor: Separate package graph node assembly

[anthonyshew]

Why this PR exists

PackageGraphBuilder currently owns two different jobs at the same time:

1. Observe native repository state: discover workspaces, parse manifests, resolve package-manager behavior, and prepare package metadata.
2. Maintain graph structure: create the root/sentinel nodes, insert package nodes, reject duplicate names, and keep the package map, petgraph nodes, and lookup indexes synchronized.

That coupling is manageable while PackageJson is the source of package identity and paths. It becomes a blocker for the next PR, where parser-neutral repository knowledge must become authoritative. If we introduce that knowledge directly into the existing builder, the same change would simultaneously alter discovery, package identity, path ownership, duplicate handling, and graph mutation. A regression would be difficult to localize, and reviewers could not tell whether changed graph output came from the new observation model or from rewritten graph assembly.

We need a narrow boundary where already-observed package facts can be handed to graph-owned code:

Before

native discovery + manifest parsing + package facts + graph invariants
                         all inside BuildState

After this PR

native discovery + manifest parsing
                |
                v
     package facts / compatibility payload
                |
                v
      PackageGraphAssembler
      - root and sentinel setup
      - package node insertion
      - duplicate validation
      - lookup/index maintenance

The next PR can therefore replace the source of package facts without also redesigning how graph nodes are assembled. This is the strangler seam: new repository knowledge will feed the assembler, while graph topology remains core-owned and behaviorally unchanged.

Why these fields move together

The package map, petgraph graph, root indexes, and node lookup are one invariant set. Adding a package must update all of them together; otherwise graph traversal and package lookup can disagree. PackageGraphAssembler gives that invariant one owner instead of leaving the fields directly mutable throughout BuildState.

It also makes the distinction between these two existing concepts explicit in one place:

• PackageNode::Root: the graph implementation sentinel.
• PackageNode::Workspace(PackageName::Root): the root execution scope.

That distinction matters once repository roots, package roots, and aggregate scopes become separate knowledge concepts.

What changes

This PR extracts a private, graph-owned assembler responsible for:

• Root and root-workspace node initialization.
• Structural root edge creation.
• Package node insertion.
• Duplicate package-name diagnostics.
• Capacity reservation and lookup-table maintenance.
• Returning the assembled graph state when construction finishes.

BuildState remains the caller, so construction order and graph output remain unchanged.

What deliberately does not change

This is a mechanical prerequisite, not the package-knowledge cutover. It does not change:

• Workspace discovery.
• Manifest parsing or PackageJson compatibility data.
• Package identity or path semantics.
• Dependency splitting or relationship edges.
• Package-manager or lockfile behavior.
• External dependency closure calculation.
• Filtering, task graph, hashing, caching, watch, or prune behavior.

The temporary PackageInfo payload is still present here. The following PR changes package identity/path authority to parser-neutral repository knowledge; doing that here would defeat the purpose of separating the two independently reviewable moves.

Review guidance

The expected result is structural equivalence. Useful review questions are:

• Are root/sentinel nodes and their structural edge initialized exactly once?
• Does every package insertion update the package map, graph, and node lookup together?
• Are duplicate diagnostics preserved?
• Did relationship and lockfile logic remain in its previous phase?
• Does finish() transfer the same graph-owned state into PackageGraph?

Stack: #13440 -> #13441 -> #13442 -> #13447 -> #13448 -> #13443

Testing Instructions

• cargo test -p turborepo-repository
• cargo lint
• pnpm run format

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
examples-basic-web	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-designsystem-docs	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-gatsby-web	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-kitchensink-blog	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-nonmonorepo	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-svelte-web	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-tailwind-web	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
examples-vite-web	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm
turbo-site	Ready	Preview, Comment, Open in v0	Jul 23, 2026 4:56pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
turborepo-eve-agent	Skipped	Open in v0	Jul 23, 2026 4:56pm