Skip to content

Commit 5134f53

Browse files
committed
docs: resolve ref-frame contract blockers
1 parent fee1415 commit 5134f53

3 files changed

Lines changed: 69 additions & 27 deletions

File tree

‎CONTEXT.md‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,11 +54,7 @@
5454
- Parity table: golden JSON fixture under `contracts/fixtures/` consumed by both vitest and the runner's gated Swift tests, so a cross-language rule (e.g. tap-point policy) cannot drift silently. Change the rule only via the table.
5555
- Coverage manifest: `CONTRACT_COVERAGE` export beside each interaction contract test file claiming which matrix cells it proves; the coverage gate requires every enforced/delegated cell to be claimed and rejects overclaims of waived cells.
5656
- Delegation-on-error: a fast path falling back to the runtime path on semantic failure shapes. It closes failure-side guarantee cells only — never success-path parity.
57-
- Ref frame: session-scoped authorization namespace containing the accessibility refs that a caller may use for mutation. It is distinct from operational observations used internally for selector matching, settling, freshness, and diagnostics.
58-
- Ref-frame epoch: seeded monotonic version of the current ref frame, exposed once per issuing response as `refsGeneration`. It advances when a frame is published, superseded, or expired; it does not make refs stable across frames.
59-
- Ref-frame activation: session transition that makes a captured namespace current for subsequent mutation admission. Complete activation authorizes its plain-ref namespace; partial activation authorizes only the explicitly issued generation-pinned refs. An explicit snapshot leaf may activate a frame for later predeclared batch/replay steps even when the outer response elides the tree.
60-
- Ref issuance: client- or workflow-visible publication of refs with their ref-frame epoch. Internal freshness, recovery, diagnostic, and cached captures do not issue refs.
61-
- Ref generation pin: optional `~s<n>` suffix on an @ref carrying the ref-frame epoch that issued it. Accepted as input everywhere; daemon tree payloads carry the epoch once at response level rather than per node, MCP may render or forward pinned refs, and durable replay scripts strip pins because epochs are session-specific.
57+
- Ref generation pin: optional `~s<n>` suffix on an @ref carrying the snapshot generation it was minted from. Accepted as input everywhere, emitted by no tree output (snapshot token budget), auto-appended by the MCP layer, stripped and ignored by replay.
6258
- Settled observation: opt-in (`--settle`) post-action payload on press/click/fill/longpress — the quiet-window stable loop re-captures until the UI settles, and the response carries the diff vs the pre-action tree (changed lines only, added lines with fresh refs, `refsGeneration` when the settled tree was stored). Best-effort: never fails the action; `settled: false` plus a hint on never-quiet content.
6359
- Snapshot capture plan: per-strategy ordered chain of iOS snapshot capture backends (recursive tree, query sweep, private AX) run by one plan runner under a shared wall-clock budget; recovery ordering is declared data, never a per-call-site branch.
6460
- Snapshot quality verdict: structured outcome (state, backend, reason code, effective depth, collapsed leaves) computed once by the plan runner and shipped with every planned snapshot payload; the daemon and CLI render it instead of re-deriving degradation from node shapes.

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -463,6 +463,12 @@ every `screen` ref with `refsGeneration` before returning it, including on the e
463463
client callers receive the unpinned refs and generation already present in the daemon error. No caller
464464
gets a text-only divergence that loses its repair data.
465465

466+
> **Proposed ADR 0014 amendment:** if ADR 0014 is accepted and implemented, replay divergence
467+
> `screen.refs` becomes a partial ref publication. MCP keeps auto-pinning those refs; CLI text renders
468+
> `@eN~s<refsGeneration>`; JSON and Node.js callers pair each plain ref with the response-level
469+
> generation before mutation. Until that migration lands, the current unpinned contract above remains
470+
> accepted. The implementation must update this note and its contract tests in the same change.
471+
466472
`--from N` is a `replay`-only flag. `test` must reject it as `INVALID_ARGS`; test shares replay execution
467473
but must remain a full, deterministic suite run. `N` is a 1-based index into the fully expanded
468474
executable plan and must be in range. It is never a YAML line number, fractional source-step number, or a

‎docs/adr/0014-session-ref-frame-lifetime.md‎

Lines changed: 62 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@ remain compatible with selector-based replay, and add no automatic capture or pe
3535

3636
## Decision
3737

38+
The terms introduced below describe the proposed target model. They do not replace the current domain
39+
language in `CONTEXT.md` while this ADR is Proposed and the source still implements the snapshot/stale
40+
marker model. The implementation change that establishes these concepts must promote the accepted
41+
terms into `CONTEXT.md`; documentation must not present the target model as current behavior early.
42+
3843
### Ref frames are separate from operational observations
3944

