Skip to content

Commit 2c6a177

Browse files
committed
docs(daemon): put the baseline's real shape in the docs that describe it (#3471)
Three places said less than the code does, all found in review: - `MovingTargetBaseline.tree` named only the pre-action tree. #3538 asked for this doc to be widened when the writer landed, because it cannot be read truthfully from that layer: the converged-settle case records the tree that settle published as rest, not the one the action started from. - `markMovingTargetBaseline` listed "a raw coordinate" among the routes that leave the session idle. A point target with `--verify` or `--settle` DOES capture a tree in `resolvePointInteractionTarget`, so the idle list is the routes with no tree of their own, not the point-shaped ones. - `DeferredSurface.stabilize.baselineSignature` still pointed at `markPostGestureStabilization`, which is `markSurfaceStabilization` now. Also shrinks five comments that were narrating control flow rather than stating the invariant: the field-owner claim, the retirement comment, the carrier comment, and two guarantee cells. Line counts matter at this layer's budget, and a claim in prose is worth less than the same claim in a name.
1 parent e9ff161 commit 2c6a177

7 files changed

Lines changed: 19 additions & 22 deletions

File tree

‎packages/contracts/src/interaction-guarantees.ts‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -85,12 +85,11 @@ export const INTERACTION_GUARANTEES = [
8585
'outcomeObservation',
8686
// The position the path dispatches at is one the target is confirmed to be at REST in (#3471).
8787
// Distinct from every guard above: those judge a tree, this judges the tree against the previous
88-
// action's tree. A capture is one instant's photograph of a surface that may still be
89-
// rearranging itself, and the ADB-backed Android helper is measured reporting frames in flight,
90-
// so a press issued right after an action that animated the UI can resolve a point the target has
91-
// already vacated and report success on the vacancy. The gate is backend-neutral: it re-observes
92-
// past the window and refuses rather than dispatching at a position two observations disagree
93-
// about.
88+
// action's tree. A capture is one instant's photograph of a surface that may still be rearranging
89+
// itself — the ADB-backed Android helper is measured reporting frames in flight — so a press
90+
// issued right after an action that animated the UI can resolve a point the target has already
91+
// vacated and report success on the vacancy. The gate is backend-neutral: it re-observes past the
92+
// window and refuses rather than dispatching at a position two observations disagree about.
9493
'targetStability',
9594
] as const;
9695

‎packages/contracts/src/moving-target-gate.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,10 @@ export type MovingTargetBaseline = Readonly<{
4848
* clock's time too. Production installs none, so both sides read the wall clock.
4949
*/
5050
finishedAt: number;
51-
/** The pre-action tree — the observation the action's own resolution came out of. */
51+
/**
52+
* The tree the action acted through: its resolution's own observation, or the settled one its
53+
* `--settle` published as rest.
54+
*/
5255
tree: SurfaceScopedNodes;
5356
}>;
5457

‎scripts/layering/session-state.ts‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -52,10 +52,8 @@ export const SESSION_STATE_FIELD_OWNERS: Readonly<Record<string, readonly string
5252

5353
trace: ['src/daemon/handlers/trace-runtime.ts'],
5454
// #3471 and #1542 share one field: what the session still owes after its last mutation. The two
55-
// variants are mutually exclusive by construction, and every transition — a gesture marking the
56-
// capture-side loop, a press recording its resolving tree (#3471), a side effect retiring it, a
57-
// capture discharging it — lives in this module, so neither mechanism can quietly overwrite the
58-
// other's claim about the surface.
55+
// variants are mutually exclusive, and every transition between them is owned by
56+
// `deferred-interaction-outcome.ts`, so neither mechanism can overwrite the other's claim.
5957
deferredSurface: ['src/daemon/deferred-interaction-outcome.ts'],
6058

6159
// App identity follows open, deployment and observation through named patches.

‎src/daemon/deferred-interaction-outcome.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -157,9 +157,9 @@ function markSurfaceStabilization(
157157
* older snapshot would attribute to this action a surface it never looked at. A tree that names no
158158
* nodes records nothing either, for the same reason — an empty tree would make every later target
159159
* read as newly arrived, which is a claim about motion no action here ever observed. That is also
160-
* why the routes that dispatch without a daemon tree (a raw coordinate, a Maestro direct-selector
161-
* tap, `back`, an app open) leave the session idle: the ordinary navigate-then-tap step pays the
162-
* gate nothing.
160+
* why the routes that dispatch with no tree of their own leave the session idle: a raw coordinate
161+
* unless `--verify`/`--settle` made it capture one, a Maestro direct-selector tap, `back`, an app
162+
* open. The ordinary navigate-then-tap step pays the gate nothing.
163163
*
164164
* `restProved` switches the tree to the session's published one, and is set only when the action's
165165
* own settle loop converged AND stored its settled tree. Everything else keeps the pre-action tree,

‎src/daemon/ref-frame.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -94,8 +94,8 @@ export function expireRefFrame(session: SessionState): void {
9494
markSessionSnapshotOutdated(session);
9595
session.refFrame = expiredRefFrame(refFrame(session));
9696
session.snapshotScopeSource = undefined;
97-
// #3471: a side effect this session did not resolve a target through leaves a tree that predates a
98-
// change nobody measured, so it cannot screen a later press.
97+
// #3471: a side effect no resolved target was aimed through leaves a tree predating an unmeasured
98+
// change, so it cannot screen a later press.
9999
retireMovingTargetBaseline(session);
100100
}
101101

‎src/daemon/runtime-session.ts‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,8 @@ function toRuntimeSessionRecord(
2727
): CommandSessionRecord | undefined {
2828
if (!session) return undefined;
2929
const frameTree = refFrameTree(session);
30-
// #3471: the moving-target gate judges a freshly resolved rect against the tree the PREVIOUS
31-
// action acted through, so that tree has to reach the command layer — the `snapshot` beside it is
32-
// the newest observation, which is the one thing that cannot show a target having moved. Absent
33-
// whenever the session is idle or owes the capture-side loop instead, which is what makes an
34-
// ordinary press pay the gate nothing.
30+
// #3471: the gate judges a fresh rect against the tree the PREVIOUS action acted through, so that
31+
// tree has to reach the command layer; the `snapshot` beside it cannot show a target having moved.
3532
const baseline = movingTargetBaseline(session);
3633
return {
3734
name,

‎src/daemon/session-state.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ export type DeferredSurface =
9999
/**
100100
* Pre-gesture interaction-surface signature, captured from the session's
101101
* last-known snapshot before the gesture dispatched (no extra capture — see
102-
* `markPostGestureStabilization`). Populated only when
102+
* `markSurfaceStabilization`). Populated only when
103103
* `requiresPostGestureBaselineDistrust` is true for the session's device
104104
* (Apple mobile only, #1542 defect 2): a post-gesture quiet-poll match that
105105
* still equals this baseline is a stale-but-internally-consistent AX read,

0 commit comments

Comments
 (0)