Skip to content

Latest commit

 

History

History
174 lines (137 loc) · 13.9 KB

0033-collocation-decision-table.md

File metadata and controls

174 lines (137 loc) · 13.9 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; each landed move is recorded in ADR 0021-style alignment notes here only when it changes a row.

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.
  • 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 → 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).
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.
src/capture-admission/perf-capture-admission-ledger.ts keep Same cycle; a four-line specialization of the ledger its own package owns.
src/capture-admission/screen-recording-admission-ledger.ts keep Same cycle; consumed by capture-kit's screen-recording session resource and stop-recovery.
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.
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 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 src/daemon/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)

Umbrella §4 owns emptying (root) of everything that is not an entry point or composition root; rows below marked move (root pass) are that workstream's, not collocation's, and are listed here so the candidate list has exactly one decision record per file. Three of the shared root files (daemon-policy-file.ts, provider-credential-fingerprint.ts, request-progress-protocol.ts) are deliberate: #2559 relocated the daemon ⇄ client shared contracts to the process root specifically so the client stops importing src/daemon/ at all, and R78 keeps any client→daemon edge at zero runtime and a five-line recorded type-only residue. Their root placement preserves that boundary — the framing below names the mixed static/dynamic import kinds rather than claiming one kind.

File Decision Reason
src/daemon-diagnostics-scope.ts move (root pass) Only daemon-server files import it; it belongs under src/daemon/ when the root pass sweeps daemon-private scopes.
src/daemon-policy-file.ts keep Daemon ⇄ client shared contract parked at the process root by #2559; the spine forbids daemon-server (rank 4) owning what daemon-client (rank 5) dynamically imports. Relocation is umbrella §4's, and only after the root's policy vocabulary is placed.
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 keep platform-runtime-* composition seam owned by R13's exact-importer rule and the ADR 0022 R76 inventory; relocating it breaks both declarations.
src/platform-runtime-daemon-lifecycle.ts keep Same R13/ADR 0022 seam.
src/platform-runtime-device-boot.ts keep Same R13/ADR 0022 seam.
src/platform-runtime-resource-cleanup.ts keep Same R13/ADR 0022 seam.
src/provider-credential-fingerprint.ts keep Daemon ⇄ client shared contract at the root by the same #2559 decision as daemon-policy-file.ts.
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 keep Daemon ⇄ client shared contract at the root by the same #2559 decision — the client reads it statically (daemon-client-progress.ts) and the server through src/daemon/server/, so only the root sits on both sides of the R78 boundary without a client→daemon edge; the wire-compat ledgers pin the framing here. Contracts was considered and R18 keeps contracts free of envelope validation mechanics.
src/runtime-command-surface.ts move (root pass) Consumed by src/runtime.ts and daemon runtime modules; it is runtime composition that can live beside them.
src/runtime-factory.ts move (root pass) Same — imported by runtime composition and two daemon modules, not a cross-zone foundation.

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)

  • Root pass ((root) → entry points and composition roots only): daemon-diagnostics-scope.ts, runtime-command-surface.ts, runtime-factory.ts, and the rank-obstruction trio (daemon-policy-file.ts, provider-credential-fingerprint.ts, request-progress-protocol.ts) after their vocabulary is split.

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 at once: it manufactures the package cycle that R4/R11 reject; managed-allocation's dependency on capture-kit is load-bearing (its record codec uses capture-kit durable mechanics).