Skip to content

Commit 054682a

Browse files
committed
docs(adr-0012): conditional matchCount, dependency-ordered migration, writer invariant, suggestion ranking contract
1 parent 6b5a1b2 commit 054682a

1 file changed

Lines changed: 70 additions & 23 deletions

File tree

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 70 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -158,8 +158,20 @@ already travels in the `.ad` file.
158158

159159
`--update`/`-u` stops silently rewriting `.ad` files. The two pieces of machinery it already has —
160160
`collectReplaySelectorCandidates` (recorded-chain/positional extraction) and the `resolveSelectorChain`
161-
re-resolution it drives — are repurposed to populate a ranked list of selector suggestions inside the
162-
divergence report (decision 4), not to act unattended. With an agent in the loop, adjudicating a heal
161+
re-resolution it drives — are repurposed to populate the ranked `suggestions` list inside the
162+
divergence report (decision 4), not to act unattended.
163+
164+
**Ranking is a total order**: (1) candidates satisfying more identity components rank first — a
165+
recorded-id match outranks a role+label match, which outranks a label-only match; (2) among equals,
166+
candidates in the same `scrollRegion` as recorded rank before candidates in other regions; (3) document
167+
order is the final tie-break. Suggestions are deduplicated by node: a node reachable through several
168+
recorded selector terms appears once, tagged with its strongest match basis. The list is bounded by
169+
decision 4's suggestion cap. Response levels affect only report content, never file behavior: before
170+
retirement lands (migration step 6), `--update` keeps its legacy rewrite semantics regardless of level;
171+
after retirement, `--update` at any level performs no rewrite and returns the same bounded suggestions
172+
object, with `--level digest` omitting suggestion entries but carrying `suggestionCount` per decision 4.
173+
174+
With an agent in the loop, adjudicating a heal
163175
proposal costs one cheap model turn — cheaper than discovering a silent wrong repair later — and the
164176
audit ((a) above) already found heal rarely able to act. A proposal an agent can accept, reject, or edit
165177
is strictly more valuable than the same proposal applied blind.
@@ -247,6 +259,16 @@ bytes** after normalization; the whole payload is at most **4 KiB**; `ancestry`
247259
entries; `sibling` and `viewportOrder` are non-negative safe integers. The parser rejects a v1 annotation
248260
exceeding these bounds with `INVALID_ARGS`.
249261

262+
**Writer-parser invariant.** The recorder must never emit a payload its own parser rejects. When a
263+
payload would exceed the 4 KiB ceiling after per-field truncation, the writer reduces it
264+
deterministically: drop `ancestry` entries one at a time from the **root side** — the same side ancestry
265+
truncation already drops from — until the payload fits. If it still overflows with only `ancestry[0]`
266+
(the parent) retained, the writer downgrades the annotation to `verification: "unverifiable"`
267+
(fail-closed) rather than writing an invalid or silently-lossy script; with the per-field 256-byte caps
268+
in force, a parent-only payload fits arithmetically, so the downgrade branch is a terminal guarantee,
269+
not an expected path. The record-time self-check (step 5 below) runs against the reduced tuple, so a
270+
`verified` claim is always honest for exactly what was written.
271+
250272
**Local identity.** Two nodes share local identity when both carry `id` and the normalized ids are equal;
251273
or, when the recording carries no `id`, when their normalized roles are equal and their normalized labels
252274
are equal (label absent on both sides counts as equal; label present on exactly one side is a mismatch).
@@ -307,8 +329,13 @@ script preserves v1 annotations in canonical form; it must not silently discard
307329

