Skip to content

Commit 89fbfc3

Browse files
thymikeeclaude
andauthored
docs: slim interactive replay ADR to a decision record (#4331)
* docs: slim interactive replay ADR to a decision record Move the target annotation, divergence, resume, repair transaction, and resolution disclosure contracts to their owning packages. Part of #4205. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(adr): correct ADR 0012 owner docs from cross-provider review List all eight resolutionDisclosure matrix cells, including target-drag and find-focus-dispatch, with the real maestro-direct-selector id. Write the overflow artifact only when the level-capped report still exceeds its byte ceiling. State that client keep-alive already uses sessionActive. * docs: correct replay decision owner contracts * docs(daemon): name the surfaced script_target_exists error --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 709b869 commit 89fbfc3

7 files changed

Lines changed: 1306 additions & 1474 deletions

File tree

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

Lines changed: 149 additions & 1472 deletions
Large diffs are not rendered by default.

‎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.
Lines changed: 239 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,239 @@
1+
# Divergence report and resume
2+
3+
These contracts supplement [ADR 0012](../../../docs/adr/0012-interactive-replay.md) decision 4.
4+
`@agent-device/contracts` holds the `details.divergence` shape.
5+
`@agent-device/ad-replay` bounds the report and resolves the resume point.
6+
The [divergence construction contract](../../replay-port/docs/replay-divergence.md) owns the screen, the suggestions, and `repairHint` computation.
7+
8+
## Report fields
9+
10+
Both action failure and target-binding mismatch return `ok:false`, code `REPLAY_DIVERGENCE`, and `details.divergence`.
11+
The version `1` object contains these fields:
12+
13+
- `kind`
14+
- `step` (`index`, `source.path`, `source.line`)
15+
- `action`
16+
- `cause`
17+
- `screen`
18+
- `suggestions`
19+
- `resume`
20+
- `repairHint`
21+
- For binding failures, `targetBinding` (`classification`, `matchCount`, `recorded`, `observed`, `mismatches`, `candidates`)
22+
23+
`kind` is `action-failure`, `selector-miss`, `identity-mismatch`, or `identity-unverifiable`.
24+
The last three are the target-binding classes of the [target annotation contract](../../ad-script/docs/target-annotation.md).
25+
`targetBinding.classification` always equals top-level `kind`.
26+
The verification path determines `targetBinding.matchCount` presence:
27+
28+
- Present, with range 0..N, for `selector-miss` and `identity-mismatch`
29+
- Present for resolution-derived `identity-unverifiable` (path 6)
30+
- Omitted, never `null`, for recorded-unverifiable evidence before resolution (path 1)
31+
32+
`step.index` is the 1-based executable-plan ordinal.
33+
The source location is diagnostic only.
34+
A Maestro parser must preserve original files and lines through includes so the caller can use the location.
35+
36+
`repairHint` is one bounded enum value from a fixed closed set: `record-and-heal`, `state-repair`, `caution`, `manual`.
37+
It is never a list.
38+
The daemon computes it under ADR 0012 decision 6, R3.
39+
Every divergence includes it, with `manual` when no safer route is proven.
40+
It is never absent or null.
41+
Its small fixed size permits inclusion at every response level, including `--level digest`.
42+
It must survive these four projections unchanged: daemon text summary, JSON, Node client `AppError`, and MCP `structuredContent`.
43+
44+
`screen` has two discriminated forms.
45+
`{ state: "available", refsGeneration, refs, truncated }` is a fresh healthy snapshot digest.
46+
Only this form issues actionable refs.
47+
`{ state: "unavailable", reason, hint }` indicates failed or sparse capture.
48+
It has no refs or generation and must not reuse the old session tree.
49+
Capture failure never replaces or conceals the original replay cause.
50+
51+
## Bounds
52+
53+
Response limits apply to the entire serialized UTF-8 `details.divergence` object:
54+
55+
| Response level | Byte ceiling | Screen refs | Suggestions |
56+
| --- | --- | --- | --- |
57+
| Compact (`--level digest`) | 8 KiB | At most 8 | No entries; `suggestionCount` |
58+
| Default | 24 KiB | At most 20 | At most 5 |
59+
| Full | 64 KiB | At most 20 | At most 5 |
60+
61+
`suggestionCount` counts entries available at default/full level.
62+
It tells callers whether a higher-level fetch has more material.
63+
Default/full suggestions follow the suggestion total order.
64+
Counts are absolute, including error payloads.
65+
These individual values are UTF-8 truncated to **256 bytes**: labels, ids, selectors, source paths, mismatch values, cause messages, and hints.
66+
67+
An action summary has no positional array.
68+
Arbitrary nested cause details are never serialized.
69+
Maestro failure provenance uses resolved diagnostic identifiers, including targets and `runFlow` paths.
70+
It names the attempted runtime operation instead of unresolved `${VAR}` or synthetic `<var:VAR>` tokens.
71+
72+
## Redaction
73+
74+
Text-entry payloads remain semantic secrets.
75+
`inputText` progress, failure messages, suggestions, and overflow artifacts never serialize entered text.
76+
Injected replay values are not global sensitive literals.
77+
Otherwise, a short ordinary value such as `2` or `on` would corrupt unrelated timestamps, paths, and typed error fields throughout the request log.
78+
The actual text-entry dispatch boundary registers values before platform work, independently of the failure projection.
79+
Users must not put secrets in selectors, links, filenames, or other diagnostic identifiers expected in failure output.
80+
81+
Native `.ad` replay retains categorical `<var:NAME>` replacement in human-readable divergence messages, hints, and bounded diagnostic fields.
82+
This existing fail-closed policy remains separate from Maestro compatibility output.
83+
Semantically masked positionals and daemon-owned machine-readable fields and paths never receive substring replacements.
84+
The report marks every truncation, redaction, and omission.
85+
86+
## Overflow
87+
88+
Level caps apply first. Only when the level-capped serialized report still exceeds its byte ceiling does the daemon write the same redacted, per-field-bounded detail to a session-scoped divergence artifact. Material that level caps omit while the report fits creates no artifact.
89+
It returns the path and `overflow: { omittedBytes, artifactPath }`.
90+
If the write fails, it returns `artifactUnavailable: true` and preserves the original error.
91+
The artifact contains no raw snapshot tree or unredacted input.
92+
93+
## Surfaces
94+
95+
All surfaces preserve the daemon error.
96+
The Node client rejects with `AppError` and retains `details.divergence`.
97+
CLI exits nonzero.
98+
Text shows a compact report; JSON includes the complete structured error.
99+
MCP returns `isError: true`, the object in `structuredContent`, and the same compact text summary.
100+
MCP treats divergence as a ref-issuing result, including on the error path.
101+
Before return, it merges and pins every `screen` ref with `refsGeneration`.
102+
CLI and direct clients receive the daemon error's unpinned refs and generation.
103+
No surface may reduce divergence to text and discard repair data.
104+
105+
Divergence `screen.refs` issues a bounded partial ref frame (ADR 0014).
106+
`markSessionPartialRefsIssued` authorizes exactly those refs.
107+
MCP pins them automatically.
108+
CLI text renders `@eN~s<refsGeneration>`.
109+
JSON and Node.js callers pair each plain ref with the response-level generation before mutation.
110+
A mutation through this partial frame requires a pinned ref.
111+
A plain ref returns `plain_ref_requires_complete_frame`.
112+
113+
## Resume ordinal
114+
115+
`--from N` belongs only to `replay`.
116+
`test` must reject it with `INVALID_ARGS` because a suite run must remain full and deterministic.
117+
`N` is a 1-based index into the fully expanded executable plan.
118+
`N` must be in the plan range, except for the watermark-authorized empty-tail resume described below.
119+
It is not a YAML line, fractional source-step number, or repeat iteration label.
120+
Static includes, platform conditions, and fixed-count repeats expand before indexing.
121+
Repeated source lines therefore have distinct plan indices.
122+
123+
Every divergence includes `resume: { allowed, from, reason?, planDigest, alternateFrom?, repairSessionHeld? }`.
124+
`repairHint` determines `from` (ADR 0012 decision 6, R2/R3):
125+
126+
- For `record-and-heal`, `from` is the index of the failed step **+ 1** (N + 1).
127+
The agent performs that step as a recorded action before it resumes.
128+
A resume AT that step would diverge again on the exact step that the agent just completed.
129+
- For `state-repair`, `caution`, and `manual`, `from` remains **N**.
130+
131+
For single-path hints (`record-and-heal`, `state-repair`), `from` describes the complete continuation.
132+
A JSON/MCP-first caller that blindly resumes at `resume.from` therefore reads the same command that the text guidance renders.
133+
It never gets a stale `from` that loops the caller back onto the step that it just repaired.
134+
For dual-path hints (`caution`, `manual`), `from` describes only app-state repair.
135+
Their optional `alternateFrom` describes recorded correction.
136+
Structured callers read both fields to obtain both text alternatives.
137+
138+
For `caution`/`manual`, there are two legitimate repairs, and the daemon cannot disambiguate them at divergence time (#1262):
139+
140+
- App-state fix: use `--no-record`, then repeat unchanged step N at `from`.
141+
- Recorded correction: perform step N's intent as a recorded action, then continue at N + 1.
142+
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.
146+
`record-and-heal` omits it because `from` already carries N + 1.
147+
`state-repair` omits it because it has no recorded-action alternate.
148+
Text renders the N + 1 command **if and only if `alternateFrom` exists**.
149+
Clients never recompute resumability.
150+
Text and structured output therefore advertise identical commands.
151+
152+
## Empty-tail resume and the corrective watermark
153+
154+
`actions.length + 1` is a legal **empty-tail resume** for a repaired final step.
155+
It executes zero device actions and follows normal end-of-plan completion.
156+
An armed transaction becomes `COMPLETE`, which permits its later `close` commit.
157+
Otherwise, `close` would abort the incomplete transaction and discard the correction.
158+
159+
This ordinal requires authorization from the exact session and target that produced it.
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:
161+
162+
- For `record-and-heal` with `allowed: true`, the reported `from` is already N + 1.
163+
- For a `caution`/`manual` final-step alternate, the watermark uses `alternateFrom` N + 1.
164+
The primary `from` remains N.
165+
166+
Only a live session can receive this watermark.
167+
Without one, an empty-tail `alternateFrom` is omitted.
168+
Otherwise, the daemon would advertise a `--from N + 1` that it must then reject.
169+
Examples include a one-step `open` failure or a session closed during replay.
170+
A later empty-tail resume must match the watermark and show growth in the session's action count.
171+
That growth proves a corrective action was recorded.
172+
It prevents unrelated or blind resumes from skipping the unresolved last step and committing an incomplete repair.
173+
Every other `record-and-heal` continuation uses the same watermark and count-growth guard, including ordinals inside the plan.
174+
If the count is unchanged, resume refuses to skip the unrepaired step.
175+
176+
## Plan digest
177+
178+
`planDigest` is SHA-256 over the canonical fully expanded plan.
179+
It includes command, normalized inputs, control shape, platform-conditioned expansion, and source provenance.
180+
Normalized inputs include positionals/flags, execution-affecting `runtime` hints, and `target-v1` identity evidence.
181+
Identity evidence affects pre-action execution and must therefore affect the digest.
182+
Platform-conditioned expansion uses the **effective resolved `platform`/`target`**.
183+
CLI flags override script metadata.
184+
A digest for one target is not reusable for another.
185+
Native `.ad` `${VAR}` **values are excluded** because substitution follows planning.
186+
Changes only to late-bound values retain the digest.
187+
Maestro substitutes environment values during compatibility parsing.
188+
Those values can change action inputs, includes, or control expansion and therefore the digest.
189+
190+
Resume requires both `--from N` and `--plan-digest <planDigest>` from the report.
191+
The daemon rebuilds the current plan.
192+
If the digest differs, it returns `INVALID_ARGS` before any action.
193+
Edits or parse-time expansion cannot silently change ordinal N's target.
194+
An edited script requires a fresh full replay and a new digest.
195+
`allowed: false` explains why resume is unsafe.
196+
Its digest remains diagnostic and cannot bypass preflight.
197+
198+
## Resumability and session lifetime
199+
200+
`allowed` describes **plan resumability only**.
201+
Every divergence emits it.
202+
It says nothing about session lifetime.
203+
The separate `repairSessionHeld: true` signal identifies an active repair transaction persisted on the session.
204+
A `--save-script` replay opens the transaction.
205+
Commit or abort ends the transaction (ADR 0012 decision 6, R7).
206+
The daemon sets `repairSessionHeld: true` until the transaction ends.
207+
A `--from` continuation without `--save-script` still reports `repairSessionHeld: true`, because the persisted transaction state determines this field, not the flags of the current request.
208+
Only this signal promises a live addressable daemon/session for repair.
209+
R7's lifetime guarantee never uses `allowed`.
210+
A non-armed replay can report `allowed: true` and then terminate its session normally.
211+
Thus a consumer must not read `allowed: true` as "the session is still there."
212+
213+
## Preflight
214+
215+
Resume reconstructs no execution state.
216+
For Maestro plans and `N > 1`, preflight rejects with `INVALID_ARGS` under either condition:
217+
218+
- A skipped action can produce `outputEnv` values.
219+
- The skipped range or resume target is inside runtime conditional, retry, or dynamic-repeat control flow.
220+
221+
After resume, only explicit script/header, CLI, and shell inputs supply variables.
222+
If the planner cannot prove that scope, it rejects the request.
223+
The daemon never infers app state.
224+
Before resume, the caller must establish the required app state.
225+
226+
Help documents the resume protocol and resume rejections.
227+
Successful text replay prints one line with replayed count and wall time.
228+
`--json` remains structured.
229+
230+
## Required coverage
231+
232+
- Divergence reports: compact/default/full field and byte ceilings; digest output includes `suggestionCount` without entries; redaction, overflow artifacts, artifact-write failure, available/sparse/capture-failed screens, and original-cause preservation.
233+
- Resume: digest emission and rejection after script/include/expansion changes; `resume.allowed` reasons, `--from` indexing, variable-output rejection, control-flow rejection, and `test --from` rejection.
234+
- Surfaces: daemon/client/CLI/MCP tests prove typed divergence survives failure.
235+
JSON and MCP structured output retain it.
236+
MCP pins only actionable error-path refs.
237+
No text-only path discards the report.
238+
`repairHint` is present and identical in text, JSON, client `AppError`, and MCP `structuredContent`, including compact `--level digest`.
239+
- `--update` retirement: no source-file rewrite; suggestions remain bounded, ranked, and deduplicated under the suggestion total order.

0 commit comments

Comments
 (0)