@@ -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
163175proposal costs one cheap model turn — cheaper than discovering a silent wrong repair later — and the
164176audit ((a) above) already found heal rarely able to act. A proposal an agent can accept, reject, or edit
165177is 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`
247259entries; ` sibling ` and ` viewportOrder ` are non-negative safe integers. The parser rejects a v1 annotation
248260exceeding 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;
251273or, when the recording carries no ` id ` , when their normalized roles are equal and their normalized labels
252274are 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
309331this 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
3133401 . 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
357388line. Its source location is diagnostic only. A Maestro parser must preserve the original file and line
358389through 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
365396Response levels bound the entire serialized UTF-8 ` details.divergence ` object, not merely its arrays:
366397compact (` --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
369402labels, 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
371404nested 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
446480Extend the settle benchmark (` ~/.agent-device-bench/rnnav-matrix.py ` pattern, external harness) with a
447481replay 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