Skip to content

Commit 18b09ef

Browse files
committed
docs(adr): restore the frozen meaning in ADR 0033
Restore "seam" wherever the base used it; "boundary" stays only where the base used it. Restore that contracts holds wire vocabulary under R18, that exports", path-keyed rules as examples of a class, the rejected proposal as a hypothetical, and "the next pass re-opens it". Keep the Follow-ups deletion: #3281 and #3294 are closed and every listed move landed, so the suggested "moves continue under #3294" would be wrong.
1 parent 43f7f5c commit 18b09ef

1 file changed

Lines changed: 35 additions & 32 deletions

File tree

‎docs/adr/0033-collocation-decision-table.md‎

Lines changed: 35 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,16 @@ Re-evaluate those files against their remaining edges.
1818
- A `keep` row records a decision.
1919
Its rationale identifies the examined direction and why it fails, usually a package cycle or spine inversion.
2020
- A detected community does not independently justify a move.
21-
Shared foundations often belong to their consumer's detected community.
21+
Most candidates belong to a consumer's detected community because they are shared foundations.
2222
The table records valid ownership locations, often the existing locations.
23-
- A move requires an actual target boundary.
23+
- A move counts only when the target has a real seam.
2424
It introduces no new dependency direction, moves no root composition into a package, and preserves the file's imports.
25-
If a proposal is infeasible, record that result without an issue to propose it again.
26-
- Path-keyed R13 importer lists, R76 inventory, and R78 scope describe existing boundaries.
27-
They do not prove optimal placement.
25+
If a proposal was infeasible, the row records that.
26+
No issue is filed to propose it again.
27+
- A path-keyed rule, for example R13's importer lists, R76's inventory, or R78's scope, describes today's seam.
28+
It does not prove that a placement is best.
2829
If a row has only path evidence, mark it "retain for this batch — relocation requires coordinated ownership changes".
29-
A package cycle rejects that proposed direction.
30+
A package cycle rejects the proposed direction.
3031
It does not prohibit a future design that first removes the cycle-closing edge.
3132

3233
## Decision table
@@ -35,11 +36,11 @@ Re-evaluate those files against their remaining edges.
3536

