Skip to content

Commit 2a09430

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 335a878 commit 2a09430

3 files changed

Lines changed: 185 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: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
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).

‎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)