docs: define session ref-frame lifetime

[thymikee]

Summary

Define ADR 0014 for a consistent cross-platform ref-frame lifetime following #1239.

The design separates mutation authorization from operational observations, expires ref authority at the first possible device side effect, defines complete and partial issuance, and covers batch/replay, .ad, MCP, repeated actions, provider paths, Android recovery, failure boundaries, and performance constraints. It documents merged #1241 as an independently landed transitional iOS fix.

Validation

• git diff --check origin/main...HEAD
• Docs-only change; runtime tests not required

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.7 MB	1.7 MB	0 B
JS gzip	542.6 kB	542.6 kB	0 B
npm tarball	652.9 kB	652.9 kB	0 B
npm unpacked	2.3 MB	2.3 MB	0 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	25.6 ms	26.3 ms	+0.7 ms
CLI --help	53.4 ms	56.7 ms	+3.3 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

Addressed the attached ADR review in fee141592 after rebasing onto current main:

1. Generic routing / app-switcher: corrected the architecture claim. app-switcher does reach the generic daemon fallback alongside back, home, rotate, scroll, and tv-remote; its actual inconsistency is the missing explicit daemon descriptor facet. The ADR now keeps the shared generic leaf, requires every generic mutator to cross the same transition, and makes the completeness gate cover daemon-projected commands so fallback cannot hide an unclassified mutation.
2. Conservative fused no-ops: compatibility now explicitly says that a dispatched fused request may expire refs even when the eventual result is already hidden or no alert. Migration guidance must document this.
3. Read compatibility: documented that a read without retained frame evidence newly fails instead of warning and resolving the same positional body against a newer observation.
4. Consequences: added a focused section stating what becomes safer, which multi-mutation and legacy .ad workflows must change, the conservative no-op trade-off, read behavior, and bounded performance cost.
5. Nits/readability: clarified that generation pins improve rejection precision rather than concurrency isolation, corrected tv-remote, simplified the subtree/guard wording, and updated fix: reject stale iOS refs after navigation #1241 from a pending transitional PR to an independently landed fix.

Validation: git diff --check origin/main...HEAD. Docs-only change; runtime tests are not required. ADR status remains Proposed pending implementation.

[thymikee]

Independent re-review of rebased head fee1415 found remaining ADR blockers:

1. CONTEXT.md presents ref frames, epochs, activation, and issuance as current repo vocabulary while ADR 0014 is Proposed and source still uses session.snapshot, snapshotGeneration, and snapshotRefsStale. Mark these terms proposed/unimplemented or keep CONTEXT aligned with current behavior.
2. ADR 0014 makes replay-divergence refs partial and pin-required, but accepted ADR 0012 still defines screen.refs as directly actionable and CLI/direct clients receive plain refs. Update ADR 0012 or define a compatibility path.
3. Replacing authorization on an @ref-scoped snapshot breaks the current repeated scoped-snapshot contract backed by snapshotScopeSource. Record this as an intentional breaking change and add migration/evidence, or preserve the contract.
4. The MCP migration needs an explicit mutating-find requirement: current MCP treats find as ref-issuing and clears pins when refsGeneration is absent. Prove mutating find leaves prior pins intact.
5. Make partial-ref text behavior normative, and add required evidence for read-only missing-frame failure plus practical device evidence for the affected direct/native/provider/platform seams.

Docs-only validation is otherwise sufficient, but the ADR should not merge with these contract ambiguities unresolved. No fixer was dispatched.

[thymikee]

Addressed the five remaining blockers in commit 5134f53:

1. Current vs proposed vocabulary: restored CONTEXT.md to the current snapshot-generation terminology. ADR 0014 now explicitly keeps ref-frame terms local while Proposed and requires the implementation migration to promote them only when they become real.
2. ADR 0012 compatibility: added a clearly labeled proposed ADR 0014 amendment. The accepted plain screen.refs contract remains current; the eventual implementation must update ADR 0012 and its tests atomically when divergence refs become partial/pin-required.
3. Repeated scoped snapshots: preserved the existing contract with one bounded semantic scope lineage. Consecutive repetitions of the same admitted scoped snapshot survive scoped ref reindexing; mutation, unrelated publication, or another scope clears lineage. It carries no positional mutation authority. Evidence now covers repeat success, mutation/unrelated-scope breakage, arbitrary stale rejection, and empty/unusable preservation.
4. Mutating find in MCP: made action-aware issuance normative. Read-only find merges its pin; mutating find is non-issuing and must leave every prior pin intact rather than taking the generic missing-generation clear path. Required evidence spells out snapshot pin, then mutating find, then later old ref forwarded and rejected stale.
5. Partial refs and verification: CLI text MUST render reusable partial refs with their generation pin; JSON/Node keep plain refs plus response-level generation; MCP may keep plain display because it forwards pins internally. Added missing-frame read-failure evidence and fresh-build live requirements for Apple runtime/direct/native, Android helper freshness/recovery, generic/lifecycle, and real provider-backed seams.

Validation: git diff --check origin/main...HEAD. Docs-only; no runtime tests required by repository policy.

[thymikee]

Current-head re-review at 5134f53 is clean. The five ADR blockers are resolved: proposed vocabulary is scoped correctly, ADR 0012 compatibility remains current until atomic migration, scoped-snapshot lineage is bounded, mutating-find MCP pins are preserved explicitly, and partial-ref rendering plus live implementation evidence are normative. Independent GPT-5.5 review found no additional issues. Docs-only checks are green. Ready for maintainer judgment; implementation PRs must still satisfy the seam-specific contract and live-device evidence required by the ADR.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-13 17:29 UTC