Skip to content

Commit 6741749

Browse files
thymikeeclaude
andcommitted
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]>
1 parent e35d0d4 commit 6741749

6 files changed

Lines changed: 1303 additions & 1472 deletions

File tree

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

Lines changed: 149 additions & 1472 deletions
Large diffs are not rendered by default.
Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
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+
If bounded output omits material, the daemon writes the same redacted, per-field-bounded detail to a session-scoped divergence 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 range.
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 manually 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 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`.
148+
`record-and-heal` omits it because `from` already carries N + 1.
149+
`state-repair` omits it because it has no recorded-action alternate.
150+
Text renders the N + 1 command **if and only if `alternateFrom` exists**.
151+
Clients never recompute resumability.
152+
Text and structured output therefore advertise identical commands.
153+
154+
## Empty-tail resume and the corrective watermark
155+
156+
`actions.length + 1` is a legal **empty-tail resume** for a repaired final step.
157+
It executes zero device actions and follows normal end-of-plan completion.
158+
An armed transaction becomes `COMPLETE`, which permits its later `close` commit.
159+
Otherwise, `close` would abort the incomplete transaction and discard the correction.
160+
161+
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:
163+
164+
- 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.
166+
The primary `from` remains N.
167+
168+
Only a live session can receive this watermark.
169+
Without one, an empty-tail `alternateFrom` is omitted.
170+
Otherwise, the daemon would advertise a `--from N + 1` that it must then reject.
171+
Examples include a one-step `open` failure or a session closed during replay.
172+
A later empty-tail resume must match the watermark and show growth in the session's action count.
173+
That growth proves a corrective action was recorded.
174+
It prevents unrelated or blind resumes from skipping the unresolved last step and committing an incomplete repair.
175+
Every other `record-and-heal` continuation uses the same watermark and count-growth guard, including ordinals inside the plan.
176+
If the count is unchanged, resume refuses to skip the unrepaired step.
177+
178+
## Plan digest
179+
180+
`planDigest` is SHA-256 over the canonical fully expanded plan.
181+
It includes command, normalized inputs, control shape, platform-conditioned expansion, and source provenance.
182+
Normalized inputs include positionals/flags, execution-affecting `runtime` hints, and `target-v1` identity evidence.
183+
Identity evidence affects pre-action execution and must therefore affect the digest.
184+
Platform-conditioned expansion uses the **effective resolved `platform`/`target`**.
185+
CLI flags override script metadata.
186+
A digest for one target is not reusable for another.
187+
Native `.ad` `${VAR}` **values are excluded** because substitution follows planning.
188+
Changes only to late-bound values retain the digest.
189+
Maestro substitutes environment values during compatibility parsing.
190+
Those values can change action inputs, includes, or control expansion and therefore the digest.
191+
192+
Resume requires both `--from N` and `--plan-digest <planDigest>` from the report.
193+
The daemon rebuilds the current plan.
194+
If the digest differs, it returns `INVALID_ARGS` before any action.
195+
Edits or parse-time expansion cannot silently change ordinal N's target.
196+
An edited script requires a fresh full replay and a new digest.
197+
`allowed: false` explains why resume is unsafe.
198+
Its digest remains diagnostic and cannot bypass preflight.
199+
200+
## Resumability and session lifetime
201+
202+
`allowed` describes **plan resumability only**.
203+
Every divergence emits it.
204+
It says nothing about session lifetime.
205+
The separate `repairSessionHeld: true` signal identifies an active repair transaction persisted on the session.
206+
A `--save-script` replay opens the transaction.
207+
Commit or abort ends the transaction (ADR 0012 decision 6, R7).
208+
The daemon sets `repairSessionHeld: true` until the transaction ends.
209+
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.
210+
Only this signal promises a live addressable daemon/session for repair.
211+
R7's lifetime guarantee never uses `allowed`.
212+
A non-armed replay can report `allowed: true` and then terminate its session normally.
213+
Thus a consumer must not read `allowed: true` as "the session is still there."
214+
215+
## Preflight
216+
217+
Resume reconstructs no execution state.
218+
For `N > 1`, preflight must reject with `INVALID_ARGS` under either condition:
219+
220+
- A skipped action can produce `outputEnv` values.
221+
- The skipped range or resume target is inside runtime conditional, retry, or dynamic-repeat control flow.
222+
223+
After resume, only explicit script/header, CLI, and shell inputs supply variables.
224+
If the planner cannot prove that scope, it rejects the request.
225+
The daemon never infers app state.
226+
Before resume, the caller must establish the required app state.
227+
228+
Help documents the resume protocol and resume rejections.
229+
Successful text replay prints one line with replayed count and wall time.
230+
`--json` remains structured.
231+
232+
## Required coverage
233+
234+
- 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.
235+
- 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.
236+
- Surfaces: daemon/client/CLI/MCP tests prove typed divergence survives failure.
237+
JSON and MCP structured output retain it.
238+
MCP pins only actionable error-path refs.
239+
No text-only path discards the report.
240+
`repairHint` is present and identical in text, JSON, client `AppError`, and MCP `structuredContent`, including compact `--level digest`.
241+
- `--update` retirement: no source-file rewrite; suggestions remain bounded, ranked, and deduplicated under the suggestion total order.

0 commit comments

Comments
 (0)