You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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).
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.
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).