NVIDIA / NVIDIA/NemoClaw

Refactor source boundaries to reduce dependency coupling

Open
#7,691 1 comment 0 reactions 1 assignee Claimed by @cv View on GitHub
area: architecture refactor
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

> [!IMPORTANT]
> Reserved for @cv. Do not self-assign this issue. Do not open an implementation PR unless @cv requests help.

## Problem

The source layout has command, action, domain, adapter, and state layers. Transitional folders now contain multiple product concepts and stack layers.

Current examples include:

- `src/lib/onboard/`: 358 production files and about 66,600 lines.
- `src/lib/actions/`: 227 production files and about 50,900 lines.
- `src/lib/state/registry.ts`: more than 100 production dependents.
- `src/lib/onboard.ts`: more than 200 direct runtime dependencies.
- Runtime dependency cycles cross actions, sandbox configuration, shields, messaging, policy, onboarding, and plugin entry code.

Large flat folders make ownership unclear. Broad modules increase change impact and test scope. Runtime cycles make module initialization order part of behavior.

## Desired outcome

Use feature ownership first. Use explicit layers inside each feature.

Keep these repository-wide layers:

- `src/commands/` for oclif command adapters.
- `src/composition/` for dependency wiring.
- `src/platform/` for Docker, OpenShell, process, filesystem, and HTTP adapters.
- `src/cli/` for CLI framework and presentation code.
- `src/foundation/` for dependency-light primitives.

Put product behavior under feature-owned modules such as onboarding, sandboxes, inference, messaging, policy, shields, sessions, MCP, and credentials.

## Constraints

- Preserve supported behavior and persisted data formats.
- Use compatibility exports only for current consumers.
- Do not add a new integration or product surface.
- Keep PRs issue-scoped and mechanically reviewable.
- Add guardrails before structural changes.
- Ratchet each measured hotspot downward.
- Keep runtime dependency graphs acyclic.
- Require cross-feature imports to use an explicit public module.

## Work sequence

1. Add dependency guardrails and baseline ratchets (#7692).
2. Remove bounded runtime dependency cycles (#7693).
3. Split the sandbox registry into narrow persistence seams (#7694).
4. Eliminate the remaining runtime dependency cycles (#7745).
5. Decompose onboarding into phase composition (#7695).
6. Move sandbox actions into feature-owned application modules (#7696).
7. Separate shipped runtime assets from contributor tooling (#7697).
8. Complete OpenClaw agent artifact co-location (#7698).
9. Reorganize integration tests by feature and contract (#7699).

Items 1 through 4 are complete. Item 5 is in progress.

Item 5 has these remaining phases:

- Extract messaging application ownership (#9170).
- Extract gateway lifecycle ownership (#9171).
- Extract provider selection and review ownership after the current gateway PR (#9169). PR #9037 resolved the prior dependency.
- Enforce the zero-decision entry boundary after #9169 (#9172).

Items 6 through 9 remain open.

## Completion criteria

- Guardrails report file fan-in, fan-out, cycles, and flat-folder counts.
- Ratchets prevent a measured hotspot from increasing.
- Runtime dependency cycles are absent from production TypeScript.
- High fan-in modules expose narrow and stable contracts.
- Composition roots contain dependency wiring and no product decisions.
- Transitional root-file counts decrease to zero or an approved remainder.
- Targeted tests and architecture checks pass for each PR.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.