Consolidate Assembly Definitions

---
name: consolidate-assembly-definitions
description: Use when merging, folding, renaming, or removing asmdef/asmref assemblies in this project — reducing assembly count, converting an .asmdef to an .asmref, moving code between assemblies, or reviewing assembly structure for redundant references and cycles.
---

# Consolidate Assembly Definitions

## Overview

Folding an assembly X into an anchor Y = delete `X.asmdef`, point an `.asmref` at Y (or nothing, if X's folder is inside Y's tree), retarget every reference. **Every merge must be cycle-simulated BEFORE touching files** — Unity forbids reference cycles and the transitive graph hides them. Verification gate = clean batch compile (never the full test suite).

Scripts live in `scripts/` next to this skill. Run `regen-graph.ps1` first — never trust stale assumptions about current references.

## Workflow

1. **Regen graph**: `scripts/regen-graph.ps1` → `graph.json` (refs resolved to names), `asmrefs.json`, `guidmap.txt`. Record the UNRESOLVED count (external packages — acceptance is "no NEW unresolved", not zero).
2. **Simulate**: `scripts/simulate-merge.ps1 -Anchor Y -Members X1,X2`. CYCLE → don't fold; check if folding the cycle-edge member *simultaneously* dissolves it (e.g. Backpack alone cycled via `RewardPanel → Backpack`; Backpack+RewardPanel together was clean).
3. **Fold**: `scripts/fold.py <plan.json>` (declarative `{folds:[{member,anchor}], renames:[{asmdef,newName}]}`). It deletes asmdef+meta, writes asmref+fresh-guid meta, retargets all referencing asmdefs/asmrefs, unions refs/unsafe/precompiled into the anchor.
4. **Reconcile by hand** (fold.py doesn't do these):
   - `csc.rsp`: delete member copies identical to the anchor's; if the anchor lacks one and a member had `-nullable:enable`, move it to the anchor folder. csc.rsp next to an `.asmref` is dead — Unity ignores it.
   - `InternalsVisibleTo`: grep for grants TO folded/renamed names → retarget. Grants inside folded folders move with the code (duplicates are legal).
   - Renames only: grep `link.xml` fullname entries, asmdef name-form refs, and serialized assets for `Type, OldAssemblyName` strings.
5. **Hygiene scan**: `scripts/scan-hygiene.py` — must report zero redundant asmrefs (ancestor already provides the same assembly) and zero code-less assembly folders. Delete empty folders entirely (+ folder .meta).
6. **Verify**: regen graph (expected count, no new unresolved, DFS cycle-free) + **batch compile only**: `Unity.exe -batchmode -quit -projectPath Explorer -logFile <log>`; zero `error CS` + "Exiting batchmode successfully". Editor must be closed. Do NOT run the EditMode suite.
7. One commit per fold group, concise bullets, skips documented with the blocking chain.
8. **Docs once at plan end** (not per iteration): refresh the layout tables + counts in `docs/directories-and-assemblies-structure.md`.

## Quick reference

| Situation | Action |
|---|---|
| Member folder's nearest ancestor assembly == the anchor | Delete member asmdef, **no asmref at all** |
| Nearest ancestor is a DIFFERENT assembly (or none) | asmref `{"reference": "GUID:<anchor-guid>"}` (GUID form = repo convention) — required even when physically nested under another assembly's tree |
| `Tests/`, `Systems/`, bus subfolders with own asmref | Excluded subtrees — keep them |
| Member has `defineConstraints` anchor lacks | `#if`-guard the sources first, or don't fold |
| Member unsafe, anchor not | Set anchor `allowUnsafeCode: true` |
| Renaming an anchor | Edit `name` field + `git mv` the file; GUID (meta) must not change |
| Reference "looks dead" by grep | Re-verify: namespaces span assemblies (`DCL.Ipfs` lives in DCL.Network) — compile is the proof |

## Hard rules (each cost a broken build or review round when violated)

- **Pick anchors by domain, not just by graph**: a clean cycle simulation is necessary, not sufficient. Read the member's source first — what is this code FOR? — then choose the anchor whose purpose matches (e.g. bootstrap/debug configuration belongs with `DCL.Platform`/app config, not with whatever assembly happens to share its references).
- **UPM package references are never a fold blocker**: packages (LiveKit, UniTask, …) are always leaves — they cannot reference project assemblies, so they cannot cycle and carrying one into an anchor is fine. Do not mirror package types or decouple package refs to "protect" an anchor; only PROJECT-assembly direction matters.
- **Preserve reusable leaves**: a natural leaf assembly (small, self-contained, several current or plausible future consumers across features) stays a leaf even when a fold simulates clean. Folding it into a fat anchor forces future consumers to take the anchor's whole tail, and splitting back out later is far costlier than keeping it now. Fold only terminal members — code consumed solely by the composition-root tier (DCL.Plugins/tests) or by exactly the anchor's own domain.
- **Lean leaves never merge upward**: Utility, DCL.Network, Web3, ECS, SceneRunner.Scene (incl. Realm), CRDT, Character, DCL.CharacterMotion.Components, DCL.Input, AssetsProvision (no domain-true anchor exists: Utility cycles via DCL.Network, Network/ECS.Unity are domain-distant - team-confirmed keep).
- **Production code must never reference DCL.Plugins** — only Playgrounds and tests may. If a fold target is DCL.Plugins and a production assembly consumes the member, pick another anchor.
- **Namespace shadowing**: after folds, namespaces like `DCL.Time`/`DCL.Chat` become visible to more code and shadow `UnityEngine.Time`/protobuf `Chat` inside `namespace DCL.*` blocks (CS0234/CS0118). Fix with full qualification (`UnityEngine.Time.` — repo idiom) or a using-alias **inside the namespace block** (file-level aliases lose to enclosing-namespace lookup).
- Known cycle-locked merges — do not re-attempt without decoupling first: Analytics+Implementation (`Flows → Profiles → Analytics`), Chat.History→Social (`RealmNavigation`), SceneLoadingScreens→Flows, SmartWearables→anything (`UI → SmartWearables`), Settings/MapRenderer→Social (`Backpack → Settings → Landscape`), Prefs→Platform, Hud↔Social one-way only.

## Red flags

- Creating an asmref without checking the nearest ancestor assembly first
- Folding before simulating ("the graph looked fine")
- Removing an asmdef reference because grep found no `using` (qualified usage, asmref-folded folders, namespace≠assembly)
- Running the 23k-test EditMode suite as a gate (compile is the gate; suite crashes batch mode)
- Leaving a folder whose only content is an asmref/asmdef