4045
A session owns at most one **ref frame**. The frame is the authorization namespace for mutation refs
@@ -77,11 +82,18 @@ compatibility.
7782
A complete activation normally accompanies a command result that exposes the complete ref namespace
7883
for the stored frame, including an interactive or intentionally scoped snapshot. An intentionally
7984
scoped snapshot replaces authorization with exactly its returned namespace; it neither authorizes
80-
matching ref bodies outside that scope nor retains the old `all` scope. A frame-activating capture
81-
scoped by `@ref` must first admit that scope ref against the current active frame. A stale or unissued
82-
scope ref fails closed; it cannot authorize a capture from a different subtree. Selector-scoped
83-
captures follow their normal selector rules. Empty, sparse, failed, or unusable captures do not
84-
replace the frame.
85+
matching ref bodies outside that scope nor retains the old `all` scope.
86+
87+
A frame-activating capture scoped by `@ref` must first admit that scope ref against the current active
88+
frame. To preserve the existing repeated scoped-snapshot contract after scoped output reindexes refs,
89+
the session retains one bounded **scope lineage** for consecutive read-only repetitions of that exact
90+
scope. The lineage stores the admitted semantic scope (label/selector chain), not the old positional
91+
tree or mutation authority. A repeated `snapshot -s @ref` may resolve through that lineage only when
92+
the immediately preceding frame publication was the same scoped capture. The first device-side effect,
93+
an unrelated frame publication, or another scope clears the lineage. An arbitrary stale or unissued
94+
scope ref still fails closed; it cannot borrow lineage or authorize a different subtree. Empty, sparse,
95+
failed, or unusable repeated captures preserve the last useful frame and its still-consecutive lineage.
96+
Selector-scoped captures follow their normal selector rules.
8597

8698
Snapshot diffs, digests that omit the namespace, `find`, settled diffs/tails, and replay divergence
8799
screens are partial external publications. They activate a partial frame only when at least one ref
@@ -154,7 +166,8 @@ awaiting that operation.
154166

155167
Failure before this seam preserves the frame. Once the seam is crossed, success, timeout,
156168
cancellation, connection loss, and ambiguous platform errors all leave it expired because the device
157-
may already have acted. There is no success-only rollback.
169+
may already have acted. Crossing the seam also clears scoped-snapshot lineage. There is no success-only
170+
rollback.
158171

159172
This rule applies to every execution shape:
160173

@@ -281,14 +294,23 @@ Read-only `find` may partially publish its returned ref. A mutating `find` retur
281294
as diagnostic pre-action identity: it must omit `refsGeneration`, must not publish or activate a
282295
frame, and cannot make that ref valid after the nested action.
283296

284-
The MCP executor continues storing per-ref pins by state-directory/session scope. Remembered pins are
285-
not cleared on mutation: sending the remembered old epoch is how the daemon produces a precise stale
286-
rejection. MCP currently neither traverses refs nested inside batch inputs nor learns refs from nested
287-
batch results; this remains an explicit non-goal.
297+
The MCP executor continues storing per-ref pins by state-directory/session scope. Issuance handling
298+
must distinguish the selected `find` action, not infer issuance from the command name alone. A
299+
read-only `find` with `refsGeneration` merges its partial pin. A mutating `find` without
300+
`refsGeneration` is explicitly non-issuing and leaves every remembered pin unchanged; it must not
301+
enter a generic missing-generation branch that clears the session's pin scope. The executor must carry
302+
enough normalized command/action context to make that distinction. Remembered pins are not cleared on
303+
mutation: sending the remembered old epoch is how the daemon produces a precise stale rejection. MCP
304+
currently neither traverses refs nested inside batch inputs nor learns refs from nested batch results;
305+
this remains an explicit non-goal.
288306

289307
The response-level `refsGeneration` field remains the token-economical authority. Snapshot nodes never
290-
gain per-node generation bytes. Human CLI output may render a ready-to-copy pinned form for the one or
291-
few refs in a partial result, but complete trees remain plain.
308+
gain per-node generation bytes. Every reusable ref in a partial CLI text result must render in
309+
ready-to-copy `@eN~s<refsGeneration>` form. JSON and Node.js responses retain plain ref bodies plus one
310+
response-level generation; callers must pair them before a mutation. MCP may render a plain ref because
311+
it stores and forwards the pin internally. Complete snapshot trees remain plain to protect the token
312+
budget. A mutating `find` diagnostic ref is never rendered or stored as pinned because it carries no
313+
`refsGeneration`.
292314

293315
## Performance and compatibility
294316

@@ -343,6 +365,8 @@ It composes with existing ADRs as follows:
343365
ambiguous dispatch.
344366
- A read without retained evidence fails rather than resolving the same positional ref body in a
345367
newer tree. Reads with retained evidence keep the structured warning behavior.
368+
- Consecutive repeated scoped snapshots retain their admitted semantic scope, while any mutation,
369+
unrelated publication, or different scope breaks that lineage.
346370
- The implementation pays bounded session-memory bookkeeping but adds no automatic capture, platform
347371
call, round trip, or per-node response bytes.
348372

