refactor(move): collocation batch 1 — allocator contract into managed-allocation

[thymikee]

Summary

Part of #3276 §5. Closes #3281.

• Adds ADR 0033 (renumbered from 0032 this round: docs(adr): retain the current layering engine (ADR 0032) #3286 already claims 0032-layering-graph-engine.md). This PR's README change adds only the 0033 row; docs(adr): retain the current layering engine (ADR 0032) #3286 has since merged with the 0032 row, and the rebase keeps both rows side by side: a decision table with one row per candidate file in the umbrella's collocation list — move, merge, or keep with the direction that was checked and fails. Required behavior (a) of Architecture WS5: collocation decisions and first refactor(move) batch #3281.
• Lands the batch-1 refactor(move): packages/contracts/src/managed-device-allocation.ts → packages/managed-allocation/src/managed-device-allocation.ts, new @agent-device/managed-allocation/managed-device-allocation subpath; contracts drops the old subpath. The port and its lease vocabulary had no importer outside managed-allocation and the daemon composition that already depends on it.
• The other listed batch moves failed the mandated re-verification and the ADR rows are the record: the four capture-kit admission ledgers and durable-json.ts cannot move to managed-allocation because managed-allocation already depends on capture-kit (the move would invert an existing package edge), and the three limrun files have no seam — src/sdk/limrun.ts is the published agent-device/limrun facade entry, limrun-runtime-types.ts is a public-type refinement colliding with the package-internal names, and src/provider-limrun-runtime.ts self-builds the root's ADR-0019 dependency factory in its constructor.

33 files; the move itself is rename-only (git diff -M90% --summary shows the file at 98% similarity; the rest are one-line import re-points and docs). The ADR 0021 link edit is independent of the renumber (it points at the moved contract file, not an ADR number).

Validation

• Head d4ac51874 (rebase onto origin/main after docs(adr): retain the current layering engine (ADR 0032) #3286/refactor(layering): rank every root module so R5 sees through (root) #3288 merged; conflict resolved keep-both in docs/adr/README.md, 0032 + 0033 rows side by side): pnpm check:affected --run exit 0, "all runnable checks passed"; check:layering green on the new spine (R80/R6 at the new merge-base).
• Previous head 6701ab987 (ADR reconciliation with refactor(layering): rank every root module so R5 sees through (root) #3288/Architecture WS9: physical root-pass moves for daemon-diagnostics-scope, runtime-command-surface, runtime-factory #3294 after the design follow-up): pnpm check:affected --run exit 0, "all runnable checks passed".
• Previous head 161b02234 (prose-only ADR intro rewording): pnpm check:affected --run exit 0, "all runnable checks passed".
• Previous head d7239c323: pnpm check:affected --run exit 0, "all runnable checks passed" (59 selected checks; the single check:affected: lint failed. line in the log is check:affected:test's own envelope fixture, reproduced identically on every run at the same position — standalone pnpm lint exits 0).
• Previous head 62200ec25 passed the same gate; this round changed only docs/adr/ files.
• check:layering, check:agent-guidance, typecheck, format:check, focused vitest (managed-allocation package + daemon allocation + reachability + allocator-fake, 116 tests) green.
• check:production-exports: identical finding count on origin/main and head (55), so no export-surface delta.
• Declared-zone modularity re-measured with the umbrella's method on both trees: 0.3732 → 0.3745 (before-value reproduces the issue's 0.373; small improvement, not chased).

Docs-only ADR rows need no runtime evidence.

[github-actions]

Size Report

Metric	Base	Current	Diff
Installed (including dependencies)	5.13 MB	5.13 MB	-2.9 kB
Package (unpacked)	5.13 MB	5.13 MB	-2.9 kB
Package (download)	1.54 MB	1.54 MB	-984 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	19.3 ms	20.5 ms	+1.2 ms
CLI --help	55.5 ms	57.1 ms	+1.6 ms

[cubic-dev-ai]

2 issues found across 33 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="docs/adr/0032-collocation-decision-table.md">

<violation number="1" location="docs/adr/0032-collocation-decision-table.md:28">
P3: The File column in the capture-kit table mixes path prefixes: the four admission-ledger rows write `capture-admission/audio-probe-admission-ledger.ts` (no `src/`), while the other four rows in the same table write `src/durable-json.ts` and `src/snapshot/...`. Every other zone's rows consistently use the `src/` prefix. Since this column is the table's key (one row per candidate), normalize the ledger rows to `src/capture-admission/...` (files live at `packages/capture-kit/src/capture-admission/`) so all eight rows resolve the same way.</violation>

<violation number="2" location="docs/adr/0032-collocation-decision-table.md:40">
P3: The contracts-section prologue says "every candidate below has dependents in two or more higher-ranked zones, so no single consumer zone can own it without inverting the spine (R5)" — but the `managed-device-allocation.ts` row directly below it is the counterexample: it was moved into managed-allocation precisely because that single consumer zone can own it without new edges (daemon already depends on the package). The universal wording contradicts the table's own outcome and muddies the R5 rationale for a reader checking why this one file moved. Scope the claim to the keep rows, or add the exception.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

This PR is ready at d7239c3, and all 19 checks pass. The diff only touches type imports, the export maps and the ADR docs, so any export-resolution failure would have shown in the typecheck and layering jobs, which are green. There are no conflicts.

Not blocking: the intro sentence in docs/adr/0033-collocation-decision-table.md (https://github.com/callstack/agent-device/blob/d7239c3/docs/adr/0033-collocation-decision-table.md#L6) is hard to read and links ADR 0021 for no clear reason, so a rewrite without that link would help. The PR body also says the README lists 0032, but only the 0033 row was added, so there is a 0032 gap until #3286 merges. You can take or leave both.

I did not re-run check:affected, check:layering, check:production-exports or the modularity measurement, and I relied on CI and the PR-body numbers for those. I also did not check the R-number reasons on the keep rows (R13, R18, R78) against the layering model.

[thymikee]

Closing the loop on the two non-blocking items — both accepted, pushed as a prose-only amend at 161b02234 (check:affected --run exit 0 on that head):

1. ADR intro rewrite: accepted. The garbled "recorded in [ADR 0021]-style alignment notes" sentence is gone; the intro now ends at "Moves land as refactor(move) PRs; batch 1 is the companion PR to this decision." Per your parenthetical, the 0021 reference was kept only where a row needs it — the managed-device-allocation.ts move row now cites (ADR 0021 §3) inline.
2. PR-body README wording: accepted. The Summary now states this PR adds only the 0033 README row and that the 0032 row arrives with docs(adr): retain the current layering engine (ADR 0032) #3286 (index gap until one merges, whichever lands second keeps both rows). No 0032 index row added here, as instructed.

[thymikee]

Design follow-up on 161b02234: the allocator-contract move is well scoped, and rejecting moves justified only by community membership is the right call. Two ADR details need reconciliation with the broader work:

1. “Keep” should distinguish sound ownership from a mechanical-move constraint. The root platform-runtime rows cite R13/R76's exact paths as reasons to keep files. Those declarations describe today's placement; needing to update them does not itself prove the placement is best. Keep this PR's move-only scope, but describe such rows as “retain for this batch; relocation requires coordinated ownership changes.” Likewise, a package-cycle result rejects the proposed move, not every possible future design. No new refactor or issue per row is requested.
2. The root-pass handoff currently doesn't match refactor(layering): rank every root module so R5 sees through (root) #3288. ADR 0033 marks daemon-diagnostics-scope.ts, runtime-command-surface.ts, and runtime-factory.ts as “move (root pass)”. At 5c90cdfcb, refactor(layering): rank every root module so R5 sees through (root) #3288 assigns logical zones but leaves these files in place. Please reconcile the rows and the existing issue checklist: either the physical moves remain outstanding, or record an explicit keep/reconsidered decision and its ownership rationale. Do not count reclassification as completed collocation.

The enduring rule should be ownership and reduced change coupling. Dependency-community scores identify candidates; current guard filenames are constraints to account for, not independent evidence that a location must stay forever.

[thymikee]

Both reconciliations landed at 6701ab987 (check:affected --run exit 0 on that head; docs-only delta, rebased onto origin/main):

1. Path-keyed keeps reworded. The four platform-runtime-* root rows now read retain for this batch and say explicitly that R13/R76's path lists constrain a relocation rather than prove the placement. Same framing promoted to a "Rules at a glance" bullet, and the capture-kit cycle rows now say the proposed direction/sequence is rejected — a future design that first removes the load-bearing capture-kit import stays open ("this row refuses the sequence, not the destination"). The enduring rule is recorded at the ADR close: judge collocation by ownership / fewer independently maintained declarations per change; community scores identify candidates, guard filenames are constraints.
2. Root-pass handoff reconciled with refactor(layering): rank every root module so R5 sees through (root) #3288 via Architecture WS9: physical root-pass moves for daemon-diagnostics-scope, runtime-command-surface, runtime-factory #3294. My previous push had gone the other way (keep/reconsidered citing the zone assignments) — corrected per your shared decision. The three rows are now move (outstanding, #3294), the (root) prologue states reclassification is not completed collocation, the Follow-ups section links #3294, and the Architecture WS5: collocation decisions and first refactor(move) batch #3281 checklist gained the unchecked item linking Architecture WS9: physical root-pass moves for daemon-diagnostics-scope, runtime-command-surface, runtime-factory #3294. Note for the Architecture WS9: physical root-pass moves for daemon-diagnostics-scope, runtime-command-surface, runtime-factory #3294 owner recorded in the rows: daemon-diagnostics-scope.ts's importers include daemon-registration-owner.ts (static, line 25), which refactor(layering): rank every root module so R5 sees through (root) #3288 classifies as daemon-contracts, and runtime-command-surface.ts/runtime-factory.ts are statically imported by src/runtime.ts (command-runtime) — the physical destination has to respect R5 against those lowest-ranked importers, which is presumably why the moves are their own workstream.

[thymikee]

The code in 6701ab9 looks good. The move diff is identical to the head I reviewed earlier (d7239c3), so my earlier clean result still holds. Both ADR wording fixes from that round are now in place. All 19 checks pass, and there are no conflicts. I did not re-run the layering or check gates locally, and I did not re-read the full move diff, so this relies on the CI results and the identical diff. Of the three cubic-dev-ai threads, the ADR line 144 thread (#3287 (comment)) and the capture-admission path prefix thread (#3287 (comment)) are fixed at this head, so you can resolve them. The Contracts prologue wording thread (#3287 (comment)) does not apply, since the meaning is unchanged and it is docs-only, so you can resolve it too. Nothing else stands in the way of merging.

Since then the branch was rebased to d4ac518. The range-diff shows the same commits, with only the ADR index context changed after ADR 0032 merged, so this result should carry over once CI finishes there.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-07 18:48 UTC