3637
| File | Decision | Reason |
3738
| --- | --- | --- |
38-
| `src/capture-admission/audio-probe-admission-ledger.ts` | keep (proposed move rejected) | The proposed move to managed-allocation adds capture-kit→managed-allocation. The reverse dependency already exists, so this forms an R4 package cycle. This rejects the direction, not a future design that first removes the cycle-closing edge. Moving the record codec off capture-kit is one example. |
39+
| `src/capture-admission/audio-probe-admission-ledger.ts` | keep (proposed move rejected) | The proposed move to managed-allocation would add a capture-kit→managed-allocation edge. The reverse dependency already exists, so this forms an R4 package cycle. This rejects the direction, not a future design that first removes the cycle-closing edge. Moving the record codec off capture-kit is one example. |
3940
| `src/capture-admission/durable-capture-admission-ledger.ts` | keep (proposed move rejected) | The same direction is rejected. This generic engine serves three per-resource ledgers. Capture-kit's `durable-capture-resource.ts` and `durable-capture-start-preflight.ts` consume it. |
40-
| `src/capture-admission/perf-capture-admission-ledger.ts` | keep (proposed move rejected) | The same direction is rejected. This four-line specialization belongs beside its package-owned ledger. |
41+
| `src/capture-admission/perf-capture-admission-ledger.ts` | keep (proposed move rejected) | The same direction is rejected. This file is a four-line specialization of the ledger that its own package owns. |
4142
| `src/capture-admission/screen-recording-admission-ledger.ts` | keep (proposed move rejected) | The same direction is rejected. Capture-kit's screen-recording session resource and stop-recovery consume it. |
42-
| `src/durable-json.ts` | keep (proposed move rejected) | Managed-allocation already imports this capture-kit module. Reversal forms a package cycle unless that import disappears first. Contracts beside `json.ts` was also rejected: R18 owns wire vocabulary, not durable-descriptor validation mechanics. Three managed-allocation `record-*` consumers explain the community coupling and can remain. |
43+
| `src/durable-json.ts` | keep (proposed move rejected) | Managed-allocation already imports this capture-kit module. Reversal forms a package cycle unless that import disappears first. Contracts beside `json.ts` was also rejected: under R18, contracts holds wire vocabulary, not durable-descriptor validation mechanics. Three managed-allocation `record-*` consumers explain the community coupling and can remain. |
4344
| `src/snapshot/snapshot-evidence.ts` | keep | This is snapshot-capture mechanics. The daemon-dominated community represents consumers. A daemon-server home would force every platform and provider to depend on the daemon zone for capture evidence. |
4445
| `src/snapshot/snapshot-freshness/index.ts` | keep | This is platform-neutral freshness policy. Capture-kit, platforms, and daemon currently import it downward. |
4546
| `src/snapshot/touch-reference-frame.ts` | keep | Interaction and capture share these snapshot-geometry mechanics. Only capture-kit is below both. |
@@ -60,9 +61,9 @@ All its consumers occupy one zone that already owns the operations represented b
6061
| `src/app-state.ts` | keep | Many zones consume this app-state vocabulary. Any consumer-side home would place it above other consumers. |
6162
| `src/device-boot.ts` | keep | Device-selection, platforms, and daemon-server consume this boot-phase vocabulary. |
6263
| `src/facades/device.ts` | keep | This published contracts facade defines the package boundary. It is not movable implementation content. |
63-
| `src/interaction-guarantees.ts` | keep | AGENTS.md names this declaration site for interaction dispatch paths and guarantee cells under ADR 0011. Cross-language golden tables in `contracts/fixtures/` associate it with this package. |
64+
| `src/interaction-guarantees.ts` | keep | AGENTS.md names this declaration site for interaction dispatch paths and guarantee cells under ADR 0011. Cross-language golden tables in `contracts/fixtures/` bind it to this package. |
6465
| `src/managed-device-allocation.ts` | move (batch 1) → `packages/managed-allocation` | Only managed-allocation and its dependent daemon composition consume this port and vocabulary; see [ADR 0021](0021-host-simlock-managed-device-allocation.md) §3. No other contracts file or zone imports it. Types therefore belong beside their implementing operations. |
65-
| `src/wait-runtime-plan.ts` | keep | Command-registry and daemon-server share it. Both are spine zones; contracts is the only boundary below them. |
66+
| `src/wait-runtime-plan.ts` | keep | Command-registry and daemon-server share it. Both are spine zones; contracts is the only seam below them. |
6667

6768
### device-selection
6869

@@ -77,36 +78,36 @@ All its consumers occupy one zone that already owns the operations represented b
7778

7879
| File | Decision | Reason |
7980
| --- | --- | --- |
80-
| `src/diagnostics.ts` | keep | AGENTS.md mandates this diagnostics boundary for all zones. Its repository-highest consumer count reflects a shared substrate, not incorrect placement. |
81+
| `src/diagnostics.ts` | keep | This is the diagnostics seam that every zone imports, as AGENTS.md mandates. Its repository-highest consumer count reflects a shared substrate, not incorrect placement. |
8182
| `src/internal/request-cancel.ts` | keep | AGENTS.md routes request cancellation through `host-kit/request`. Its internal mechanics already reside beside the facade. |
82-
| `src/request.ts` | keep | AGENTS.md names host-kit as the boundary for these cross-layer request contracts. Consumers span every zone. |
83+
| `src/request.ts` | keep | AGENTS.md names these cross-layer request contracts as a host-kit seam. Consumers span every zone. |
8384
| `src/session-paths.ts` | keep | Daemon, cli, and platforms resolve this session-artifact path grammar. AGENTS.md assigns path policy to `packages/daemon-contracts/src/session-artifact-paths.ts`, which consumes it. |
8485

8586
### kernel
8687