@@ -357,31 +381,45 @@ The implementation is not complete until contract and provider tests prove:
357381
provider-backed lifecycle/generic paths cross the same seam;
358382
5. Android freshness cannot retarget an admitted ref through positional coincidence;
359383
6. read-only operational captures do not replace the authorized frame;
360-
7. partial publication admits only emitted pinned refs, reports each typed admission failure, and
361-
cannot bless unrelated plain refs;
384+
7. partial publication admits only emitted pinned refs, reports each typed admission failure, cannot
385+
bless unrelated plain refs, and CLI text renders every reusable partial ref with its pin while JSON
386+
and Node.js retain the response-level representation;
362387
8. complete publication admits its plain namespace while sparse/unusable captures do not;
363388
9. mutating `find` omits `refsGeneration` and never pins or activates its pre-action ref as current
364-
post-action state;
389+
post-action state; an MCP sequence that first remembers a snapshot pin, then performs mutating
390+
`find`, still forwards the remembered old pin on a later ref input so the daemon rejects it as stale;
365391
10. batch and replay delegate per step, retain their existing failure/partial-result contracts, and
366392
allow `snapshot -> @ref` with an intermediate digest without exposing pins or dynamic bindings;
367393
11. recorded scripts contain selectors rather than portable generation claims;
368394
12. press/swipe series and Apple chunks resolve and expire exactly once;
369395
13. Android dialog recovery expires before its first recovery side effect and aborts an outstanding
370396
ref action after recovery mutates;
371-
14. `@ref`-scoped activation rejects stale scope refs, while empty partial output leaves the current
372-
frame unchanged;
397+
14. consecutive repeated `snapshot -s @ref` calls resolve the same admitted semantic scope after
398+
scoped output reindexes refs; a mutation, unrelated publication, or different scope breaks the
399+
lineage; an arbitrary stale ref cannot use it; and empty/unusable repetition preserves the last
400+
useful frame and still-consecutive lineage;
373401
15. fused keyboard/alert requests and split status/action paths follow their documented conservative
374402
seams, including already-hidden and no-alert outcomes;
375403
16. failed or timed-out existing-session open/relaunch leaves the old frame expired after dispatch;
376-
17. a large-tree fixture proves frame/observation separation introduces no deep copy and records the
404+
17. a read-only ref with retained stale evidence returns the structured warning, while missing frame
405+
evidence fails without falling through to a newer observation by positional coincidence;
406+
18. a large-tree fixture proves frame/observation separation introduces no deep copy and records the
377407
bounded peak retained nodes/bytes; and
378-
18. enforcement and error shapes are consistent across supported platforms.
408+
19. enforcement and error shapes are consistent across supported platforms.
379409

380410
Performance regression tests prove that admission, expiration, and frame/observation separation add
381411
no implicit capture or provider/platform call. Device benchmarks are required only if those tests or
382412
live evidence reveal a regression. No path may claim success until a test proves the relevant
383413
direct/native/runtime/provider branch actually executed.
384414

415+
Before enforcement is enabled for a platform, fresh-build live evidence must exercise every supported
416+
production seam affected there: Apple runtime-ref and direct/native paths where available, Android
417+
helper freshness and recovery, generic/lifecycle mutation, and at least one real provider-backed
418+
interaction plus lifecycle operation. Each run must prove a fresh ref succeeds, a second mutation with
419+
the stale ref is rejected before dispatch, and a fresh observation restores usability. A seam not
420+
exercised remains disabled or is recorded as an explicit release blocker. Fixture-backed tests and
421+
registry claims are necessary but do not substitute for this live evidence.
422+
385423
## Migration
386424

387425
Each step lands green and independently useful:
@@ -391,13 +429,15 @@ Each step lands green and independently useful:
391429
2. add the complete daemon descriptor classification and gate, including request-sensitive resolvers;
392430
3. route every leaf side effect, fallback, retry, and readiness recovery through the idempotent
393431
pre-side-effect transition;
394-
4. correct complete/partial publication and MCP/CLI rendering while preserving response-level epochs;
432+
4. correct complete/partial publication, bounded scoped-snapshot lineage, MCP pin retention, pinned
433+
partial CLI text, and JSON/Node.js response-level generation handling;
395434
5. decouple Android freshness capture from positional ref authorization;
396435
6. add sequence, batch, replay, series, failure-boundary, and cross-platform provider contracts;
397436
7. enable fail-closed mutation enforcement per platform only after its paths have evidence, ending in
398437
one uniform policy; and
399-
8. update help, changelog, and replay/batch guidance for refresh-between-mutations, conservative
400-
fused no-op invalidation, and reads without retained evidence; then remove the superseded coarse
438+
8. update help, changelog, ADR 0012's proposed-amendment note and tests, and replay/batch guidance for
439+
refresh-between-mutations, conservative fused no-op invalidation, and reads without retained
440+
evidence; promote the implemented vocabulary into `CONTEXT.md`; then remove the superseded coarse
401441
stale marker.
402442

403443
PR #1241 landed independently as a compatible transitional fix. It rejects a known iOS stale-marker

0 commit comments

Comments
 (0)