Skip to content

Latest commit

 

History

History
219 lines (178 loc) · 19.2 KB

0033-collocation-decision-table.md

File metadata and controls

219 lines (178 loc) · 19.2 KB

0033. Collocation decision table

Status: accepted. Decision pass over the 48 candidate files listed in umbrella issue #3276 §5 (communities detected at ff685ad80: declared zones score 0.373 Louvain modularity versus 0.564 for detected communities). One row per candidate: move, merge, or keep, with the reason. Moves land as refactor(move) PRs; batch 1 is the companion PR to this decision.

2026-10-10: packages/managed-allocation was removed with the withdrawn allocator design (ADR 0021). The src/managed-device-allocation.ts row and Batch 1 record a move that landed (#3287) and was then deleted with the package; nothing moves there now. Rows that refuse a move into it, or cite its capture-kit dependency as a cycle, no longer bind; re-evaluate those files on their remaining edges.

Rules at a glance

  • A keep row is a decision, not a punt: the reason names the direction that was checked and why it fails (usually a package cycle or a spine inversion).
  • The detected community is not itself a reason to move. Most candidates sit in a consumer's community precisely because they are shared foundations; the table records where the module can live, which is often where it already lives.
  • Moves only count when the target has a real seam: no new dependency direction, no root composition pulled into a package, and the file's own imports come along unchanged. Where the proposal was infeasible, the row records that, and no issue is filed to re-propose it.
  • A path-keyed rule (R13's importer lists, R76's inventory, R78's scope) describes today's seam, not proof that a placement is best. A row whose only evidence is such a rule says "retain for this batch — relocation requires coordinated ownership changes" instead of resting the placement on the rule's path. A package cycle rejects the proposed direction, not every future design that first removes the edge closing it.
  • Rows marked move (batch N) are tracked as unchecked items on #3281; batch 1 is this decision's companion refactor(move) PR.

Decision table

capture-kit

File Decision Reason
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.
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.
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.
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.
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.
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.
src/snapshot/snapshot-freshness/index.ts keep Same: platform-neutral freshness policy its consumers (capture-kit itself, platforms, daemon) all import downward today.
src/snapshot/touch-reference-frame.ts keep Snapshot-geometry mechanics used by interaction and capture alike; capture-kit is the only zone below both.

contracts

contracts is the rank-1 shared-vocabulary zone. Each candidate below that stays has dependents in two or more higher-ranked zones, so no single consumer zone can own it without inverting the spine (R5). The one move row is the counter-case: its dependents all sit in one consumer zone that already owns the operations behind the vocabulary.

File Decision Reason
src/android-observation.ts keep Vocabulary read by capture-kit, platform-android, and daemon-server; contracts is the only zone below all three.
src/android-system-chrome.ts keep Same three-way split (capture-kit, platform-android, daemon-server).
src/app-events.ts keep Event vocabulary shared by commands, daemon, and platforms.
src/app-state.ts keep Broad fan-in app-state vocabulary; any consumer-side home would rank it above the others.
src/device-boot.ts keep Boot-phase vocabulary for device-selection, platforms, and daemon-server.
src/facades/device.ts keep Published facade of the contracts package; facades are the package boundary, not movable content.
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.
src/managed-device-allocation.ts move (batch 1) → packages/managed-allocation The port and its vocabulary (ADR 0021 §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.
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.

device-selection

File Decision Reason
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.
src/device-selection-resolver.ts keep Same — moving it up would rank it above its other consumers (replay-port, cli).
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.
src/open-target.ts keep Open-target vocabulary consumed across daemon, remote, and CLI.

host-kit

File Decision Reason
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.
src/internal/request-cancel.ts keep Request-cancellation mechanics AGENTS.md routes to host-kit/request; internal beside its facade is already the collocation.
src/request.ts keep Cross-layer request contracts AGENTS.md names as a host-kit seam; consumers span every zone.
src/session-paths.ts keep Session-artifact path grammar the daemon, cli, and platforms all resolve; AGENTS.md keeps the path policy in packages/daemon/src/session-artifact-paths.ts, which consumes this.

kernel

File Decision Reason
src/device-isolation.ts keep Device-isolation vocabulary below device-selection, replay-port, and daemon; kernel is the only zone beneath all of them.

platform-android

File Decision Reason
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.

platform-apple

File Decision Reason
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.
src/runner/legacy-xctest-device-set.ts keep Runner-internal legacy device-set parsing beside the runner it serves.
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.

replay-port

File Decision Reason
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.

selectors

File Decision Reason
src/parameterized-recorded-fill.ts keep ADR 0017 recorded-input mechanics; selector parsing/matching is centralized in this package by AGENTS.md.
src/target-evidence.ts keep Target-evidence vocabulary shared by daemon replay and selectors matching; selectors is below both.

cli

File Decision Reason
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.

(root)

#3288 assigns every process-root module a logical zone in scripts/layering/root-module-zones.ts (command-runtime rank 3, platform-runtime rank 4, …) while leaving the files physically in place. Per the maintainer design decision, that reclassification is not completed collocation: the physical moves under #3294 (child of #3276) replace each file's row with folder-derived ownership. The runtime assembly pair runtime-command-surface.ts / runtime-factory.ts has moved into src/command-runtime/, and the whole daemon-contracts zone has moved into packages/daemon-contracts — the folder and package derive the zone, so every moved file's ROOT_MODULE_ZONES row is gone. The daemon ⇄ client shared files that remain here (provider-credential-fingerprint.ts) trace to #2559, which relocated the shared contracts to the process root so the client stops importing packages/daemon/src/ at all; R78 keeps any client→daemon edge at zero runtime and a five-line recorded type-only residue, and #3288's daemon-contracts zone was the declaration of that shared-below-both ownership — the extraction makes it physical, with R11 and the package's dependency edges holding the same boundary. Rows on path-keyed evidence alone (the platform-runtime-* seams) say "retain for this batch": a guard's current path lists constrain a relocation, they are not independent proof the placement is optimal.

File Decision Reason
src/daemon-diagnostics-scope.ts moved → packages/daemon-contracts/src/daemon-diagnostics-scope.ts (#3297 into src/daemon-contracts/, then the package extraction) The whole daemon-contracts zone now lives as packages/daemon-contracts, so the package directory derives the zone and the per-file ROOT_MODULE_ZONES row stays deleted; an internal rename needs no ownership-table edit.
src/daemon-policy-file.ts moved → packages/daemon-contracts/src/daemon-policy-file.ts 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. The extraction makes that placement physical: the package sits below both sides and its manifest exports own the boundary.
src/daemon.ts keep Entry point (internal/daemon bundle entry); composition roots stay in root by umbrella §4.
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.
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.
src/platform-runtime-device-boot.ts retain for this batch Same path-keyed R13/ADR 0022 seam.
src/platform-runtime-resource-cleanup.ts retain for this batch Same path-keyed R13/ADR 0022 seam.
src/provider-credential-fingerprint.ts keep (type extracted) 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. PR 6 of the daemon extraction moved only the DaemonProviderCredentials declaration to packages/daemon-contracts (./provider-credentials), the same shared-below-both landing as the policy file; the fingerprinting implementation stays here because it reads the installed-plugin manifest.
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.
src/request-progress-protocol.ts moved → packages/daemon-contracts/src/request-progress-protocol.ts Daemon ⇄ client shared contract from the same #2559 decision — the client reads it statically (daemon-client-progress.ts) and the server through packages/daemon/src/server/, so only #2559's shared-placement boundary and the wire-compat ledgers pin it; declared daemon-contracts by #3288 and now physically placed by the extraction. Contracts was considered and R18 keeps contracts free of envelope validation mechanics. The wire-ledger keys moved with the file.
src/runtime-command-surface.ts moved → src/command-runtime/runtime-command-surface.ts (#3299) Physical move landed with runtime-factory.ts as one assembly group: the command-surface binding sits beside the factory it composes, under the folder that derives its command-runtime zone, so topFolder replaces the per-file ROOT_MODULE_ZONES row.
src/runtime-factory.ts moved → src/command-runtime/runtime-factory.ts (#3299) Physical move landed: the runtime assembly now lives under the folder that derives its command-runtime zone, with the same row deletion through folder-derived ownership.

sdk

File Decision Reason
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.
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 Omits. Relocating it into provider-limrun requires renaming or dual-exporting the internal types — design, not a move.

Batch 1 (this decision's companion PR)

  • packages/contracts/src/managed-device-allocation.ts → packages/managed-allocation/src/managed-device-allocation.ts (new @agent-device/managed-allocation/managed-device-allocation subpath).

Batch 1 is exactly this one file. The moves the issue listed beside it failed re-verification against the current import graph, and the rows above record why: the four admission ledgers and durable-json.ts hit the capture-kit ⇄ managed-allocation package cycle, and the three limrun files have no seam (published facade, public-type collision, root dependency factory).

Follow-ups (tracked on #3281)

  • Physical root-pass moves under #3294 (child of #3276): the runtime assembly pair runtime-command-surface.ts / runtime-factory.ts is collocated in src/command-runtime/ (#3299). Each folder derives its zone, replacing the moved files' ROOT_MODULE_ZONES rows; #3288's zone assignments alone were classification, and each landed move completes its own file's collocation. The daemon-contracts side landed as a workspace package: the zone's ten files (daemon-owner-cleanup, daemon-policy-file, daemon-process, daemon-registration-owner, daemon-registration, daemon-resolution, daemon-shutdown-report, request-progress-protocol, session-repair-tombstone, and daemon-diagnostics-scope from src/daemon-contracts/, first moved there by #3297) are now packages/daemon-contracts/src/ behind narrow per-file subpath exports.

2026-10-13 (11b, #3546): src/daemon/ moved to packages/daemon/src/ as @agent-device/daemon. Its export surface settles on a façade, not importer reach: one named subpath per production/script consumer, plus ONE ./testing/* pattern entry publishing test data that R11 refuses for any non-test importer (a package test double reached through the boundary is production code depending on a fake). internal/ modules are reached only by tests living inside the package. Moving the daemon-request wire types down to @agent-device/daemon-contracts so the client stops depending on the server package is a follow-up, keeping 11b a pure move.

Refuted alternatives

  • Move every ≥80% community match into its dominant zone. Rejected: the measure is consumer-side. Foundations (host-kit, contracts, selectors, device-selection) score badly by construction, and reversing their edges inverts the spine.
  • durable-json.ts → contracts. Pure-JSON helpers looked like contracts/json.ts neighbors, but R18 holds contracts to wire vocabulary, and these functions are durable-descriptor persistence validation. Rejected.
  • Ledgers → managed-allocation with capture-kit importing them back. Rejected as proposed: it completes the cycle that R4/R11 reject while managed-allocation's dependency on capture-kit is load-bearing (its record codec uses capture-kit durable mechanics). Removing that load-bearing import first would reopen the question — this row refuses the sequence, not the destination.

The enduring rule

Collocation is judged by ownership: the placement that minimizes independently maintained declarations per change. Dependency-community scores only identify candidates; a guard's current path lists (R13, R76, R78) are constraints a relocation must account for, never independent evidence that a location must stay. A keep that cannot cite ownership, only a path, is marked "retain for this batch" so the next pass re-opens it rather than inheriting it as settled.