|
2 | 2 |
|
3 | 3 | ## Status |
4 | 4 |
|
5 | | -Accepted |
| 5 | +Accepted; implemented and enforced on `main` across all platforms. Fresh live evidence exercised |
| 6 | +every production seam except Android blocking-dialog recovery, which shipped as a documented, |
| 7 | +accepted gap: no deterministic repro exists to raise the system dialog on demand, and the seam's |
| 8 | +transition and abort logic are pinned by fixture regressions |
| 9 | +(`android-system-dialog-ref-frame.test.ts`, `interaction-android-recovery-abort.test.ts`). The |
| 10 | +staged migration plan lives in this file's git history; PR #1241 was an earlier compatible |
| 11 | +transitional fix, not this architecture migration. |
| 12 | + |
| 13 | +## Rules at a glance |
| 14 | + |
| 15 | +Normative summary; the binding contracts and edge cases are in [Decision](#decision), and the |
| 16 | +ref-frame vocabulary is promoted into `CONTEXT.md`. |
| 17 | + |
| 18 | +- A session owns at most one **ref frame** — the authorization namespace for mutation refs (epoch |
| 19 | + exposed as `refsGeneration`, immutable source tree, `active`/`expired` state, `all` or bounded |
| 20 | + issuance scope) — owned by `src/daemon/ref-frame.ts` and kept separate from the latest |
| 21 | + operational observation (`session.snapshot`). |
| 22 | +- A complete snapshot activates an `all` frame; `find`, settled diffs, and replay divergence |
| 23 | + screens activate a bounded partial frame that supersedes the prior one; internal read-only |
| 24 | + captures never activate, reindex, or expire a frame. |
| 25 | +- Every mutating leaf expires the frame at the side-effect seam — after all pre-action guards, |
| 26 | + immediately before the device op — with no success-only rollback; a post-dispatch failure still |
| 27 | + leaves it expired. |
| 28 | +- Mutation admission requires an active frame whose epoch and issuance scope authorize the ref; |
| 29 | + rejections carry ordered typed reasons `ref_frame_expired` -> `ref_generation_mismatch` -> |
| 30 | + `plain_ref_requires_complete_frame` -> `ref_not_issued`. |
| 31 | +- Read-only ref consumers stay fail-open with a structured staleness warning only while the frame |
| 32 | + retains the ref's evidence; missing evidence fails rather than resolving by positional |
| 33 | + coincidence against a newer observation. |
| 34 | +- Every daemon command declares a `RefFrameEffect` (`preserve` | `may-invalidate` | `delegated`) in |
| 35 | + its descriptor daemon facet; the registry classification is completeness-gated. |
6 | 36 |
|
7 | 37 | ## Context |
8 | 38 |
|
@@ -36,7 +66,7 @@ remain compatible with selector-based replay, and add no automatic capture or pe |
36 | 66 | ## Decision |
37 | 67 |
|
38 | 68 | The terms introduced below are now the implemented model; the ref-frame vocabulary is promoted into |
39 | | -`CONTEXT.md`. The superseded coarse `snapshotRefsStale` marker has been removed (migration step 8): |
| 69 | +`CONTEXT.md`. The superseded coarse `snapshotRefsStale` marker has been removed: |
40 | 70 | read-only ref staleness is now derived from frame state — a plain ref warns once the frame has expired, |
41 | 71 | and a read-only capture no longer marks refs stale because it does not expire the frame. |
42 | 72 |
|
@@ -64,7 +94,7 @@ the evidence tree, bounds partial authority. The frame and latest observation sh |
64 | 94 | data when they originate from the same capture; neither transition deep-copies the tree. |
65 | 95 |
|
66 | 96 | The existing `snapshotGeneration` implementation evolves behind one ref-frame module; the |
67 | | -`snapshotRefsStale` marker it originally paired with has since been removed (migration step 8). The |
| 97 | +`snapshotRefsStale` marker it originally paired with has since been removed. The |
68 | 98 | public name `refsGeneration` and the `@e12~s42` grammar remain unchanged for wire compatibility. |
69 | 99 |
|
70 | 100 | ### Frame transitions |
@@ -418,50 +448,6 @@ the stale ref is rejected before dispatch, and a fresh observation restores usab |
418 | 448 | exercised remains disabled or is recorded as an explicit release blocker. Fixture-backed tests and |
419 | 449 | registry claims are necessary but do not substitute for this live evidence. |
420 | 450 |
|
421 | | -## Migration |
422 | | - |
423 | | -Each step lands green and independently useful: |
424 | | - |
425 | | -1. introduce the bounded ref-frame module and separate operational observations without changing |
426 | | - enforcement; |
427 | | -2. add the complete daemon descriptor classification and gate, including request-sensitive resolvers; |
428 | | -3. route every leaf side effect, fallback, retry, and readiness recovery through the idempotent |
429 | | - pre-side-effect transition; |
430 | | -4. correct complete/partial publication, bounded scoped-snapshot lineage, MCP pin retention, pinned |
431 | | - partial CLI text, and JSON/Node.js response-level generation handling; |
432 | | -5. decouple Android freshness capture from positional ref authorization; |
433 | | -6. add sequence, batch, replay, series, failure-boundary, and cross-platform provider contracts; |
434 | | -7. enable fail-closed mutation enforcement per platform only after its paths have evidence, ending in |
435 | | - one uniform policy; and |
436 | | -8. update help, changelog, ADR 0012's proposed-amendment note and tests, and replay/batch guidance for |
437 | | - refresh-between-mutations, conservative fused no-op invalidation, and reads without retained |
438 | | - evidence; promote the implemented vocabulary into `CONTEXT.md`; then remove the superseded coarse |
439 | | - stale marker. |
440 | | - |
441 | | -Implementation status: all migration steps have landed — the ref-frame module and observation split |
442 | | -(1), the complete daemon classification and gate (2), the pre-side-effect seam at every leaf (3), |
443 | | -correct complete/partial publication with bounded scope, MCP pin retention, and pinned partial CLI text |
444 | | -(4), Android freshness decoupled from positional ref authorization (5), the cross-platform contract and |
445 | | -provider evidence (6), fail-closed admission enforcement across platforms with typed reasons (7), and |
446 | | -the docs/vocabulary promotion plus removal of the superseded coarse `snapshotRefsStale` marker (8). |
447 | | -Fresh live evidence has exercised nearly every production seam — Apple runtime-ref, direct/native |
448 | | -selector, generation-pin, generic, and lifecycle paths; Android helper freshness (including proven |
449 | | -non-retarget) and Android existing-session relaunch; and a real provider-backed interaction plus |
450 | | -provider-backed lifecycle operation (AWS Device Farm, `backend: webdriver`: a fresh ref succeeded, an |
451 | | -immediate stale ref was rejected before dispatch with the shared typed fields, an `open --relaunch` |
452 | | -lifecycle mutation expired the frame, and a fresh observation restored authorization). ONE seam — |
453 | | -Android blocking-dialog recovery — was NOT live-exercised: the repo harness exposes no deterministic |
454 | | -app-owned ANR trigger, and no reproducible control exists to raise the system dialog on demand. The |
455 | | -team accepted shipping without a live run for it: its transition and abort logic are covered by fixture |
456 | | -regressions (`android-system-dialog-ref-frame.test.ts` proves recovery expires the frame before its |
457 | | -tap; `interaction-android-recovery-abort.test.ts` proves an outstanding ref action then aborts with the |
458 | | -shared `ref_frame_expired` rejection and no dispatch), the seam is enforced in code identically to the |
459 | | -verified paths, and it is recorded here as a documented, accepted evidence gap rather than an open |
460 | | -release blocker. Every other enabled seam is proven on hardware. |
461 | | - |
462 | | -PR #1241 landed independently as a compatible transitional fix. It rejects a known iOS stale-marker |
463 | | -case before this full lifecycle is implemented; it does not own the architecture migration. |
464 | | - |
465 | 451 | ## Alternatives considered |
466 | 452 |
|
467 | 453 | - **Stable refs across trees:** rejected because positional accessibility snapshots have no durable |
|
0 commit comments