8788
| File | Decision | Reason |
8889
| --- | --- | --- |
89-
| `src/device-isolation.ts` | keep | Only kernel places this device-isolation vocabulary below device-selection, replay-port, and daemon. |
90+
| `src/device-isolation.ts` | keep | This device-isolation vocabulary is below device-selection, replay-port, and daemon. Kernel is the only zone below all of them. |
9091

9192
### platform-android
9293

9394
| File | Decision | Reason |
9495
| --- | --- | --- |
95-
| `src/device-boot.ts` | keep | ADR 0019/R13 assign boot mechanics to the platform. Root consumers perform composition through their own platform package loads. |
96+
| `src/device-boot.ts` | keep | ADR 0019/R13 assign boot mechanics to the platform. The root-zone consumers are the composition root, which loads its own platform packages. |
9697

9798
### platform-apple
9899

99100
| File | Decision | Reason |
100101
| --- | --- | --- |
101-
| `src/runner-owner-facade.ts` | keep | ADR 0005 defines the runner-owner boundary. R13 owns platform composition exports. The root importer is the designated host. |
102+
| `src/runner-owner-facade.ts` | keep | This is the ADR 0005 runner-owner seam. R13 owns platform composition exports. The root importer is the designated host. |
102103
| `src/runner/legacy-xctest-device-set.ts` | keep | Runner-internal legacy device-set parsers reside beside their runner. |
103-
| `src/simulator-boot.ts` | keep | ADR 0009 assigns simulator boot mechanics to the platform. The package's kernel device model and xctestrun preparation must remain synchronized with them. |
104+
| `src/simulator-boot.ts` | keep | ADR 0009 assigns simulator boot mechanics to the platform. The kernel device model and xctestrun preparation must remain synchronized with them in this package. |
104105

105106
### replay-port
106107

107108
| File | Decision | Reason |
108109
| --- | --- | --- |
109-
| `src/daemon-port/session-test-shard-devices.ts` | keep | This daemon-port adapter already colocates its shard enumeration binding. The `replay-test` scheduler deliberately never enumerates hardware. A move toward that zone breaks the port. |
110+
| `src/daemon-port/session-test-shard-devices.ts` | keep | This daemon-port adapter already colocates its shard enumeration binding. The `replay-test` scheduler deliberately never enumerates hardware. A move toward that zone would break the port. |
110111

111112
### selectors
112113

@@ -129,7 +130,7 @@ The maintainer decision does not classify this as completed collocation.
129130
Physical moves under #3294, a #3276 child, replace per-file declarations with folder-derived ownership.
130131

131132
`runtime-command-surface.ts` and `runtime-factory.ts` now reside in `src/command-runtime/`.
132-
The complete `daemon-contracts` zone resides in `packages/daemon-contracts`.
133+
The complete `daemon-contracts` zone resides in `packages/daemon-contracts`, behind narrow per-file subpath exports.
133134
Folders and packages derive these zones, so moved files no longer need `ROOT_MODULE_ZONES` rows.
134135

135136
The remaining shared daemon/client file, `provider-credential-fingerprint.ts`, follows #2559's decision.
@@ -145,21 +146,22 @@ R78 also prohibits access through any root module reachable by the CLI process.
145146
#3288's `daemon-contracts` zone declared ownership below both daemon and client.
146147
Package extraction makes it physical.
147148
R11 and package dependencies preserve that boundary.
148-
Rows supported only by path-keyed evidence say "retain for this batch".
149-
Current path lists constrain moves without independently proving optimal placement.
149+
Rows supported only by path-keyed evidence, the `platform-runtime-*` seams, say "retain for this batch".
150+
A guard's current path lists constrain a relocation.
151+
They are not independent proof that the placement is optimal.
150152

