Skip to content

Commit 2b77678

Browse files
committed
docs(adr): decision table for the umbrella collocation candidates
One row per file in #3276 section 5: move, merge, or keep with the checked direction that fails. Batch 1 moves only the managed-device allocator contract into managed-allocation; the limrun files have no seam and the capture-kit ledger moves would invert an existing package edge. ADR 0021's contract link follows the moved file.
1 parent 64a850b commit 2b77678

3 files changed

Lines changed: 193 additions & 1 deletion

File tree

‎docs/adr/0021-host-simlock-managed-device-allocation.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Accepted (2026-09-01; scope amended 2026-10-01). This ADR defines the minimal Ho
66
[Simlock #70](https://github.com/callstackincubator/simlock/issues/70) tracks allocator-side work;
77
the supported client contract and conformance tests enforce the boundary.
88

9-
Implementation alignment is pending: the [managed-device allocator contract](../../packages/contracts/src/managed-device-allocation.ts)
9+
Implementation alignment is pending: the [managed-device allocator contract](../../packages/managed-allocation/src/managed-device-allocation.ts)
1010
still requires `supersedeLeaseRequest`, `confirmLeaseActivation`, `getManagedIdentityStatus`,
1111
and `acknowledgeManagedIdentityRemoval`, and exposes `activation: 'external-fence'`. Host implementation
1212
must trim those requirements, their consumers/tests, and Android reuse documentation to this scope.
Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
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.

‎docs/adr/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
3333
| [0029 Daemon Policy](0029-daemon-policy.md) | `AGENT_DEVICE_DAEMON_POLICY`, confining a daemon's commands, devices, or device shutdown, and where operator rules are enforced for batch/replay steps |
3434
| [0030 Process Lock Exclusion](0030-process-lock-exclusion.md) | process-lock publication/reclaim/release, retained mutation guards, and the single-protocol upgrade boundary |
3535
| [0031 macOS Native App Backend](0031-macos-native-app-backend.md) | `AGENT_DEVICE_MACOS_APP_BACKEND`, driving macOS app sessions without XCTest Automation Mode, why pointer actions are accessibility actions only, and the ghost cursor |
36+
| [0033 Collocation decision table](0033-collocation-decision-table.md) | moving or adding a file listed in umbrella #3276 §5, re-proposing a move that table refused, reading a zone's collocation decisions |
3637

3738
ADRs record *why*; the registries and gates they describe are the living source of truth — when
3839
prose and a registry disagree, the registry wins and the ADR needs a follow-up.

0 commit comments

Comments
 (0)