308330
**Replay-time verification.** Every annotated resolved target is checked before its action is sent, by
309331
this exact classification. `matchCount` is the number of current nodes matching the **recorded selector**
310-
at replay time — the same match set resolution itself used — with range **0..N** and **always present**
311-
in the report's `targetBinding`. Identity verification applies only when `matchCount >= 1`.
332+
at replay time — the same match set resolution itself used — with range **0..N**. It is **required on
333+
every path that performs resolution (paths 2–6 below) and absent on path 1** — the key is omitted per
334+
the drop-empty-keys convention, never `null` — because path 1 fires before any resolution. No
335+
diagnostic-only count is computed there: a recorded-unverifiable annotation means there is no
336+
trustworthy recorded identity to resolve against, so a count would invite misreading and add capture
337+
cost on a path that by definition cannot verify. Identity verification applies only when
338+
`matchCount >= 1`.
312339

313340
1. Recorded `verification` is `"unverifiable"` → **identity-unverifiable** divergence, before any
314341
resolution.
@@ -352,7 +379,11 @@ mismatch. The object has version `1` and contains `kind`, `step` (`index`, `sour
352379
`action`, `cause`, `screen`, `suggestions`, `resume`, and, for binding failures, `targetBinding`
353380
(`classification`, `matchCount`, `recorded`, `observed`, `mismatches`, `candidates`). `kind` is one of
354381
`action-failure`, `selector-miss`, `identity-mismatch`, or `identity-unverifiable` — the latter three are
355-
decision 3's target-binding classes, and `targetBinding.matchCount` is always present for them (0..N).
382+
decision 3's target-binding classes, and `targetBinding.classification` always equals the top-level
383+
`kind`. `targetBinding.matchCount` follows decision 3's presence rule exactly: present (0..N) for
384+
`selector-miss`, `identity-mismatch`, and an `identity-unverifiable` reached through resolution (path 6);
385+
absent — key omitted, never `null` — when `identity-unverifiable` arose from a recorded-unverifiable
386+
annotation (path 1), which fires before any resolution.
356387
`step.index` is the 1-based executable-plan ordinal, not a source
357388
line. Its source location is diagnostic only. A Maestro parser must preserve the original file and line
358389
through includes so that source location is actionable.
@@ -364,8 +395,10 @@ the old session tree. Screen-capture failure never replaces or masks the origina
364395

365396
Response levels bound the entire serialized UTF-8 `details.divergence` object, not merely its arrays:
366397
compact (`--level digest`) is at most **8 KiB**, default at most **24 KiB**, and full at most **64 KiB**.
367-
Compact carries at most **8** screen refs and no suggestions; default and full carry at most **20** screen
368-
refs and **5** ranked suggestions. These counts are absolute, including error payloads. Individual
398+
Compact carries at most **8** screen refs and no suggestion entries — it carries `suggestionCount` (the
399+
number of suggestions available at default/full) so a caller knows whether a re-fetch at a higher level
400+
has material; default and full carry at most **20** screen refs and **5** suggestions ranked per
401+
decision 1's total order. These counts are absolute, including error payloads. Individual
369402
labels, ids, selectors, source paths, mismatch values, cause messages, and hints are UTF-8 truncated to
370403
**256 bytes**; an action summary has no positional array, and fill text, expanded variables, and arbitrary
371404
nested cause details are never serialized. All rendered strings and any overflow artifact pass through the
@@ -433,15 +466,16 @@ Implementation is not accepted on benchmark evidence alone. Required automated c
433466
record and replay, a recorded scroll region that no longer exists (unavailable, never compared
434467
cross-region), out-of-range ordinals, and document-order determinism for equal rect centers and
435468
rect-less members — plus divergence-report tests for
436-
compact/default/full field and byte ceilings, redaction, overflow artifacts and artifact-write failure,
469+
compact/default/full field and byte ceilings (including digest-level `suggestionCount` with entries
470+
omitted), redaction, overflow artifacts and artifact-write failure,
437471
available versus sparse/capture-failed screen forms, and preservation of the original cause;
438472
- replay resume tests for plan-digest emission and mismatch rejection after script/include/expansion
439473
changes, `resume.allowed` reasons, `--from` indexing, variable-output and control-flow rejection, and
440474
`test --from` rejection;
441475
- daemon/client/CLI/MCP contracts proving the typed divergence survives failure, JSON and MCP structured
442476
output retain it, MCP pins only actionable error-path refs, and no text-only path drops the report; and
443477
- `--update` retirement tests proving it never rewrites the source file and only returns bounded
444-
suggestions.
478+
suggestions ranked and deduplicated per decision 1's total order.
445479

446480
Extend the settle benchmark (`~/.agent-device-bench/rnnav-matrix.py` pattern, external harness) with a
447481
replay arm only after these contracts pass: measure clean replay and one induced divergence repaired
@@ -494,17 +528,30 @@ through the allowed `--from` loop.
494528

495529
## Migration plan
496530

497-
Each step lands independently useful, in order:
498-
499-
1. **Resolution disclosure** (decision 2) — update all six matrix cells, the exact waiver list, and
500-
provider mutation contracts together. It is additive to response data and does not claim direct-iOS
501-
selection parity or issue pre-action refs.
502-
2. **`.ad` target annotations** (decision 3) — land bounded parser/writer round trips, compatibility,
503-
structural uniqueness, and duplicate detection before recording. Recording and pre-action
504-
target-binding verification then land together.
505-
3. **Structured divergence + `replay --from`** (decision 4) — land bounded/redacted error propagation,
506-
actionable-or-unavailable screen semantics, error-path MCP pinning, plan digest validation, and
507-
conservative resume preflight together. `test` does not expose `--from`.
508-
4. **`--update` retirement** (decision 1) — remove its write path only after divergence suggestions are
509-
available, with a no-write regression test.
510-
5. **Benchmark extension** (decision 5) follows the mandatory contracts and measures the economic claim.
531+
Steps are ordered so every dependency lands before its consumer; each step is independently useful, and
532+
each states its dependencies explicitly.
533+
534+
1. **Resolution disclosure** (decision 2) — no dependencies. Update all six matrix cells, the exact
535+
waiver list, and provider mutation contracts together. Additive to response data; does not claim
536+
direct-iOS selection parity or issue pre-action refs.
537+
2. **Structured divergence transport** (decision 4, report only) — no dependencies. `REPLAY_DIVERGENCE`
538+
with `kind: "action-failure"` attaches to the EXISTING replay failure paths: step provenance (source
539+
path + line preserved through Maestro includes), bounded/redacted payloads, actionable-or-unavailable
540+
screen semantics, error-path MCP pinning, ranked suggestions (decision 1's candidate machinery,
541+
read-only), and the one-line text success summary. Immediately useful on its own — this closes the
542+
provenance/evidence gaps the live hands-on evidence documents — and introduces no verification
543+
semantics.
544+
3. **`.ad` target annotations, inert** (decision 3, parser/writer only) — no dependencies. Bounded
545+
parser/writer round trips, the writer-parser invariant with root-side reduction, old/new reader
546+
compatibility, structural uniqueness, and duplicate detection. Recordings gain annotations; replay
547+
parses and preserves them but does not yet enforce.
548+
4. **Target-binding verification** (decision 3, enforcement) — depends on 2 (reports through the
549+
divergence transport, adding the `selector-miss`/`identity-mismatch`/`identity-unverifiable` kinds)
550+
and on 3 (consumes the annotations).
551+
5. **`replay --from` + `--plan-digest` resume** (decision 4, resume) — depends on 2 only (the report
552+
supplies `resume` and `planDigest`); may land before, with, or after 3/4. `test` does not expose
553+
`--from`.
554+
6. **`--update` retirement** (decision 1) — depends on 2 (ranked suggestions must be available in the
555+
report before the write path is removed), with a no-write regression test.
556+
7. **Benchmark extension** (decision 5) — follows the mandatory contracts; measures the economic claim
557+
(clean replay plus one induced divergence repaired through the allowed `--from` loop).

0 commit comments

Comments
 (0)