docs(adr-0018): revise state-sync implementation gate — RenderState is the cache primitive#1
Merged
Conversation
…s the cache primitive The original ADR-0018 Decision section framed implementation as gated on a missing libghostty primitive (Terminal::snapshot_grid + diff_into). Re-reading upstream's C headers (include/ghostty/vt/render.h) and the in-tree usage shows that framing is too pessimistic on the cache half. GhosttyRenderState / libghostty_vt::RenderState IS the per-consumer cache primitive Mosh's framework needs: N instances per Terminal is the supported pattern, dirty bits are caller-managed (set_dirty(Clean) is explicit), and phux already holds one per renderer in SnapshotSynthesizer (server) and PaneRenderer (client). The state-sync server work is lifecycle (one RenderState per attached consumer instead of one per Terminal) + incremental synthesis (extend SnapshotSynthesizer to skip the reset and consult dirty rows) + tick scheduler + ack-driven dirty reset. The synthesis half remains phux's work — no upstream gate. Estimate revised from ~500-1000 LOC to ~200-400 LOC of new code, most of it shared with the existing synthesizer. Upstream COW-backed snapshots remain a wanted federation-scale optimization, but not a v0.2 blocker. This commit: - ADR-0018: status line notes the revision; appends an Addendum section enumerating what's actually load-bearing (Snapshot::dirty() reliability per phux-l0t; per-consumer RenderState in TerminalActor per phux-28f; the incremental synthesizer; tick + ack handler). No change to Decision, Rationale, Tradeoffs, or Alternatives. - research/2026-05-26-state-sync-algorithm.md: replaces the Dependencies section with the revised picture and adds a revision history footer. Original framing remains in git history. Companion bd state (phux-q0e epic + sub-tickets, mosh-decomposition memory update, renderstate-as-cache memory) was committed on feat/l1-cascade-wave-a (commit 64d0d95, mixed-scope chore commit) and will arrive on main when that branch merges. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Terminal::snapshot_grid+diff_into). Re-readinginclude/ghostty/vt/render.hand the in-tree usage showsGhosttyRenderStatealready fills the per-consumer cache role: N instances per Terminal is the supported pattern, dirty bits are caller-managed, and phux already holds one per renderer inSnapshotSynthesizer(server) andPaneRenderer(client).Snapshot::dirty()reliability on subsequent updates (phux-l0t), per-consumer RenderState in TerminalActor (phux-28f), the incremental synthesizer extension, and the tick + ack handler. No change to Decision, Rationale, Tradeoffs, or Alternatives.research/2026-05-26-state-sync-algorithm.mdDependencies section with the corrected picture; adds a revision-history footer pointing at git for the original framing.The synthesis half remains phux's work — no upstream gate. Estimate revised from ~500–1000 LOC to ~200–400 LOC of new code, most of it shared with the existing synthesizer. Upstream COW-backed snapshots remain a wanted federation-scale optimization but not a v0.2 blocker.
Companion bd state
The new state-sync epic (phux-q0e) and sub-tickets (phux-q0e.1–q0e.5), the phux-l0t re-prioritization (P3 → P2), the updated
mosh-decompositionmemory, and the newrenderstate-as-cachememory landed onfeat/l1-cascade-wave-a(commit64d0d95, a mixed-scope chore commit from a bd auto-commit hook) and will arrive on main when that branch merges. This PR's prose references those tickets by ID; readers checking out main before the L1 branch merges will see ID references that don't resolve in bd yet.Test plan
🤖 Generated with Claude Code