Skip to content

Commit ab50f2a

Browse files
authored
docs(adr): write runtime and architecture ADRs in ASD-STE100 (#3731)
* docs(adr): delete completed ADR 0019 checkpoint history * docs(adr): write ADR 0019 in ASD-STE100 * docs(adr): write ADR 0021 in ASD-STE100 * docs(adr): delete retired ADR 0022 classification procedure * docs(adr): write ADR 0022 in ASD-STE100 * docs(adr): delete completed ADR 0023 revision history * docs(adr): write ADR 0023 in ASD-STE100 * docs(adr): delete superseded ADR 0025 Device Hub process * docs(adr): write ADR 0025 in ASD-STE100 * docs(adr): write ADR 0026 in ASD-STE100 * docs(adr): write ADR 0027 in ASD-STE100 * docs(adr): write ADR 0029 in ASD-STE100 * docs(adr): write ADR 0030 in ASD-STE100 * docs(adr): write ADR 0031 in ASD-STE100 * docs(adr): write ADR 0032 in ASD-STE100 * docs(adr): delete completed ADR 0033 move batches * docs(adr): write ADR 0033 in ASD-STE100 * docs(adr): delete completed ADR 0019 substrate adoption instructions * docs(adr): restore the ADR 0019 move-unit size rule The deletion of the completed checkpoint history (667484c) also removed the operative size rule of section 8. The language commit re-added only one sentence of it. Restore the full rule: the original-baseline and stack-base bounds, the zero-or-negative expected delta, the root-versus-package byte report, the named justification of each addition, type inflation as size growth, and the #1739 evidence home. * docs(adr): restore the frozen meaning in ADR 0021 Restore "replaced" in Status and the "ADR text before 2026-10-10" recovery pointer. Restore the leased-device scope of remote access, the "is the device leased" check, the Simlock owner of the HTTP API, and the "address a device" requirement. Keep the base sentence about the adb server, because its "which" referent is ambiguous. * docs(adr): restore the frozen meaning in ADR 0022 Rewrite the R75 glance rule as the membership ratchet that the gate enforces. Name the whole root platform-runtime family, which includes src/platform-runtime.ts. Restore the querySelector CONDITIONAL attribution, the separate landed child issues, "leaked", the generic hook bag prohibition, the kill criterion, the request-spine guards, the owning seam, and "fold"/"collapse" as two separate words. * docs(adr): restore the frozen meaning in ADR 0023 Restore the comparability sentence for the counting definition, the collapse and fold vocabulary of the ≤14 section, the decision (not the wrappers) as the thing outside this route's ownership, the seam and kept-depth terms, the wiring rows, "multiple" calls, the capture as the ineligible subject, and adapter examples as examples. Revert the generalized 38/29 sentence to the base text; its stale "higher" claim is a discrepancy for the PR body, not a language fix. * docs(adr): restore the frozen meaning in ADR 0025 Restore the accepted gap that the hinge stream never ran on a physical device, which the Device Hub deletion removed. Restore the glance rows for an unsettled hinge, the refusal of any pose that never agrees, and the panel-power-only pose report. Restore "only when neither window resolves", the two facts of the ADR in the Android amendment, the 27.1 toolchain check, the former half-open rule, the unverified refusal, and the dangling private-API pointer. * docs(adr): restore the frozen meaning in ADR 0026 Restore that a weak signal reaches only the scroll-band site and that directional hints are its outlet only when nothing is the indicator's parent. Restore "characterize each site before you reshape any of them", the subject and "only" of the frame-change glance row, examples as examples, the refuted alternatives as hypotheticals, and the pinned scroll host as the test subject. * docs(adr): restore the frozen meaning in ADR 0027 Restore "exactly when it is a split" as "if and only if", the glance rule that the tolerance guarantees only flat weight over a preserved base closure, and the code-quoted terms "wiring lines", "loading-shape probe", "loading property", and "façade exactness". Restore "two or more shared" statements, "exactly these facts", the like-for-like replacement scope, and the refuted alternatives as hypotheticals. * docs(adr): restore the frozen meaning in ADR 0029 Restore "the only exception" for the capability gate, the examples of protocol plumbing as examples, the remote agent and the simulator as the referents in Context, the three enforcement "points" and the backstop rule, the client reuse of a daemon, "every" earlier admission decision, and the per-daemon floor. * docs(adr): restore the frozen meaning in ADR 0030 Restore that daemon registration keeps the same daemon.lock path and refuses legacy files instead of reclaiming them. Make the separate state directory conditional on the failure to stop every user again. Restore "after that bound", "guard path", the scope "those paths" for the legacy ban, the guard's paths, the unexpanded support contract, and "any retained" guard. Keep the base "its directory guard": its referent is ambiguous. * docs(adr): restore the frozen meaning in ADR 0031 Restore the code term "helper-routed" and "exactly", the passive member-by-member assembly, the 48-level limit as a maximum, the runner as the actor that moves the shared pointer, and "dropped" as the one word for lost events. * docs(adr): restore the frozen meaning in ADR 0032 Remove the added "only" from the fallow revisit rule. Make "replaceable" describe the model implementation again. Restore the code term "lazy seams", the parseImports miss as the gap, "misses none of these edges", "with either engine", and "does not include" for tsconfig. * 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. * docs(adr): restore the frozen meaning in ADR 0019 Restore the shape rule in section 2 as a plain statement in force, including the timing "at the point the shape is requested"; #2808, #2806, and the web runtime tests already rely on it. The Status line keeps its "proposed" wording, so the conflict stays visible. Restore the operative half of the deleted section 6 substrate paragraph: no duplication or package-to-root back-import of shared Apple-runner or Android-helper mechanics, the injected-capability path, and one execution owner. Repoint the dangling substrate references in sections 6, 10, and the ADR 0009 relationship. Restore the Status outcome of the adoption checkpoint, the kernel helper scope, the only static value-import sites, the owning provider, owner cell, freezes, the time-bound await using ban, the trust choke point, "seam" as the code term, the conditional scope of the preferred/required rule, the loading shape, the "yet" qualifiers of the End state, and the declared host-port adapter. * docs(adr): restore three conditions dropped by sentence splits - ADR 0025: emit apple_display_primary_geometry_conflict only when the primary panel is also the largest. - ADR 0025: keep the pre-panel normalization only when the runner reports no panel metadata. - ADR 0032: the revisit trigger is an engine that can supply the shared import model, not one that already supplies it. Found in review round 2. * docs(adr): keep translation hops in the ADR 0022 route-depth rule The base decision applies the deletion test to pass-through and translation hops and endorses only the proven removable hop. The glance named only pass-through hops. Restore the selector "seam" term from the base rationale. #3731 (comment) * docs(adr): restore that the ADR 0033 managed-allocation move landed The base text says the row and Batch 1 record a move that landed in #3287 and that the package removal then deleted. The rewrite dropped that the move landed. #3731 (comment) * docs(adr): restore the ADR 0025 rule that the fold press is not evidence The Device Hub deletion also removed the base sentence that fold sets the pose and that only the read-back is evidence. Point to the HID amendment that replaced the Device Hub press. #3731 (comment) * docs(adr): state the ADR 0022 route-depth rule with its base scope Name pass-through and translation hops in one rule, as the base deletion test does, and drop the commit hash that the base does not attach to the verdict. #3731 (comment) * docs(adr): cite R76's path-family ban in ADR 0033 ADR 0022 records that #3430 emptied the R76 inventory and reduced R76 to a plain ban on the src/platform-runtime-*.ts family. The ban still keys on these paths, so the retain-for-this-batch rationale holds; only the noun was stale. #3731 (comment) * docs(adr): mark the ADR 0033 managed-allocation row as landed and removed The row is history: the move landed in #3287, and the package removal on 2026-10-10 deleted the file. State this in the row, as the Status note does, so the row does not read as a live move target. #3731 (comment) * docs(adr): restore scope words in ADR 0033 rows and prose Restore base scope dropped in the rewrite: "design, not a move" for the limrun rows, the shared reason and "all" for snapshot-freshness, the fingerprint and policy-file links, the real-seam conditions, "every edge" and "at all" for client imports, "the platform package's", the capture-kit back-edge, R11's "from a non-test file", and the daemon entry's re-export scope. * docs(adr): restore scope words and a fixture ban in ADR 0019 Restore "provider" and "concrete" in the bindDevice glance, the conditional parity evidence that explains why, "touches" for the SessionState unit, "not pass-through layers" for the declared boundaries, and "grab bag". Restore the operative ban that temporary fixtures never authorize a production bridge, duplicate route, or package back-import; the section 7 deletion removed it. * docs(adr): restore scope words found by the 12-ADR drift pass ADR 0021: restore the two "so" consequences. ADR 0023: name `isEligible` as the fallback condition, and describe the adb-host binding instead of a permission. ADR 0025: limit "never promoted to a verified pose" to the `screen` evidence. ADR 0026: name the ledger as the shape to extend, not an order. ADR 0027: restore "carry no code", "new code", and "all". ADR 0029: restore the "HTTP edge" term. ADR 0032: restore "only", "one more", the "and" between edge kinds, and the "because" link. * docs(adr): restore ADR 0022 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0023 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0031 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0032 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0033 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0025 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0026 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0027 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. * docs(adr): restore ADR 0019 wording dropped by the rewrite Found by the second meaning-drift pass against base 59fdf00. Also repair the review instruction that pointed at the deleted substrate paragraph. * docs(adr): restore the ADR 0021 claim guard wording Base: "device claims still guard against two sessions ... driving the same device". "prevent" claimed a stronger guarantee. * docs(adr): scope the ADR 0025 defensible-source claim to the recorded poses Base: "Poses came from the hinge read-back, not from the pose that was requested; the amendment above is why that is the only defensible source". #3731 (comment)
1 parent 8628e93 commit ab50f2a

12 files changed

Lines changed: 2830 additions & 2501 deletions

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 929 additions & 936 deletions
Large diffs are not rendered by default.

‎docs/adr/0021-host-simlock-managed-device-allocation.md‎

Lines changed: 61 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -2,75 +2,87 @@
22

33
## Status
44

5-
Accepted (2026-09-01). Decision replaced 2026-10-10: the in-process Host allocator integration is
6-
withdrawn. Simlock closed its side ([simlock#70](https://github.com/callstackincubator/simlock/issues/70))
7-
as superseded by a design in which agents lease devices themselves, and agent-device follows it.
5+
Accepted (2026-09-01). The decision was replaced on 2026-10-10. The in-process Host allocator integration is withdrawn.
6+
Simlock closed [simlock#70](https://github.com/callstackincubator/simlock/issues/70) in favor of direct device leases by agents.
7+
agent-device follows that design.
88

99
## Rules at a glance
1010

11-
- Agents acquire booted devices from Simlock (`simlock lease`, its MCP tool, or its HTTP API) and
12-
own renewal and release. agent-device does not call Simlock.
11+
- Agents acquire booted devices from Simlock through `simlock lease`, the Simlock MCP tool, or the Simlock HTTP API.
12+
Agents own renewal and release. agent-device does not call Simlock.
1313
- Simlock owns allocation, capacity, provisioning, readiness, expiry, and device deletion.
14-
- agent-device drives a leased device as an ordinary local device: the local platform runtime,
15-
ordinary sessions, and process-owned device claims. There is no managed runtime owner, allocator
16-
client, allocation journal, managed binding fence, or Host lease mapping.
17-
- iOS: pass the grant's `SIMLOCK_IOS_DEVICE_SET` as `--ios-simulator-device-set` (or the
18-
`iosSimulatorDeviceSet` config key). Discovery, `simctl`, and the XCTest runner then resolve the
19-
leased simulator inside Simlock's set.
20-
- Android: the grant's `ANDROID_ADB_SERVER_PORT` points `adb` at Simlock's server. The daemon's
21-
`adb` invocations read it from the daemon's own environment, so the daemon must start inside the
22-
lease environment (for example, a per-agent `--state-dir`).
14+
- agent-device uses the ordinary local runtime, sessions, and process-owned device claims for a leased device.
15+
It has no managed runtime owner, allocator client, allocation journal, managed binding fence, or Host lease mapping.
16+
- For iOS, pass the grant's `SIMLOCK_IOS_DEVICE_SET` as `--ios-simulator-device-set` or the `iosSimulatorDeviceSet` config key.
17+
Discovery, `simctl`, and the XCTest runner resolve the leased simulator inside Simlock's set.
18+
- For Android, the grant's `ANDROID_ADB_SERVER_PORT` selects Simlock's adb server.
19+
Daemon `adb` calls read the daemon's environment.
20+
The daemon must start inside the lease environment, for example with a per-agent `--state-dir`.
2321

2422
## 1. Context
2523

26-
Simlock keeps parallel agents from fighting over the same simulator or emulator. Its simulators
27-
live in a device set Xcode does not read, and its emulators register with Simlock's own adb server,
28-
which is what stops another tool from erasing a leased device. A grant reports what reaching the
29-
device needs as an `environment` object (`SIMLOCK_IOS_DEVICE_SET`, `ANDROID_ADB_SERVER_PORT`), and
30-
`simlock lease --export-env` prints it for `eval`.
24+
Simlock prevents parallel agents from competing for one simulator or emulator.
25+
Its simulators reside in a device set that Xcode does not read, and its emulators register with Simlock's own adb server, which is what stops another tool from erasing a leased device.
26+
A grant reports device access requirements in an `environment` object with `SIMLOCK_IOS_DEVICE_SET` and `ANDROID_ADB_SERVER_PORT`.
27+
`simlock lease --export-env` prints this object for `eval`.
3128

32-
The first version of this ADR planned a Host inside agent-device that would allocate through
33-
Simlock's typed client, journal allocation requests, fence every command with confirmed lease
34-
authority, and run managed devices through a dedicated runtime owner. agent-device shipped those
35-
foundations without ever activating them. Simlock then settled on agents leasing devices directly,
36-
which needs nothing from agent-device beyond addressing a device in Simlock's roots, and both
37-
already existed: simulator-set scoping and adb's own server-port environment.
29+
The first design proposed a Host inside agent-device with these responsibilities:
30+
31+
- Allocate through Simlock's typed client.
32+
- Journal allocation requests.
33+
- Fence each command with confirmed lease authority.
34+
- Use a dedicated runtime owner for managed devices.
35+
36+
agent-device shipped these foundations but never activated them.
37+
Simlock then selected direct device leases by agents.
38+
This design needs nothing from agent-device beyond the ability to address a device in Simlock's roots.
39+
agent-device already supported simulator-set scope and adb's server-port environment.
3840

3941
## 2. Decision
4042

41-
agent-device has no Simlock-specific code. An agent leases a device, points agent-device at it with
42-
the scope Simlock reports, and releases the lease when done:
43+
agent-device has no Simlock-specific code.
44+
An agent leases a device and configures agent-device with Simlock's reported scope.
45+
After use, the agent releases the lease.
4346

4447
```sh
4548
eval "$(simlock lease --platform ios --device 'iPhone 16' --detach --export-env)"
4649
agent-device open MyApp --platform ios --ios-simulator-device-set "$SIMLOCK_IOS_DEVICE_SET"
4750
```
4851

49-
The lease is the exclusion between agents; agent-device's process-owned device claims still guard
50-
against two sessions of one installation driving the same device. Simlock's "advisory, not a
51-
sandbox" model applies: agent-device does not verify that a device is leased.
52+
The lease provides exclusion between agents.
53+
Process-owned device claims still guard against two sessions of one installation that drive the same device.
54+
Simlock's "advisory, not a sandbox" model applies.
55+
agent-device does not verify that a device is leased.
5256

5357
## 3. Consequences
5458

55-
- The `managed-allocation` package, managed request admission and reachability, the `managed-local`
56-
runtime owner kind, allocator-held device claims, and the managed device scope in platform
57-
readiness and deployment are removed. A persisted durable-resource envelope naming a
58-
`managed-local` owner decodes as unreattachable, and a schema-3 device-claim record as
59-
inconsistent; no shipped production path ever wrote either.
60-
- `device status` and `device release --stale` no longer report an `owner.kind: "allocator"` shape
61-
or the `allocator-held` classification. Released v0.21.24 could print them but never produced them.
62-
- Remote access to a leased device uses Simlock's own gateway or HTTP API, or agent-device's
63-
existing `proxy` and remote daemon; neither depends on the other.
64-
- The CLI and daemon take no per-request Android adb server port: one daemon talks to one adb
65-
server, so agents holding leases from different Simlock daemons use separate state dirs. The Node
66-
SDK's `agent-device/android-adb` functions run the caller's own adb executor, so the caller points
67-
that executor at Simlock's server; the per-call `serverPort` in `AndroidAdbExecutorOptions` takes
68-
effect only when that executor honors it.
59+
- These components are removed:
60+
- The `managed-allocation` package.
61+
- Managed request admission and reachability.
62+
- The `managed-local` runtime owner kind.
63+
- Allocator-held device claims.
64+
- Managed device scope in platform readiness and deployment.
65+
A persisted durable-resource envelope with a `managed-local` owner decodes as unreattachable.
66+
A schema-3 device-claim record decodes as inconsistent.
67+
No shipped production path wrote either representation.
68+
- `device status` and `device release --stale` no longer report `owner.kind: "allocator"` or `allocator-held`.
69+
Released v0.21.24 could print these values but never produced them.
70+
- Remote access to a leased device uses Simlock's own gateway or HTTP API, or the existing agent-device `proxy` and remote daemon.
71+
Neither system depends on the other.
72+
- The CLI and daemon accept no per-request Android adb server port.
73+
One daemon uses one adb server.
74+
Therefore, agents with leases from different Simlock daemons use separate state directories.
75+
Node SDK `agent-device/android-adb` functions run the caller's own adb executor.
76+
Therefore, the caller points that executor at Simlock's server.
77+
Per-call `AndroidAdbExecutorOptions.serverPort` takes effect only if the executor honors it.
6978

7079
## 4. Withdrawn design
7180

72-
The replaced design required a durable allocation journal reconciled through Simlock after crashes,
73-
fenced lease admission with renewal covering each command deadline plus teardown, a managed runtime
74-
owner delegating to the local family, and allocator-held device claims whose principal was an
75-
installation rather than a process. Recover it from git history (ADR text before 2026-10-10,
76-
#2284, #2308, #2312) if an in-process allocator returns.
81+
The replaced design required these components:
82+
83+
- A durable allocation journal reconciled through Simlock after crashes.
84+
- Fenced lease admission with renewal across each command deadline and teardown.
85+
- A managed runtime owner that delegates to the local family.
86+
- Allocator-held device claims with an installation principal instead of a process principal.
87+
88+
If an in-process allocator returns, recover that design from git history: the ADR text before 2026-10-10, #2284, #2308, and #2312.

0 commit comments

Comments
 (0)