151153
| File | Decision | Reason |
152154
| --- | --- | --- |
153155
| `src/daemon-diagnostics-scope.ts` | moved → `packages/daemon-contracts/src/daemon-diagnostics-scope.ts` ([#3297](https://github.com/callstack/agent-device/pull/3297) into `src/daemon-contracts/`, then the package extraction) | The complete zone resides in `packages/daemon-contracts`. Its directory derives zone ownership without per-file `ROOT_MODULE_ZONES` rows. An internal rename therefore needs no ownership-table edit. |
154-
| `packages/daemon-contracts/src/device-claim-recovery.ts` | keep (shared-below-both) | The owner-scoped reconciler recovers durable resources from a dead owner's state directory. Daemon `open`/startup and daemonless `device release --stale` both run it. It therefore belongs below both. Runtime recovery may reside in `daemon-contracts` only with both consumers and gateway-only root composition, per ADR 0019 section 1. The package depends on `capture-kit`. A reverse dependency forms a project-reference cycle through `selectors`. |
156+
| `packages/daemon-contracts/src/device-claim-recovery.ts` | keep (shared-below-both) | The owner-scoped reconciler recovers durable resources from a dead owner's state directory. Daemon `open`/startup and daemonless `device release --stale` both run it. It therefore belongs below both. Runtime recovery may reside in `daemon-contracts` only when both sides run it and root composition supplies only the gateway, per ADR 0019 section 1. The package depends on `capture-kit`. A reverse dependency forms a project-reference cycle through `selectors`. |
155157
| `src/daemon-policy-file.ts` | moved → `packages/daemon-contracts/src/daemon-policy-file.ts` | This shared daemon/client contract follows #2559 and #3288's `daemon-contracts` declaration. Rank-5 daemon-client dynamically imports it, so the spine requires a home below both. Package extraction supplies that physical home with manifest-owned exports. |
156158
| `src/daemon.ts` | keep | This is the `internal/daemon` bundle entry. Umbrella §4 keeps composition roots at the root. |
157-
| `src/platform-runtime-apple-runner-owner.ts` | retain for this batch | R13's exact-importer rule and ADR 0022's R76 inventory use this `platform-runtime-*` composition path. Relocation requires coordinated changes to both declarations. The rules constrain the move without independently proving placement. |
158-
| `src/platform-runtime-daemon-lifecycle.ts` | retain for this batch | The same path-keyed R13/ADR 0022 boundary requires coordinated declaration changes for relocation. |
159-
| `src/platform-runtime-device-boot.ts` | retain for this batch | The same path-keyed R13/ADR 0022 boundary applies. |
160-
| `src/platform-runtime-resource-cleanup.ts` | retain for this batch | The same path-keyed R13/ADR 0022 boundary applies. |
161-
| `src/provider-credential-fingerprint.ts` | keep (type extracted) | Like `daemon-policy-file.ts`, this shared daemon/client contract follows #2559. #3288 places it beside provider composition that consumes fingerprinted credentials. Daemon extraction PR 6 moved only `DaemonProviderCredentials` to `packages/daemon-contracts` at `./provider-credentials`, below both consumers. The implementation remains here because it reads the installed-plugin manifest. |
162-
| `src/provider-limrun-runtime.ts` | keep | The proposed provider-limrun destination lacks a valid boundary. Its constructor builds root `src/sdk/limrun-runtime-dependencies.ts`, the ADR 0019 composition factory. This loads the root adb-host binder, core Android interactor, and platform-runtime app-state helpers, all prohibited package imports. Moving the class also moves composition and therefore requires design changes. |
159+
| `src/platform-runtime-apple-runner-owner.ts` | retain for this batch | This is a `platform-runtime-*` composition seam. R13's exact-importer rule and ADR 0022's R76 inventory key on its path. Relocation requires coordinated changes to both declarations. The rules constrain the move without independently proving placement. |
160+
| `src/platform-runtime-daemon-lifecycle.ts` | retain for this batch | The same path-keyed R13/ADR 0022 seam applies. Relocation is possible only with coordinated changes to those declarations. |
161+
| `src/platform-runtime-device-boot.ts` | retain for this batch | The same path-keyed R13/ADR 0022 seam applies. |
162+
| `src/platform-runtime-resource-cleanup.ts` | retain for this batch | The same path-keyed R13/ADR 0022 seam applies. |
163+
| `src/provider-credential-fingerprint.ts` | keep (type extracted) | Like `daemon-policy-file.ts`, this shared daemon/client contract follows #2559. #3288 declares its zone beside provider composition that consumes fingerprinted credentials. Daemon extraction PR 6 moved only `DaemonProviderCredentials` to `packages/daemon-contracts` at `./provider-credentials`, below both consumers. The implementation remains here because it reads the installed-plugin manifest. |
164+
| `src/provider-limrun-runtime.ts` | keep | The proposed provider-limrun destination has no seam. Its constructor builds the root dependency factory `src/sdk/limrun-runtime-dependencies.ts`, which is the ADR 0019 composition seam. This loads the root adb-host binder, core Android interactor, and platform-runtime app-state helpers, all prohibited package imports. Moving the class also moves composition and therefore requires design changes. |
163165
| `src/request-progress-protocol.ts` | moved → `packages/daemon-contracts/src/request-progress-protocol.ts` | This follows #2559's shared-contract decision. The client reads it statically through `daemon-client-progress.ts`; the server reads it through `packages/daemon/src/server/`. Only shared placement and wire-compat ledgers constrain it. #3288 declared `daemon-contracts`; extraction made it physical and moved wire-ledger keys with it. Contracts was rejected because R18 excludes envelope validation mechanics. |
164166
| `src/runtime-command-surface.ts` | moved → `src/command-runtime/runtime-command-surface.ts` ([#3299](https://github.com/callstack/agent-device/pull/3299)) | The command-surface binding resides beside `runtime-factory.ts` as one assembly group. Their folder derives `command-runtime` ownership. `topFolder` replaces per-file `ROOT_MODULE_ZONES` declarations. |
165167
| `src/runtime-factory.ts` | moved → `src/command-runtime/runtime-factory.ts` ([#3299](https://github.com/callstack/agent-device/pull/3299)) | The runtime assembly folder derives `command-runtime` ownership without per-file `ROOT_MODULE_ZONES` declarations. |
@@ -168,8 +170,8 @@ Current path lists constrain moves without independently proving optimal placeme
168170

169171
| File | Decision | Reason |
170172
| --- | --- | --- |
171-
| `src/sdk/limrun.ts` | keep | This publishes `agent-device/limrun`. `tsdown.config.ts` builds the bundle entry, and `package.json#exports` ships `dist/src/limrun.js`. A published facade cannot reside in a private workspace package. |
172-
| `src/sdk/limrun-runtime-types.ts` | keep | This public session-type refinement replaces provider session types with platform `AndroidAdbProvider` types. The published surface differs from the internal surface, whose identical names it `Omit`s. A provider-limrun home requires renamed or dual-exported internal types. That requires design changes, not only a move. |
173+
| `src/sdk/limrun.ts` | keep | This file is 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 reside in a private workspace package. |
174+
| `src/sdk/limrun-runtime-types.ts` | keep | This public session-type refinement is the provider session with the platform `AndroidAdbProvider` types swapped in. It exists because the published surface differs from the package-internal surface, whose identical names it `Omit`s. A provider-limrun home requires renamed or dual-exported internal types. That requires design changes, not only a move. |
173175

174176
## Batch 1 (this decision's companion PR)
175177

@@ -223,6 +225,7 @@ Composed root tests reach the daemon through `startDaemonRuntime` from the entry
223225

224226
Judge collocation by ownership: the location that minimizes independently maintained declarations per change.
225227
Community scores identify candidates only.
226-
Current R13, R76, and R78 path lists constrain relocation but never independently prove required placement.
228+
A guard's current path lists, for example R13, R76, and R78, are constraints that a relocation must account for.
229+
They are never independent evidence that a location must stay.
227230
If only a path supports retention, mark the row "retain for this batch".
228-
A later pass then re-examines it instead of treating it as settled.
231+
The next pass then re-opens it instead of treating it as settled.

0 commit comments

Comments
 (0)