Skip to content

Architecture WS5: collocation decisions and first refactor(move) batch #3281

Description

@thymikee

Part of #3276.

Purpose

Static collocation analysis says declared zones do not match observed coupling: Louvain modularity 0.564 for detected communities vs 0.373 for declared zones; 48 files sit in a community that is ≥80% another zone. This issue drives the decision pass and lands the first unambiguous moves.

No blockers. Analysis baseline: ff685ad80. The full candidate list is in the umbrella issue body (section 5).

Required behavior

  1. Decision table: one row per candidate file in the umbrella list — move, merge, or keep with a one-line reason. Land it as docs/adr/ (or extend the architecture-ownership table if that is the owning declaration site).
  2. Land the first refactor(move) PR batch with the moves that need no design work:
    • src/sdk/limrun.ts, src/sdk/limrun-runtime-types.ts → provider-limrun
    • src/provider-limrun-runtime.ts → provider-limrun
    • capture-kit/src/durable-json.ts and the four capture-kit/src/capture-admission/*ledger.ts files → managed-allocation (per the candidate notes; re-verify direction against the current import graph before moving)
    • contracts/src/managed-device-allocation.ts → managed-allocation
  3. Moves are git mv + import fixes only (refactor(move)), each batch provable with git diff -M90% --stat (move-only PRs are exempt from the size budget). Update ownership tables/exports maps in the final chore(gates) commit.
  4. Where a move is refused, the decision row is the record; where a move is impossible because the target package has no seam, say so in the row and file nothing.

Done when

  • Every candidate in the umbrella list has a merged decision row.
  • The first move batch is merged and pnpm depgraph/layering gates are green; zone modularity is re-measured and reported (expect a small improvement; do not chase the number).
  • Remaining moves are enumerated as follow-up child issues or listed here as unchecked items.

Constraints

  • One command family/package group per PR; do not mix decisions with moves in a single commit.
  • Keep the public export surface stable: re-export from the old facade only if something outside the repo can observe it (fallow production-exports gate will tell you).
  • Follow docs/agents/pull-requests.md (size budget, commit shape, validation).

Follow-up checklist (post #3287 decision pass)

Activity

  1. thymikee commented on Oct 7, 2026

    @thymikee
    MemberAuthor

    Closure evidence: physical root-pass moves (#3294)

    All three outstanding root-pass moves have landed as refactor(move) PRs:

    File New location PR
    src/daemon-diagnostics-scope.ts src/daemon-contracts/daemon-diagnostics-scope.ts #3297
    src/runtime-command-surface.ts src/command-runtime/runtime-command-surface.ts #3299
    src/runtime-factory.ts src/command-runtime/runtime-factory.ts #3299

    Each file now lives inside a folder whose zone the layering graph already derives via topFolder, so the per-file ROOT_MODULE_ZONES rows are deleted (no new registry, per the bridge rule). rootModuleZoneDrift proves the declaration matches the tree after each row removal, and pnpm check:layering is green on both heads. Rename-only proofs via git diff -M90% --stat are recorded in each PR body. ADR 0033 rows updated to moved with links; #3294 closes when both PRs merge.

    Checking the checklist item above is left to a maintainer.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions