Skip to content

Commit ce49ed1

Browse files
committed
docs: correct replay decision owner contracts
1 parent e73e7c3 commit ce49ed1

7 files changed

Lines changed: 60 additions & 63 deletions

File tree

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ An inserted or removed wrapper ancestor changes identity.
6666
Replay classifies every annotated step before dispatch through six exact verification paths.
6767
Only a verified result sends the action.
6868
Anything that the evidence cannot isolate is an `identity-unverifiable` divergence, never a silent pick.
69-
The recorder must never emit a payload that its parser rejects. If bounded evidence still exceeds the payload limit, the writer downgrades it to `verification: "unverifiable"` instead of writing an invalid script.
69+
The recorder must never emit a payload that its parser rejects. The writer downgrades oversized evidence to `verification: "unverifiable"` and drops its rect. Escape-heavy values can still exceed the serialized limit; the implementation does not recheck after dropping the rect.
7070
The format is additive. Old readers ignore the comment, and new readers run unannotated actions without the check.
7171
An annotation binds only to the next physical action line.
7272

@@ -97,7 +97,7 @@ Resume is `replay --from N --plan-digest <sha>`.
9797
`N` is a 1-based index into the fully expanded executable plan.
9898
`test` rejects `--from`, because a suite run must remain full and deterministic.
9999
`planDigest` covers the canonical expanded plan, including identity evidence and the effective target, so an edit cannot silently change ordinal N's target.
100-
Resume reconstructs no state: preflight rejects a resume that skips an `outputEnv` producer or enters runtime control flow.
100+
Resume reconstructs no state. Maestro preflight rejects a resume that skips an `outputEnv` producer or enters runtime control flow.
101101
`resume.allowed` describes plan resumability only. `resume.repairSessionHeld` is the only session-lifetime signal.
102102
`resume.alternateFrom` offers the recorded-correction ordinal for dual-path hints.
103103

@@ -107,7 +107,7 @@ The loop is:
107107
2. Read the divergence.
108108
3. Repair the app state.
109109
4. Replay with the reported plan digest and index.
110-
If you completed the failed action manually, use the next index: `from` for `record-and-heal`, or `alternateFrom` for `caution`/`manual`.
110+
If you completed the failed action as a recorded action, use the next index: `from` for `record-and-heal`, or `alternateFrom` for `caution`/`manual`.
111111

112112
An edited script requires a fresh full replay and a new digest.
113113
The [divergence and resume contract](../../packages/ad-replay/docs/divergence-and-resume.md) owns the fields, bounds, redaction, surfaces, ordinals, watermark, and digest.
@@ -201,5 +201,5 @@ The [divergence construction contract](../../packages/replay-port/docs/replay-di
201201

202202
- Deterministic state reconstruction for resume needs a separate specification and tests.
203203
- The replay benchmark arm of decision 5 is deferred.
204-
- A `--force`/`--overwrite` override for `--save-script` publication is out of scope (#1258). Automatic versioned healed names are also out of scope.
204+
- Automatic versioned healed names are out of scope.
205205
- Read-only coverage stays deferred for `is exists`, `is absent`, `wait absent`, read-only `find`, and `wait` forms without an element target.

‎docs/adr/0020-composable-recorded-fragments.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -303,7 +303,7 @@ The absolute resolved filesystem path is excluded.
303303
Therefore, a child move keeps the child digest, but it requires an explicit parent locator edit and parent repin.
304304

305305
The digest excludes session timestamps, device names, absolute source paths, and ordinary comments.
306-
Native `${VAR}` placeholders remain unresolved in the digest, as ADR 0012's late-bound-value rule requires.
306+
Native `${VAR}` placeholders remain unresolved in the digest, as the [plan digest contract](../../packages/ad-replay/docs/divergence-and-resume.md#plan-digest) requires.
307307
Maestro's effective static environment and parse-time expansion continue to participate in the Maestro plan digest under ADR 0015.
308308
A changed target annotation changes the digest because the annotation changes execution-time verification.
309309
The reason is not that the annotation is diagnostic text.
@@ -663,7 +663,7 @@ This is the intentional v1 tradeoff: stale reuse stays visible, and multiple flo
663663
Screen identity is app semantics.
664664
A caller-selected, identity-bearing landmark reuses the verified `wait` contract, and no cross-platform fingerprint is necessary.
665665
- **Expand all fragments into one flat global plan: rejected.**
666-
ADR 0012's Maestro include incident showed that expansion-only provenance shifts ordinals and loses the included source boundary.
666+
The [divergence provenance contract](../../packages/ad-replay/docs/divergence-and-resume.md#report-fields) preserves source files and lines through Maestro includes, where expansion can shift ordinals and lose the included source boundary.
667667
A nested plan may execute actions in order, but it must retain the fragment address at every step.
668668
- **Use path-only or floating includes: rejected.**
669669
A shared file can change between authoring and replay.

‎packages/ad-replay/docs/divergence-and-resume.md‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ A plain ref returns `plain_ref_requires_complete_frame`.
115115
`--from N` belongs only to `replay`.
116116
`test` must reject it with `INVALID_ARGS` because a suite run must remain full and deterministic.
117117
`N` is a 1-based index into the fully expanded executable plan.
118-
`N` must be in range.
118+
`N` must be in the plan range, except for the watermark-authorized empty-tail resume described below.
119119
It is not a YAML line, fractional source-step number, or repeat iteration label.
120120
Static includes, platform conditions, and fixed-count repeats expand before indexing.
121121
Repeated source lines therefore have distinct plan indices.
@@ -124,7 +124,7 @@ Every divergence includes `resume: { allowed, from, reason?, planDigest, alterna
124124
`repairHint` determines `from` (ADR 0012 decision 6, R2/R3):
125125

126126
- For `record-and-heal`, `from` is the index of the failed step **+ 1** (N + 1).
127-
The agent performs that step manually before it resumes.
127+
The agent performs that step as a recorded action before it resumes.
128128
A resume AT that step would diverge again on the exact step that the agent just completed.
129129
- For `state-repair`, `caution`, and `manual`, `from` remains **N**.
130130

@@ -140,11 +140,9 @@ For `caution`/`manual`, there are two legitimate repairs, and the daemon cannot
140140
- App-state fix: use `--no-record`, then repeat unchanged step N at `from`.
141141
- Recorded correction: perform step N's intent as a recorded action, then continue at N + 1.
142142

143-
`alternateFrom` carries N + 1 only if that request passes `evaluateReplayResumePreflight({ from: N + 1, actions }).allowed`.
144-
Step N must itself be safe to skip.
145-
A `runScript` `outputEnv` producer or runtime control flow therefore prevents this alternate.
146-
The alternate preflight examines a strict superset of the primary range.
147-
Thus, `alternateFrom` implies `allowed: true`.
143+
`alternateFrom` carries N + 1 for these hints when it is in range, or when a live session can authorize an empty tail.
144+
The builder does not run a separate plan-safety preflight for the alternate.
145+
The `ReplayResumeCheck` list validates range, corrective action growth, and digest on the resume request.
148146
`record-and-heal` omits it because `from` already carries N + 1.
149147
`state-repair` omits it because it has no recorded-action alternate.
150148
Text renders the N + 1 command **if and only if `alternateFrom` exists**.
@@ -159,10 +157,10 @@ An armed transaction becomes `COMPLETE`, which permits its later `close` commit.
159157
Otherwise, `close` would abort the incomplete transaction and discard the correction.
160158

161159
This ordinal requires authorization from the exact session and target that produced it.
162-
The daemon stamps a per-session watermark (`expectedFrom`, the recorded action count at divergence time) in these cases:
160+
The daemon stamps a per-session watermark (`expectedFrom`, the authorized resume ordinal, and `actionsCountAtDivergence`, the recorded action count at divergence time) in these cases:
163161

164162
- For `record-and-heal` with `allowed: true`, the reported `from` is already N + 1.
165-
- For a preflight-safe `caution`/`manual` final-step alternate, the watermark uses `alternateFrom` N + 1.
163+
- For a `caution`/`manual` final-step alternate, the watermark uses `alternateFrom` N + 1.
166164
The primary `from` remains N.
167165

168166
Only a live session can receive this watermark.
@@ -215,7 +213,7 @@ Thus a consumer must not read `allowed: true` as "the session is still there."
215213
## Preflight
216214

217215
Resume reconstructs no execution state.
218-
For `N > 1`, preflight must reject with `INVALID_ARGS` under either condition:
216+
For Maestro plans and `N > 1`, preflight rejects with `INVALID_ARGS` under either condition:
219217

220218
- A skipped action can produce `outputEnv` values.
221219
- The skipped range or resume target is inside runtime conditional, retry, or dynamic-repeat control flow.

‎packages/ad-script/docs/target-annotation.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
# Target annotations
22

33
These contracts supplement [ADR 0012](../../../docs/adr/0012-interactive-replay.md) decision 3.
4-
`@agent-device/ad-script` parses, writes, and classifies `target-v1` and `targets-v1` annotations.
4+
`@agent-device/ad-script` parses, serializes, and classifies `target-v1` and `targets-v1` annotations.
5+
`@agent-device/selectors` builds record-time evidence and owns the writer-parser invariant.
56
`@agent-device/contracts` holds their shape.
67

78
## Format
@@ -64,10 +65,10 @@ The recorder must never emit a payload that its parser rejects.
6465
If per-field truncation still leaves more than 4 KiB, the writer removes `ancestry` entries from the root side, one at a time.
6566
This reduction is deterministic and uses the existing ancestry truncation direction.
6667
If only `ancestry[0]` remains and the payload still exceeds the limit, the writer sets `verification: "unverifiable"`.
67-
It must not write an invalid or silently lossy script.
68-
With the 256-byte field limits, a parent-only payload fits arithmetically.
69-
Thus, this downgrade is a terminal guarantee, not an expected path.
70-
The record-time self-check uses the reduced tuple.
68+
The limit measures serialized UTF-8 bytes, while field limits apply before JSON escaping.
69+
The writer drops `rect` if the downgraded payload still exceeds the limit, but does not recheck afterward.
70+
Escape-heavy values can therefore still produce an over-limit annotation that the parser rejects.
71+
When the reduced tuple fits, the record-time self-check uses that tuple.
7172
A `verified` claim therefore applies to exactly the written evidence.
7273

7374
Action-mode evidence has another independent cause for the same `"unverifiable"` downgrade (#1398, ADR 0017).
@@ -239,7 +240,7 @@ Every comparison is therefore deterministic and total.
239240
Otherwise, write `verification: "unverifiable"`.
240241
Both ordinals derive from the winner over deterministic total orders.
241242
Thus, the self-check succeeds by construction whenever the capture supplies the required structural data.
242-
Record-time `unverifiable` identifies a capture anomaly, such as missing parent linkage.
243+
An `unverifiable` result from this self-check identifies a capture anomaly, such as missing parent linkage.
243244
It is a fail-closed safeguard, not an expected path.
244245
At replay, it causes `identity-unverifiable` before an action.
245246

@@ -288,7 +289,7 @@ Identity verification applies only when `matchCount >= 1`.
288289
The same child index can recur under different parents.
289290
- **Region-scoped viewportOrder:** restrict I to the partition whose scroll-region key equals the recorded `scrollRegion`.
290291
If `scrollRegion` is omitted, use the *none* partition.
291-
If the partition is empty, the recorded scroll region no longer exists.
292+
If the partition is empty, no identity-set candidate is in the recorded region.
292293
Then `viewportOrder` is **unavailable**, and it is never compared across regions.
293294
Otherwise, order centers top-to-bottom, then left-to-right.
294295
Resolve equal centers by document order.

‎packages/command-runtime/docs/resolution-disclosure.md‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@ Successful structural-collapse diagnostics remain **pre-action diagnostics**.
1717
They issue no refs.
1818
After mutation, neither `winnerDiagnostic` nor `alternatives` may serve as an `@ref` target.
1919
An ambiguity rejection performs no mutation.
20-
Its bounded candidate lines issue a partial ref frame and `refsGeneration`.
21-
CLI prints pinned candidates. MCP remembers their generation for immediate retry.
20+
When the consumed capture is the tree stored under the frozen generation, its bounded candidate lines issue a partial ref frame and `refsGeneration`.
21+
CLI prints pinned candidates, and MCP remembers their generation for immediate retry.
22+
Otherwise the error returns the match count without candidate refs or an act-on-candidate hint.
2223
A post-action `--settle` diff remains a separate actionable issuer.
2324
A target-binding divergence also sends no action.
2425
It issues its fresh report snapshot under the [divergence contract](../../ad-replay/docs/divergence-and-resume.md).
@@ -30,19 +31,19 @@ A successful lookup of the `@ref` itself returns `{ source: "ref", phase: "pre-a
3031
The runtime-ref path can recover a stale or unusable `@ref` through its recorded trailing label.
3132
`tryResolveRefNode` uses `fallbackLabel` for this first-match label lookup.
3233
This recovery returns `{ source: "ref", phase: "pre-action", kind: "label-fallback" }`.
33-
Label recovery must never claim exact ref provenance.
34+
Runtime-ref label recovery discloses its fallback provenance.
3435

3536
The native-ref fast path always discloses `exact`.
3637
It dispatches the ref handle and forwards the recorded `fallbackLabel` to the backend.
37-
The daemon cannot observe any backend label recovery.
38-
Thus, `exact` describes only daemon resolution.
39-
This path cannot make a more specific claim.
38+
The daemon preflight can itself recover a node by label, but the response still discloses `exact`.
39+
Backend label recovery is also not reflected in the response.
40+
Thus, this disclosure can misstate ref provenance.
4041

4142
## Direct-iOS selector
4243

4344
The accepted direct-iOS selector fast path has no daemon tree.
4445
The XCTest response cannot establish a match count, candidate refs, or a runtime tiebreak.
45-
This path remains enabled for an ordinary simple `press`.
46+
This path requires a Maestro-compatible `click` with `allowNonHittableCoordinateFallback`; ordinary presses use runtime resolution.
4647
Its canonical unique-match response contains `resolution: { source: "direct-ios", kind: "not-observed" }`.
4748
It must never invent a unique-match or identity claim.
4849
XCTest counts raw exact matches before it applies hittability.

‎packages/daemon/docs/replay-repair-transaction.md‎

Lines changed: 16 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Across a repair session, original steps that verified and dispatched enter `sess
1414
The corrective interactive actions of the agent enter `session.actions`.
1515
Corrective actions receive fresh `target-v1` evidence because recording is armed.
1616
Armed recording also disables the direct-iOS fast path, which permits evidence computation.
17-
`formatSessionScript` serializes actions from the repair boundary onward (R6).
17+
`prepareSessionScript` serializes actions from the repair boundary onward (R6).
1818

1919
## Sub-flows
2020

@@ -157,32 +157,17 @@ It cannot double-commit or trigger no-clobber refusal again.
157157
## Publication
158158

159159
Commit serializes the healed slice with a final `close` line for self-contained output.
160-
It creates a temp file **in the final target's directory**.
161-
An explicit target can be on another mount, and `linkSync` requires the same filesystem.
162-
One exclusive `linkSync(temp, target)` then publishes with create-if-absent, first-writer-wins semantics.
163-
Readers never see partial output.
160+
It creates a temp file in the target directory so publication works across mounts and readers never see partial output.
161+
Without `--force`/`--overwrite`, publication uses an exclusive `linkSync` and refuses an existing target for both repair and ordinary recording.
162+
With the flag, publication uses atomic replacement; concurrent forced writers are last-writer-wins.
163+
Repair arming refuses an existing target unless the flag is set.
164+
The same publication primitive serves repair and ordinary recording.
165+
Without force, an existing target returns an `EEXIST` error and leaves its bytes unchanged.
166+
The opt-in persists across `--from` continuation on the same target.
167+
Retargeting drops the opt-in unless that request supplies its own flag.
164168
Aborted repair leaves no partial file.
165-
166-
Publication refuses every pre-existing target.
167-
This applies to complete/partial files and default/explicit paths.
168-
`EEXIST` occurs if and only if a file already exists at the target, irrespective of its content.
169-
The caller must remove it or select another `replay --save-script=<path>`.
170-
The existing file is never silently replaced.
171-
There is no lock, lease, ownership transfer, or overwrite.
172-
`# agent-device:heal-complete` remains a trailing marker of a complete, reviewable artifact.
173-
It does not affect publication permission.
174-
Automatic versioned names, such as `.healed.2.ad`, remain out of scope as a separate naming change.
175-
176-
The refusal applies to repair and ordinary recording.
177-
`publishHealedScriptAtomically` is the one publication primitive used by `SessionScriptWriter.write` for every `--save-script` target.
178-
It has no repair/ordinary branch.
179-
Repair sets `saveScriptBoundary`; ordinary `open --save-script`/`close --save-script` recording does not.
180-
Both use the same exclusive `linkSync`.
181-
An ordinary recording with an existing target receives the same `AppError` for `EEXIST`.
182-
The existing bytes remain unchanged.
183-
The caller must remove the file or select another path.
184-
Neither path has a `--force`/`--overwrite` override.
185-
Issue #1258 tracks that future work.
169+
`# agent-device:heal-complete` remains a trailing marker of a complete, reviewable artifact; it does not authorize publication.
170+
Automatic versioned names remain out of scope.
186171

187172
## Tombstone
188173

@@ -204,7 +189,7 @@ This supersedes the stage 1 (#1287) guidance to pass `--no-record` by hand on ea
204189

205190
**1. Exclusion depends on provenance.** Both conditions must hold:
206191

207-
- The command is observation-only: `snapshot`, `get`, `is`, or read-only `find` (`exists`, `wait`, `get_text`, `get_attrs`).
192+
- The command is observation-only: `snapshot`, `get`, `is`, or read-only `find` (`exists`, `wait`, `get_text`, `get_attrs`, `list`).
208193
Mutating `find … click|fill|focus|type` remains a corrective action like `press`/`fill` and always records.
209194
The top-level `wait` command is deliberately **not** in this set.
210195
It is flow timing/synchronization, not observation, so it must keep recording unconditionally.
@@ -263,7 +248,7 @@ Every surface reaches that same daemon function.
263248
The flags retain their different scopes:
264249

265250
- Common `--no-record` belongs to `COMMON_COMMAND_SUPPORTED_FLAG_KEYS`.
266-
Every recordable reader forwards it with `noRecordInputFromFlags`.
251+
Every recordable reader forwards it with `commonInputFromFlags`.
267252
- Scoped `--record` is not common.
268253
Only `snapshot`/`get`/`is` and dynamically validated `find` permit it.
269254
Only their readers use `observationRecordInputFromFlags`.
@@ -318,8 +303,9 @@ The guard's message adds `--record` beside `--no-record` because correction can
318303
After `COMMITTED`, teardown is idempotent and never republishes.
319304
- An armed replay skips its terminal source `close` without session deletion.
320305
- The temp file uses the target directory.
321-
One exclusive `linkSync` publishes it with create-if-absent, first-writer-wins semantics.
322-
- Publication refuses **every** existing target and preserves its bytes.
306+
Without force, one exclusive `linkSync` publishes it with create-if-absent, first-writer-wins semantics.
307+
With force, atomic replacement permits overwriting.
308+
- Without force, publication refuses **every** existing target and preserves its bytes.
323309
This includes complete/partial files, the default healed sibling, and explicit `--save-script=<path>`.
324310
It also includes ordinary non-repair `open`/`close --save-script` recording.
325311
- Observation exclusion:

0 commit comments

Comments
 (0)