Skip to content

Commit 79157ed

Browse files
committed
docs(adr): mark the unshipped ADR 0026 rules and narrow two claims
Recording ADR 0026 as Accepted made two unshipped rules read as current: the "every removed source" row and the ejection ledger in Contracts. Both now name #2754 step 5 as the open contract, and the `ScrollArea` passages record the decision #2759 shipped instead of asking for one. ADR 0004's boundary sentence said the gate covers the facet; it covers only the roots `snapshot-policy` declares, so the overlay modules beside that tree are now named as outside it. ADR 0005's keying sentence claimed the runner reports nothing; it is the runner-side classification of the command that plays no part, while the refusal code selects the budget.
1 parent cbb1634 commit 79157ed

3 files changed

Lines changed: 41 additions & 34 deletions

File tree

‎docs/adr/0004-ios-snapshot-backend-strategy.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -140,9 +140,10 @@ facet in `@agent-device/capture-kit` owns snapshot policy generally rather than
140140
daemon keeps approved artifact and ref assembly only: ranking, projection to screenshot pixels,
141141
drawing, and PNG IO.
142142

143-
`scripts/layering/snapshot-presentation-boundary.test.ts` enforces the direction across the roots
144-
declared for `snapshot-policy` in `scripts/layering/architecture-ownership.ts`: nothing in those
145-
roots may import `src/daemon/`. It carries a positive control, because a filter that stopped
143+
`scripts/layering/snapshot-presentation-boundary.test.ts` enforces the direction, but only across
144+
the roots `snapshot-policy` declares in `scripts/layering/architecture-ownership.ts`: nothing in
145+
that snapshot tree may import `src/daemon/`, while the overlay modules beside the tree sit outside
146+
those roots and are outside that gate. It carries a positive control, because a filter that stopped
146147
matching would look identical to a boundary being obeyed.
147148

148149
The residual call sites #1983 also named are audited and deliberately left in place.

