|
| 1 | +# ADR 0039: Pre-dispatch admission for resolved targets |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +Accepted. |
| 6 | +This record owns the checks that run after an interaction target is resolved and before input is sent. |
| 7 | +It narrows how [ADR 0011](0011-interaction-guarantee-contract.md) paths declare those checks. It keeps the frame rules of [ADR 0014](0014-session-ref-frame-lifetime.md), the plan rules of [ADR 0013](0013-unified-gesture-plans.md), and the dispatch ledger. |
| 8 | +[#4456](https://github.com/callstack/agent-device/issues/4456) holds the migration plan. |
| 9 | + |
| 10 | +## Context |
| 11 | + |
| 12 | +Pre-input checks exist so that an action reports success only when the intended control could receive it. They reject a target that is still moving, a covered target, a point inside a system bar, or a control that a fading view still blocks. |
| 13 | + |
| 14 | +There is no owner for this step. |
| 15 | +The moving-target gate runs only for runtime-resolved press and click. Long-press, fill, hover and drag skip it. |
| 16 | +Its waits ignore the request deadline and cancellation signal (`packages/command-runtime/src/commands/runtime-common.ts`). |
| 17 | +Each new check brings its own place, loop, evidence carrier and refusal reason. |
| 18 | +#4391 adds an iOS readiness poll and revalidation beside the gate, about 970 production lines, and a native read on every idle press. |
| 19 | +#4446 adds Android system-bar bounds as a private symbol on each node. |
| 20 | +Both patch the in-memory session clone to keep their private facts. |
| 21 | +State that decides the outcome is implicit: object identity between captures, closures, private side tables, and the `deferredSurface` baseline that one request leaves for the next. |
| 22 | + |
| 23 | +## Decision |
| 24 | + |
| 25 | +**One owner.** Command runtime has one pre-dispatch admission step for resolved targets. |
| 26 | +Every resolved-target interaction calls it between resolution and the backend call: press, click, long-press, double-tap, hover, fill, and each endpoint of a target-authored drag. |
| 27 | +Static resolution guards (visibility, parent-owned touch point, covered annotation) stay in their shared owner and run first. Admission consumes their result. |
| 28 | + |
| 29 | +**Typed checks with declared policy.** Admission runs an ordered list of checks over one evidence bundle. Today the list is motion and readiness. |
| 30 | +Each check returns pass, wait, or refuse with a typed reason. Unknown geometry, a covered target, an ambiguous native binding, and a native read failure keep distinct reasons. |
| 31 | +Each interaction declares which checks apply and their policy in its ADR 0011 path row, with the maximum extra reads on the accept path. |
| 32 | + |
| 33 | +**One budget and one loop.** All waiting in admission uses one loop under one hard bound: the earlier of the request execution and result deadlines, and any explicit intent cap. |
| 34 | +The loop checks cancellation and the bound before and after every awaited read, before every sleep, and immediately before dispatch. |
| 35 | +Transition windows are anchored once; a retry does not restart them. |
| 36 | +The loop reuses the observation engine in `packages/capture-kit/src/observe-until.ts` with a hard bound that a verdict or minimum poll count cannot extend. Other consumers keep its soft budget. |
| 37 | +While only a live fact is blocked, the loop polls that fact. When a fact or geometry changes, dependent checks run again on fresh evidence before dispatch. |
| 38 | + |
| 39 | +**Evidence provenance.** Platform facts reach admission as typed private evidence, owned by `packages/contracts/src/snapshot-private-evidence.ts`. |
| 40 | +One operation constructs, copies and remaps that evidence across projection and cloning. Checks and stores do not add side tables or per-field clone patches. |
| 41 | +A live probe result is separate evidence with its own producer, surface and generation. It is never relabeled as part of an older capture. |
| 42 | + |
| 43 | +**Cost.** On the accept path an idle target pays no extra capture, probe or sleep. |
| 44 | +A live probe, such as iOS native hittability, runs only when its policy asks: after a mutation left a motion baseline, or when static evidence cannot decide. |
| 45 | + |
| 46 | +**Preserved authority.** Frame admission and its error precedence stay first (ADR 0014). Ref expiry stays immediately before the leaf side effect. |
| 47 | +Pinned replay and find targets, repeated-action plans, and system sheets keep their current rules. |
| 48 | +A refusal before any send reports `dispatched: no`. A failure after a send reports what the ledger recorded. |
| 49 | + |
| 50 | +## Rejected alternatives |
| 51 | + |
| 52 | +- **One admission stage for every input, with admitted-only backend signatures.** Raw points, native refs, coordinate gestures, keyboard and remote input do not have a resolved target. The stage would add captures they do not need and would break ADR 0011, 0013, 0014 and 0031 guarantees. |
| 53 | +- **Path declarations alone.** Declaring order and cost in ADR 0011 makes omissions visible but leaves two wait loops and two matchers on the press path. |
| 54 | +- **Fused native tap-if-authorized as the readiness design.** It can shorten the gap between read and tap on iOS, but it does not solve waiting on other platforms and element hittability still does not prove the point receives input. It stays a separate, measured optimization behind the readiness check. |
| 55 | +- **A check per PR, as today.** Each fix adds a loop, a carrier and a reason, and the paths drift apart. |
| 56 | + |
| 57 | +## Consequences and open gaps |
| 58 | + |
| 59 | +The admission step replaces the two motion schedules in `packages/command-runtime/src/commands/interaction/runtime/moving-target-gate.ts` and the readiness poll proposed in #4391. #4391 and #4446 move their facts and checks onto this owner. |
| 60 | +Long-press, fill, hover and drag gain the motion check. Their accept-path latency must not grow. |
| 61 | +An app-timed overlay that appears with no preceding mutation is not detected on an idle press. This is the cost rule's trade-off and matches the gate's existing blind spot. |
| 62 | +Partial custom covers (#4347) and safe regions for coordinate-authored trajectories stay open. Admission gives them a place; it does not solve them. |
0 commit comments