|
| 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 → managed-allocation, but capture-kit's session resources own the ledger's types and lifecycle, and `managed-allocation` already depends on `capture-kit` — the move would add a capture-kit→managed-allocation edge to an existing cycle (R4). | |
| 33 | +| `src/capture-admission/durable-capture-admission-ledger.ts` | keep | Same cycle: 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 | Same cycle; a four-line specialization of the ledger its own package owns. | |
| 35 | +| `src/capture-admission/screen-recording-admission-ledger.ts` | keep | Same cycle; consumed by capture-kit's screen-recording session resource and stop-recovery. | |
| 36 | +| `src/durable-json.ts` | keep | Proposed → managed-allocation, but `managed-allocation` already imports this module from capture-kit, so the edge cannot reverse without a package cycle. Considered a contracts home beside `json.ts` and rejected: contracts owns 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 | +Umbrella §4's root pass, #3288, resolves `(root)` by assigning every process-root module a |
| 120 | +logical zone in `scripts/layering/root-module-zones.ts` (`daemon-contracts` rank 2, |
| 121 | +`command-runtime` rank 3, `platform-runtime` rank 4, …) while leaving the files physically in |
| 122 | +place. That reclassification, not relocation, is the ownership decision: no collocation move |
| 123 | +remains for these files, and moving them into a consumer folder under `src/daemon/` would now be |
| 124 | +an R5 back-edge against their lowest-ranked importer. Each row below is therefore a keep citing |
| 125 | +its assigned zone as the ownership rationale — except the `platform-runtime-*` composition seams, |
| 126 | +where the only evidence checked is path-keyed (R13/R76), so those say "retain for this batch": |
| 127 | +the rules constrain a move, they do not prove the placement. The daemon ⇄ client shared files |
| 128 | +(`daemon-policy-file.ts`, `provider-credential-fingerprint.ts`, `request-progress-protocol.ts`) |
| 129 | +trace to #2559, which relocated the shared contracts **to the process root** so the client stops |
| 130 | +importing `src/daemon/` at all; R78 keeps any client→daemon edge at zero runtime and a five-line |
| 131 | +recorded type-only residue. Their root placement preserves that boundary — the rows name the |
| 132 | +mixed static/dynamic import kinds rather than claiming one kind. |
| 133 | + |
| 134 | +| File | Decision | Reason | |
| 135 | +| --- | --- | --- | |
| 136 | +| `src/daemon-diagnostics-scope.ts` | keep (reconsidered with #3288) | The batch-1 read "only daemon-server files import it" was incomplete: `daemon-registration-owner.ts` — a daemon ⇄ client shared contract statically importing it at line 25 — also reads the scope. #3288 assigns it `daemon-contracts` (rank 2); moving it under `src/daemon/` would make that importer a rank-2 → rank-4 R5 back-edge. The zone assignment is the ownership decision; no move remains. | |
| 137 | +| `src/daemon-policy-file.ts` | keep (reconsidered with #3288) | Daemon ⇄ client shared contract from #2559; #3288 assigns it `daemon-contracts` (rank 2), which is the shared-below-both placement the spine needs since daemon-client (rank 5) dynamically imports it. No relocation remains. | |
| 138 | +| `src/daemon.ts` | keep | Entry point (`internal/daemon` bundle entry); composition roots stay in root by umbrella §4. | |
| 139 | +| `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. | |
| 140 | +| `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. | |
| 141 | +| `src/platform-runtime-device-boot.ts` | retain for this batch | Same path-keyed R13/ADR 0022 seam. | |
| 142 | +| `src/platform-runtime-resource-cleanup.ts` | retain for this batch | Same path-keyed R13/ADR 0022 seam. | |
| 143 | +| `src/provider-credential-fingerprint.ts` | keep (reconsidered with #3288) | Daemon ⇄ client shared contract from the same #2559 decision as `daemon-policy-file.ts`; #3288 assigns it `platform-runtime` (rank 4), beside the provider composition that reads the credentials it fingerprints. | |
| 144 | +| `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. | |
| 145 | +| `src/request-progress-protocol.ts` | keep (reconsidered with #3288) | 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/`; #3288 assigns it `daemon-contracts` (rank 2), the shared zone below both readers, so only the R78 boundary matters. The wire-compat ledgers pin the framing here. Contracts was considered and R18 keeps contracts free of envelope validation mechanics. | |
| 146 | +| `src/runtime-command-surface.ts` | keep (reconsidered with #3288) | Imported by `src/runtime.ts` (statically) as well as daemon runtime modules; #3288 assigns it `command-runtime` (rank 3), and moving it under `src/daemon/` (rank 4) would make `src/runtime.ts` a rank-3 → rank-4 R5 back-edge. The zone assignment is the ownership decision; no move remains. | |
| 147 | +| `src/runtime-factory.ts` | keep (reconsidered with #3288) | Same: statically imported by `src/runtime.ts` and two daemon modules; assigned `command-runtime`, so `src/daemon/` is an R5 back-edge, not a destination. | |
| 148 | + |
| 149 | +### sdk |
| 150 | + |
| 151 | +| File | Decision | Reason | |
| 152 | +| --- | --- | --- | |
| 153 | +| `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. | |
| 154 | +| `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. | |
| 155 | + |
| 156 | +## Batch 1 (this decision's companion PR) |
| 157 | + |
| 158 | +- `packages/contracts/src/managed-device-allocation.ts` → `packages/managed-allocation/src/managed-device-allocation.ts` |
| 159 | + (new `@agent-device/managed-allocation/managed-device-allocation` subpath). |
| 160 | + |
| 161 | +Batch 1 is exactly this one file. The moves the issue listed beside it failed re-verification |
| 162 | +against the current import graph, and the rows above record why: the four admission ledgers and |
| 163 | +`durable-json.ts` hit the capture-kit ⇄ managed-allocation package cycle, and the three limrun |
| 164 | +files have no seam (published facade, public-type collision, root dependency factory). |
| 165 | + |
| 166 | +## Follow-ups (tracked on #3281) |
| 167 | + |
| 168 | +None outstanding. The root pass originally tracked here was resolved by #3288's logical-zone |
| 169 | +assignment (see the `(root)` section): the files keep their paths, the zone declaration is the |
| 170 | +ownership record, and reclassification alone is not counted as a collocation move — the rows |
| 171 | +record explicit keep/reconsidered decisions instead. |
| 172 | + |
| 173 | +## Refuted alternatives |
| 174 | + |
| 175 | +- **Move every ≥80% community match into its dominant zone.** Rejected: the measure is |
| 176 | + consumer-side. Foundations (host-kit, contracts, selectors, device-selection) score badly by |
| 177 | + construction, and reversing their edges inverts the spine. |
| 178 | +- **`durable-json.ts` → contracts.** Pure-JSON helpers looked like `contracts/json.ts` neighbors, |
| 179 | + but R18 holds contracts to wire vocabulary, and these functions are durable-descriptor |
| 180 | + persistence validation. Rejected. |
| 181 | +- **Ledgers → managed-allocation with capture-kit importing them back.** Rejected at once: it |
| 182 | + manufactures the package cycle that R4/R11 reject; managed-allocation's dependency on capture-kit |
| 183 | + is load-bearing (its record codec uses capture-kit durable mechanics). |
0 commit comments