‎docs/adr/0005-ios-runner-interaction-lifecycle.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -65,17 +65,17 @@ therefore drained), and left intact by a transport failure or an unstamped recov
6565
healthy `ok` is never read as proof of drain because a private-AX snapshot can be served while an
6666
abandoned tree crawl still grinds on the XCTest main thread (#2552).
6767

68-
What a `RUNNER_BUSY` refusal then costs the caller is keyed on the daemon's own per-command read-only
69-
trait, not on anything the runner reports: `RUNNER_COMMAND_TRAITS` in
70-
`packages/platform-apple/src/runner/runner-command-traits.ts`, read through `isReadOnlyRunnerCommand`
71-
where `runAppleRunnerCommand` decides whether to wrap the send in a resend loop. The asymmetry is
72-
shipped, and asserted in `runner-command-busy-resend.test.ts`: a read-only command treats the refusal
73-
as *not yet*, waiting the drain out on a budget sized to outlast it and resending until the runner
74-
answers or the window ends; a mutating command treats the same refusal as *not mine to send again* —
75-
one attempt, and the refusal reaches the caller unwrapped with nothing replayed. Neither path pays a
76-
status probe, because a structured reply already answered "did my command run?" (the bypass in
77-
`runner-lifecycle.ts`). The same trait already decides the startup-preflight skip above, so it is the
78-
single place a change to that classification lands.
68+
What a `RUNNER_BUSY` refusal then costs the caller turns on the daemon's own per-command read-only
69+
trait, not on any runner-side classification of the command: `RUNNER_COMMAND_TRAITS` in
70+
`packages/platform-apple/src/runner/runner-command-traits.ts`, read through
71+
`isReadOnlyRunnerCommand` where `runAppleRunnerCommand` decides whether to wrap the send in a resend
72+
loop. The asymmetry is shipped, and asserted in `runner-command-busy-resend.test.ts`: a read-only
73+
command treats the refusal as *not yet*, waiting the drain out on the busy-specific budget sized to
74+
outlast it and resending until the runner answers or the window ends; a mutating command treats the
75+
same refusal as *not mine to send again* — one attempt, and the refusal reaches the caller unwrapped
76+
with nothing replayed. Neither path pays a status probe, because a structured reply already answered
77+
"did my command run?" (the bypass in `runner-lifecycle.ts`). The same trait already decides the
78+
startup-preflight skip above, so it is the single place a change to that classification lands.
7979

8080
Close that would retain a runner for reuse first stops it when that occupancy is set, awaiting the
8181
stop so the lease is released before the next request. A runner still finishing watchdog-abandoned

‎docs/adr/0026-scroll-clip-authority.md‎

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,8 @@ Accepted (2026-09-22). The ownership decision is shipped: #2758 reads an indicat
66
parent edge, climbing only same-frame ancestors — the tolerance the #2754 step 3 survey justified on
77
real captures — and #2759 pairs the two eligibility lists and settles `ScrollArea` for macOS. Two
88
#2754 steps stay open work rather than part of this decision: the runner-stage differential arm, and
9-
the typed ejection disposition behind the "every removed source" row below, which is that step's
10-
contract and not a description of `main`. Refines ADR 0004's fact/interpretation boundary for scroll
11-
geometry; does not supersede it.
9+
the typed ejection disposition the "every removed source" row below names. Refines ADR 0004's
10+
fact/interpretation boundary for scroll geometry; does not supersede it.
1211

1312
An interactive iOS snapshot of a list dropped every row after a row holding selectable text. A
1413
`UITextView` is a UIScrollView and XCTest publishes its scroll indicator inside the text, so the
@@ -27,7 +26,7 @@ walking up past the indicator's parent, and that guess decided which nodes exist
2726
| Removing a node **because a scroll band hides it** | Requires evidence: the clip fold's result, or a band whose owner is the indicator's parent. A guess about ownership may not do it |
2827
| Removing a node by semantic delegation — a collapsed row, a duplicate label, a wrapper's content | Out of scope here. That is compaction, and it keeps its own authority |
2928
| Weaker evidence than a parent edge | Directional hints (`hiddenContentAbove` / `hiddenContentBelow`) and nothing that changes membership |
30-
| Every removed source | Ends with a typed disposition. Internal evidence, never wire vocabulary |
29+
| Every removed source | Must end with a typed disposition — the open #2754 step 5 contract, not shipped code. Internal evidence, never wire vocabulary |
3130

3231
## Contracts
3332

@@ -52,25 +51,30 @@ neither eligible set contains it, and the iOS runner never emits it — it origi
5251
`AXScrollArea` mapping. That helper's trees do reach these rules, through `snapshot-desktop-surface.ts`
5352
→ `ios-snapshot-runtime.ts` → `publishIosSnapshot`, so on that surface a `ScrollArea` host can be dropped
5453
by eligibility while its children re-parent past it, which leaves a parent-edge lookup with no owner.
55-
Reusing this rule for macOS therefore needs a `ScrollArea` eligibility decision made there, not carried
56-
over from the iOS claim above.
54+
Reusing this rule for macOS therefore needed a `ScrollArea` eligibility decision made there, not
55+
carried over from the iOS claim above, and #2759 made it with cases rather than by admitting the
56+
type for iOS's sake: `scrollarea` stays out of both eligible sets, a `ScrollArea` carrying content
57+
survives eligibility on those trees and owns its band, and a label-less one is dropped, leaving its
58+
indicator with no owner to band — which under-clips (safe) instead of mis-clipping the enclosing
59+
list (`eligibility-parity.test.ts`).
5760

5861
**Why the band exists at all.** XCTest reports a scroll view's frame spanning the bars and the safe
5962
area, not the visible track. In the pinned Settings tree the `CollectionView` frame is the whole screen,
6063
0–874, while its indicator track is 116–812 (`runner-presentation.test.ts`). The frame alone therefore
6164
cannot express visibility, and deleting indicator clipping would return content that is scrolled under
6265
the chrome. The band is necessary; only *who owns it* was ever in question.
6366

64-
**Visibility ejection needs evidence, and every ejection is recorded.** Most of the engine's 23 removal
65-
sites delegate semantics or drop decoration — a collapsed row, a duplicate label, a wrapper's content, a
66-
system indicator — and this ADR does not touch their authority. It governs the four visibility-driven
67-
sites among them, the scroll band's one and the keyboard band's three, alongside the clip fold's own
68-
inclusion decision in `geometry-policy.ts`. Of those, the scroll band is the one a weak signal can reach,
69-
and directional hints are its safe outlet when nothing is the indicator's parent. Every source index ends
70-
either presented, with its representatives, or removed with a typed reason, which makes the ledger complete
71-
by construction rather than gated. The existing `presentedIndexesBySourceIndex` in
72-
`ios-snapshot-engine/semantic-index.ts` is the shape to extend; a second parallel ledger would be a second
73-
source of truth.
67+
**Visibility ejection needs evidence, and every ejection must be recorded.** Most of the engine's 23
68+
removal sites delegate semantics or drop decoration — a collapsed row, a duplicate label, a
69+
wrapper's content, a system indicator — and this ADR does not touch their authority. It governs the
70+
four visibility-driven sites among them, the scroll band's one and the keyboard band's three,
71+
alongside the clip fold's own inclusion decision in `geometry-policy.ts`. Of those, the scroll band
72+
is the one a weak signal can reach, and directional hints are its safe outlet when nothing is the
73+
indicator's parent. Every source index must end either presented, with its representatives, or
74+
removed with a typed reason, which makes the ledger complete by construction rather than gated;
75+
#2754 step 5 still owes that reason, and `presentedIndexesBySourceIndex` in
76+
`ios-snapshot-engine/semantic-index.ts` records representatives and no removal reason today. That
77+
ledger is the shape to extend; a second parallel ledger would be a second source of truth.
7478

7579
## Refuted alternatives
7680

@@ -123,10 +127,12 @@ source of truth.
123127
upward. So `findScrollIndicatorContainer` returns null when the node is itself a scroll type;
124128
`runner-presentation.test.ts` pins a scroll host labelled as an indicator leaving its parent list's
125129
band intact.
126-
- **macOS is already a second consumer of these rules.** Desktop capture runs the engine through
127-
`snapshot-desktop-surface.ts` → `ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry
128-
`ScrollArea`, which neither eligible set admits. The parent-edge rule needs its own decision there
129-
before it is reused, not a carry-over from the iOS claim.
130+
- **macOS is already a second consumer of these rules, and #2759 settled its `ScrollArea`
131+
question.** Desktop capture runs the engine through `snapshot-desktop-surface.ts` →
132+
`ios-snapshot-runtime.ts` → `publishIosSnapshot`, and its trees carry `ScrollArea`, which neither
133+
eligible set admits: a content-bearing one survives eligibility and owns its band; a label-less
134+
one is dropped and leaves its indicator with no owner, under-clipping instead of mis-clipping the
135+
list. `eligibility-parity.test.ts` pins both outcomes and the TS/Swift eligibility pair.
130136
- **Ejection inventory precedes any API change.** 23 suppression sites across ten rules, and two of them
131137
(`scroll`, `transitions`) already rewrite rects on other nodes in the same pass that ejects — the
132138
combination the proposed API split claimed to make impossible.

0 commit comments

Comments
 (0)