|
| 1 | +# 0033. Collocation decision table |
| 2 | + |
| 3 | +Status: accepted. Decision pass over the 48 candidate files listed in umbrella issue #3276 §5 |
| 4 | +(communities detected at `ff685ad80`: declared zones score 0.373 Louvain modularity versus 0.564 |
| 5 | +for detected communities). One row per candidate: `move`, `merge`, or `keep`, with the reason. |
| 6 | +Moves land as `refactor(move)` PRs; batch 1 is the companion PR to this decision. |
| 7 | + |
| 8 | +## Rules at a glance |
| 9 | + |
| 10 | +- A `keep` row is a decision, not a punt: the reason names the direction that was checked and why |
| 11 | + it fails (usually a package cycle or a spine inversion). |
| 12 | +- The detected community is not itself a reason to move. Most candidates sit in a consumer's |
| 13 | + community precisely because they are shared foundations; the table records where the module |
| 14 | + **can** live, which is often where it already lives. |
| 15 | +- Moves only count when the target has a real seam: no new dependency direction, no root |
| 16 | + composition pulled into a package, and the file's own imports come along unchanged. Where the |
| 17 | + proposal was infeasible, the row records that, and no issue is filed to re-propose it. |
| 18 | +- A path-keyed rule (R13's importer lists, R76's inventory, R78's scope) describes today's seam, |
| 19 | + not proof that a placement is best. A row whose only evidence is such a rule says |
| 20 | + "retain for this batch — relocation requires coordinated ownership changes" instead of resting |
| 21 | + the placement on the rule's path. A package cycle rejects the proposed direction, not every |
| 22 | + future design that first removes the edge closing it. |
| 23 | +- Rows marked `move (batch N)` are tracked as unchecked items on #3281; batch 1 is this decision's |
| 24 | + companion `refactor(move)` PR. |
| 25 | + |
| 26 | +## Decision table |
| 27 | + |
| 28 | +### capture-kit |
| 29 | + |
| 30 | +| File | Decision | Reason | |
| 31 | +| --- | --- | --- | |
| 32 | +| `src/capture-admission/audio-probe-admission-ledger.ts` | keep (proposed move rejected) | The proposed → managed-allocation move would add a capture-kit→managed-allocation edge while `managed-allocation` already depends on `capture-kit`, completing a package cycle (R4). That rejects this direction; a future design that first removes the edge closing the cycle (e.g. moving the record codec off capture-kit) is not excluded by this row. | |
| 33 | +| `src/capture-admission/durable-capture-admission-ledger.ts` | keep (proposed move rejected) | Same rejected direction: it is the generic engine the three per-resource ledgers specialize, consumed by `durable-capture-resource.ts` and `durable-capture-start-preflight.ts` inside capture-kit. | |
| 34 | +| `src/capture-admission/perf-capture-admission-ledger.ts` | keep (proposed move rejected) | Same rejected direction; a four-line specialization of the ledger its own package owns. | |
| 35 | +| `src/capture-admission/screen-recording-admission-ledger.ts` | keep (proposed move rejected) | Same rejected direction; consumed by capture-kit's screen-recording session resource and stop-recovery. | |
| 36 | +| `src/durable-json.ts` | keep (proposed move rejected) | `managed-allocation` already imports this module from capture-kit, so the proposed direction cannot reverse without completing a package cycle; a design that removes that import first stays open. Considered a contracts home beside `json.ts` and rejected on ownership grounds: contracts is wire vocabulary (R18), not durable-descriptor validation mechanics. The coupling the community saw is the three managed-allocation `record-*` consumers; they can stay. | |
| 37 | +| `src/snapshot/snapshot-evidence.ts` | keep | Snapshot-capture mechanics; the daemon-dominated community is consumer-side, and moving it into daemon-server would force every platform and provider onto the daemon zone for capture evidence. | |
| 38 | +| `src/snapshot/snapshot-freshness/index.ts` | keep | Same: platform-neutral freshness policy its consumers (capture-kit itself, platforms, daemon) all import downward today. | |
| 39 | +| `src/snapshot/touch-reference-frame.ts` | keep | Snapshot-geometry mechanics used by interaction and capture alike; capture-kit is the only zone below both. | |
| 40 | + |
| 41 | +### contracts |
| 42 | + |
| 43 | +contracts is the rank-1 shared-vocabulary zone. Each candidate below that stays has dependents in |
| 44 | +two or more higher-ranked zones, so no single consumer zone can own it without inverting the spine |
| 45 | +(R5). The one move row is the counter-case: its dependents all sit in one consumer zone that |
| 46 | +already owns the operations behind the vocabulary. |
| 47 | + |
| 48 | +| File | Decision | Reason | |
| 49 | +| --- | --- | --- | |
| 50 | +| `src/android-observation.ts` | keep | Vocabulary read by capture-kit, platform-android, and daemon-server; contracts is the only zone below all three. | |
| 51 | +| `src/android-system-chrome.ts` | keep | Same three-way split (capture-kit, platform-android, daemon-server). | |
| 52 | +| `src/app-events.ts` | keep | Event vocabulary shared by commands, daemon, and platforms. | |
| 53 | +| `src/app-state.ts` | keep | Broad fan-in app-state vocabulary; any consumer-side home would rank it above the others. | |
| 54 | +| `src/device-boot.ts` | keep | Boot-phase vocabulary for device-selection, platforms, and daemon-server. | |
| 55 | +| `src/facades/device.ts` | keep | Published facade of the contracts package; facades are the package boundary, not movable content. | |
| 56 | +| `src/interaction-guarantees.ts` | keep | AGENTS.md names this file as the declaration site for interaction dispatch paths and guarantee cells (ADR 0011); the cross-language golden tables under `contracts/fixtures/` bind it to this package. | |
| 57 | +| `src/managed-device-allocation.ts` | move (batch 1) → `packages/managed-allocation` | The port and its vocabulary ([ADR 0021](0021-host-simlock-managed-device-allocation.md) §3) are consumed only by managed-allocation and the daemon composition that already depends on that package; no other contracts file or zone imports it, so the types land beside the operations that implement them. | |
| 58 | +| `src/wait-runtime-plan.ts` | keep | Shared by command-registry and daemon-server; both are spine zones and contracts is the only seam below them. | |
| 59 | + |
| 60 | +### device-selection |
| 61 | + |
| 62 | +| File | Decision | Reason | |
| 63 | +| --- | --- | --- | |
| 64 | +| `src/device-inventory-context.ts` | keep | Rank-1 selection engine imported by daemon-server, remote, and replay adapters; the daemon-heavy community is its largest consumer, not its owner. | |
| 65 | +| `src/device-selection-resolver.ts` | keep | Same — moving it up would rank it above its other consumers (replay-port, cli). | |
| 66 | +| `src/dispatch-resolve.ts` | keep | Dispatch resolution is shared by the daemon gateway and the daemonless CLI paths; only the rank-1 zone sits below both. | |
| 67 | +| `src/open-target.ts` | keep | Open-target vocabulary consumed across daemon, remote, and CLI. | |
| 68 | + |
| 69 | +### host-kit |
| 70 | + |
| 71 | +| File | Decision | Reason | |
| 72 | +| --- | --- | --- | |
| 73 | +| `src/diagnostics.ts` | keep | The diagnostics seam every zone imports (AGENTS.md mandates it); highest fan-in in the repo is what a substrate looks like, not misplacement. | |
| 74 | +| `src/internal/request-cancel.ts` | keep | Request-cancellation mechanics AGENTS.md routes to `host-kit/request`; internal beside its facade is already the collocation. | |
| 75 | +| `src/request.ts` | keep | Cross-layer request contracts AGENTS.md names as a host-kit seam; consumers span every zone. | |
| 76 | +| `src/session-paths.ts` | keep | Session-artifact path grammar the daemon, cli, and platforms all resolve; AGENTS.md keeps the path *policy* in `src/daemon/session-artifact-paths.ts`, which consumes this. | |
| 77 | + |
| 78 | +### kernel |
| 79 | + |
| 80 | +| File | Decision | Reason | |
| 81 | +| --- | --- | --- | |
| 82 | +| `src/device-isolation.ts` | keep | Device-isolation vocabulary below device-selection, replay-port, and daemon; kernel is the only zone beneath all of them. | |
| 83 | + |
| 84 | +### platform-android |
| 85 | + |
| 86 | +| File | Decision | Reason | |
| 87 | +| --- | --- | --- | |
| 88 | +| `src/device-boot.ts` | keep | Boot mechanics the platform owns per ADR 0019/R13; the root-zone consumers are the composition root loading its own platform packages. | |
| 89 | + |
| 90 | +### platform-apple |
| 91 | + |
| 92 | +| File | Decision | Reason | |
| 93 | +| --- | --- | --- | |
| 94 | +| `src/runner-owner-facade.ts` | keep | ADR 0005 runner-owner seam; R13 owns the platform package's composition exports and the root importer is the designated host. | |
| 95 | +| `src/runner/legacy-xctest-device-set.ts` | keep | Runner-internal legacy device-set parsing beside the runner it serves. | |
| 96 | +| `src/simulator-boot.ts` | keep | Simulator boot mechanics are platform authority (ADR 0009); the kernel device model and xctestrun preparation must stay in sync with it in this package. | |
| 97 | + |
| 98 | +### replay-port |
| 99 | + |
| 100 | +| File | Decision | Reason | |
| 101 | +| --- | --- | --- | |
| 102 | +| `src/daemon-port/session-test-shard-devices.ts` | keep | Already collocated: it is the daemon-port adapter binding shard enumeration, and `replay-test` (the scheduler) deliberately never enumerates hardware — moving it toward that zone would break the port. | |
| 103 | + |
| 104 | +### selectors |
| 105 | + |
| 106 | +| File | Decision | Reason | |
| 107 | +| --- | --- | --- | |
| 108 | +| `src/parameterized-recorded-fill.ts` | keep | ADR 0017 recorded-input mechanics; selector parsing/matching is centralized in this package by AGENTS.md. | |
| 109 | +| `src/target-evidence.ts` | keep | Target-evidence vocabulary shared by daemon replay and selectors matching; selectors is below both. | |
| 110 | + |
| 111 | +### cli |
| 112 | + |
| 113 | +| File | Decision | Reason | |
| 114 | +| --- | --- | --- | |
| 115 | +| `src/cli/commands/device-release.ts` | keep | Command surface belongs in `cli` by the folder spine; the daemon device-claim modules it reuses are already extracted, so what remains is thin daemonless-CLI composition. | |
| 116 | + |
| 117 | +### (root) |
| 118 | + |
| 119 | +`#3288` assigns every process-root module a logical zone in |
| 120 | +`scripts/layering/root-module-zones.ts` (`daemon-contracts` rank 2, `command-runtime` rank 3, |
| 121 | +`platform-runtime` rank 4, …) while leaving the files physically in place. Per the maintainer |
| 122 | +design decision, that reclassification is **not** completed collocation: the physical moves for |
| 123 | +`daemon-diagnostics-scope.ts`, `runtime-command-surface.ts`, and `runtime-factory.ts` remain |
| 124 | +outstanding and are tracked as #3294 (child of #3276). The other rows below are keeps: the |
| 125 | +daemon ⇄ client shared files (`daemon-policy-file.ts`, `provider-credential-fingerprint.ts`, |
| 126 | +`request-progress-protocol.ts`) trace to #2559, which relocated the shared contracts **to the |
| 127 | +process root** so the client stops importing `src/daemon/` at all; R78 keeps any client→daemon |
| 128 | +edge at zero runtime and a five-line recorded type-only residue, and #3288's `daemon-contracts` |
| 129 | +zone is the declaration of that shared-below-both ownership. Rows on path-keyed evidence alone |
| 130 | +(the `platform-runtime-*` seams) say "retain for this batch": a guard's current path lists |
| 131 | +constrain a relocation, they are not independent proof the placement is optimal. |
| 132 | + |
| 133 | +| File | Decision | Reason | |
| 134 | +| --- | --- | --- | |
| 135 | +| `src/daemon-diagnostics-scope.ts` | move (outstanding, #3294) | Confirmed as an outstanding physical move, not reconsidered. Importers: `daemon/server/daemon-runtime.ts` and `daemon-registration-owner.ts` (static, line 25). #3288's `daemon-contracts` assignment classifies it only; #3294 owns the physical move and the row deletion from `ROOT_MODULE_ZONES`. | |
| 136 | +| `src/daemon-policy-file.ts` | keep | Daemon ⇄ client shared contract from #2559, declared `daemon-contracts` by #3288 — the shared-below-both ownership the spine needs, since daemon-client (rank 5) dynamically imports it. | |
| 137 | +| `src/daemon.ts` | keep | Entry point (`internal/daemon` bundle entry); composition roots stay in root by umbrella §4. | |
| 138 | +| `src/platform-runtime-apple-runner-owner.ts` | retain for this batch | `platform-runtime-*` composition seam: R13's exact-importer rule and the ADR 0022 R76 inventory key on its path, so relocation requires coordinated ownership changes to both declarations — the rules constrain the move, they do not independently prove the placement. | |
| 139 | +| `src/platform-runtime-daemon-lifecycle.ts` | retain for this batch | Same path-keyed R13/ADR 0022 seam: relocation is possible only with coordinated changes to those declarations. | |
| 140 | +| `src/platform-runtime-device-boot.ts` | retain for this batch | Same path-keyed R13/ADR 0022 seam. | |
| 141 | +| `src/platform-runtime-resource-cleanup.ts` | retain for this batch | Same path-keyed R13/ADR 0022 seam. | |
| 142 | +| `src/provider-credential-fingerprint.ts` | keep | Daemon ⇄ client shared contract from the same #2559 decision as `daemon-policy-file.ts`; #3288 declares its zone beside the provider composition that reads the credentials it fingerprints. | |
| 143 | +| `src/provider-limrun-runtime.ts` | keep | Proposed → provider-limrun, but there is no seam: the class's constructor self-builds the root dependency factory (`src/sdk/limrun-runtime-dependencies.ts`), which is the ADR 0019 composition seam — it loads the root's adb-host binder, core Android interactor, and platform-runtime app-state helpers that the package must not import. Moving the class means moving that composition, which is design, not a move. | |
| 144 | +| `src/request-progress-protocol.ts` | keep | Daemon ⇄ client shared contract from the same #2559 decision — the client reads it statically (`daemon-client-progress.ts`) and the server through `src/daemon/server/`, so only #2559's shared-placement boundary and the wire-compat ledgers pin it; declared `daemon-contracts` by #3288. Contracts was considered and R18 keeps contracts free of envelope validation mechanics. | |
| 145 | +| `src/runtime-command-surface.ts` | move (outstanding, #3294) | Confirmed as an outstanding physical move, not reconsidered. Importers: `src/runtime.ts` (static) and daemon runtime modules; #3288's `command-runtime` assignment classifies it only — #3294 owns the physical move and the `ROOT_MODULE_ZONES` row deletion. | |
| 146 | +| `src/runtime-factory.ts` | move (outstanding, #3294) | Same: statically imported by `src/runtime.ts` and two daemon modules; outstanding physical move tracked by #3294. | |
| 147 | + |
| 148 | +### sdk |
| 149 | + |
| 150 | +| File | Decision | Reason | |
| 151 | +| --- | --- | --- | |
| 152 | +| `src/sdk/limrun.ts` | keep | The published `agent-device/limrun` facade: `tsdown.config.ts` builds it as the bundle entry and `package.json#exports` ships `dist/src/limrun.js`. A published facade cannot live in a private workspace package. | |
| 153 | +| `src/sdk/limrun-runtime-types.ts` | keep | The public session-type refinement (provider session with the platform `AndroidAdbProvider` types swapped in) exists precisely because the published surface differs from the package-internal one, whose identical names it `Omit`s. Relocating it into provider-limrun requires renaming or dual-exporting the internal types — design, not a move. | |
| 154 | + |
| 155 | +## Batch 1 (this decision's companion PR) |
| 156 | + |
| 157 | +- `packages/contracts/src/managed-device-allocation.ts` → `packages/managed-allocation/src/managed-device-allocation.ts` |
| 158 | + (new `@agent-device/managed-allocation/managed-device-allocation` subpath). |
| 159 | + |
| 160 | +Batch 1 is exactly this one file. The moves the issue listed beside it failed re-verification |
| 161 | +against the current import graph, and the rows above record why: the four admission ledgers and |
| 162 | +`durable-json.ts` hit the capture-kit ⇄ managed-allocation package cycle, and the three limrun |
| 163 | +files have no seam (published facade, public-type collision, root dependency factory). |
| 164 | + |
| 165 | +## Follow-ups (tracked on #3281) |
| 166 | + |
| 167 | +- Physical root-pass moves remain **outstanding** per the maintainer design decision: |
| 168 | + `daemon-diagnostics-scope.ts`, `runtime-command-surface.ts`, and `runtime-factory.ts` move |
| 169 | + under [#3294](https://github.com/callstack/agent-device/issues/3294) (child of #3276). |
| 170 | + #3288's zone assignments classify these files; reclassification is not completed collocation. |
| 171 | + |
| 172 | +## Refuted alternatives |
| 173 | + |
| 174 | +- **Move every ≥80% community match into its dominant zone.** Rejected: the measure is |
| 175 | + consumer-side. Foundations (host-kit, contracts, selectors, device-selection) score badly by |
| 176 | + construction, and reversing their edges inverts the spine. |
| 177 | +- **`durable-json.ts` → contracts.** Pure-JSON helpers looked like `contracts/json.ts` neighbors, |
| 178 | + but R18 holds contracts to wire vocabulary, and these functions are durable-descriptor |
| 179 | + persistence validation. Rejected. |
| 180 | +- **Ledgers → managed-allocation with capture-kit importing them back.** Rejected as proposed: it |
| 181 | + completes the cycle that R4/R11 reject while managed-allocation's dependency on capture-kit is |
| 182 | + load-bearing (its record codec uses capture-kit durable mechanics). Removing that load-bearing |
| 183 | + import first would reopen the question — this row refuses the sequence, not the destination. |
| 184 | + |
| 185 | +## The enduring rule |
| 186 | + |
| 187 | +Collocation is judged by ownership: the placement that minimizes independently maintained |
| 188 | +declarations per change. Dependency-community scores only identify candidates; a guard's current |
| 189 | +path lists (R13, R76, R78) are constraints a relocation must account for, never independent |
| 190 | +evidence that a location must stay. A keep that cannot cite ownership, only a path, is marked |
| 191 | +"retain for this batch" so the next pass re-opens it rather than inheriting it as settled. |
0 commit comments