RFC: split LoopX distributions inside the monorepo (loopx-core / loopx-workspace / capability packages) and pin top-level module growth

[huangruiteng]

Problem

The loopx wheel is one distribution that installs the kernel, the CLI, 33 built-in capabilities, the chat/workspace server, and the Python side of the TS effect runtime. On main@3e443ad7c:

• loopx/ top level: 143 flat *.py files / ~78.8k lines, including 37 chat_*.py modules and 9 *_goal_mode/ host packages next to the kernel.
• loopx/control_plane ≈131k lines, loopx/capabilities ≈115k lines, loopx/extensions ≈44k lines in one package.
• pyproject.toml declares dependencies = [] and describes "a lightweight ... control plane", but the effect runtime requires Node.js ≥ 22.22.3 for every install, including CLI-only or kernel-only use.
• Coupling is bidirectional: 52 kernel/CLI/top-level modules import loopx.capabilities; 74 capability modules import loopx.control_plane.
• packages/ already hosts 9 independently packaged extensions (loopx-finance-*, loopx-jev, loopx-obelisk, loopx-repo-health, ...), so the repository has two packaging conventions at once.

Effects: first-use installs pull everything; contributors cannot find module boundaries from the tree; the import-boundary tests protect control_plane inward edges but nothing stops the top level from growing.

Proposal (monorepo stays; distributions split)

Do not split the repository. Keep one repo and one PR/CI flow, especially while the TypeScript control-plane migration is in its transaction-cutover phase. Instead:

1. Top-level regrouping first (pure moves + compat re-exports): loopx/chat_*.py → loopx/chat/; loopx/*_goal_mode/ → loopx/hosts/; keep import paths working through re-export shims for at least one minor release.
2. Architecture test "top-level file count does not grow": alongside tests/architecture/test_control_plane_import_boundaries.py, pin the current count of loopx/*.py and only allow it to decrease.
3. Distributions: loopx-core (kernel + CLI + minimal host adapters; Node runtime declared as an optional extra or bundled), loopx-workspace (chat server, apps/presentation, desktop), and per-capability packages migrated into packages/ behind the existing CapabilityRegistry provider boundary.
4. Package graduation to separate repos is explicitly out of scope until the kernel migration is complete and a package has its own maintainers.

Acceptance sketch

• pip install loopx-core on a clean machine without Node succeeds and loopx --help / read-only status work; effect-runtime commands report a typed node_unavailable diagnostic instead of failing at import time.
• loopx/*.py count is pinned and decreasing; the architecture test fails on any new top-level module.
• Existing import loopx.chat_server style imports keep working for one minor release with a deprecation note.
• Capability packages moved to packages/ install/uninstall independently and off-state preserves core behavior (same rule as existing extensions).

RFC PR: #5073

[karenchuu]

Picking up M0 of docs/architecture/rfcs/monorepo-distribution-split-v0.md (the budget fixture plus the guard test, per Section 5 and the Section 9 row "Top-level module count never grows"): PR #5191.

Two facts measured at the current base that the RFC's own re-measurement note asks for:

• ls loopx/*.py | wc -l is 147 on 9eaacfbf2, not the 148 in the Section 5 example, so test(architecture): pin the top-level module count before it grows again #5191 pins 147 — pinning 148 would admit one more top-level module on arrival.
• The surface is still moving: 66 distinct top-level modules were added in the 45 days before that base, 6 of them in the last 7 days.

M1/M2 (the chat_* and *_goal_mode regroupings) are untouched here; each of them now has a number it must lower in the same PR. D1-D4 and M3+ stay with you.