Fold streaming text deltas at the chat replay boundary

[arul28]

Item 3 of Tier 1C. Stacked on #1057 — review/merge that first.

The finding

A 30-second reply is persisted as hundreds of individual text delta rows, and replay re-sends every one for the client to re-fold. Measured on a real 87.85 MiB thread from this machine:

68,081 text events averaged 798 bytes each while carrying 10.1 bytes of text — a 1.27% payload. One measured event spent 833 bytes to deliver the word " and".

The other 98.7% is the identifier stack, re-sent per delta: a ~130-char composite messageId, a ~160-char provenance.messageId repeating it plus a UUID, then threadId/turnId/itemId/sessionId/timestamp/sequence.

The change

Full chat_subscribe snapshots collapse consecutive streaming deltas of the same message into one event. Gated on a new foldedReplay hello capability; a client that does not declare it receives every individual delta, unchanged.

Measurements — read the boundary, not the transcript

A chat_subscribe snapshot is bounded before the fold ever runs: CHAT_EVENT_REPLAY_MAX_EVENTS = 500 and maxBytes (220 KB default, 2 MB ceiling). No snapshot carries the whole transcript, so the effect per hydration is what matters, and it varies with how much of the window is streaming text:

220 KB window sampled at	before	after	smaller
25% through the thread	249 events / 213.9 KB	35 events / 44.3 KB	79.3%
75%	279 events / 214.8 KB	105 events / 87.4 KB	59.3%
tail	202 events / 214.5 KB	112 events / 187.4 KB	12.6%
50%	232 events / 214.5 KB	190 events / 201.9 KB	5.9%

So: 5.9%–79.3% per hydration, with event count down 18–86%. A window landing inside a long streamed reply is where the fold pays; a window of mixed tool/command traffic is where it barely does.

For reference, folding the entire 87.85 MiB transcript gives 91,090 → 31,703 events and 42.72 MiB (51.4%) in 30 ms — but that is the fold's effect on history, not on any single hydration, and no code path sends it. An earlier revision of this PR led with that number; it was correct arithmetic against the wrong boundary.

The event-count reduction is worth as much as the bytes here: every snapshot event is decoded on iOS, and #1056 moved that decode off the main actor precisely because it was expensive.

Why the scope is this narrow

The two clients do not fold text the same way, in two independent respects, and the fold obeys both.

Merge semantics. Desktop concatenates text deltas unconditionally (inline in the row reducer). iOS's mergeWorkStreamingText (WorkErrorAndMessageHelpers.swift:310) is ~50 lines of replay-shape detection, trimmed prefix/suffix checks, and an overlap scan. For deltas that overlap or repeat those two already render differently today, so only clean appends fold — neither side a prefix of the other, not equal, no boundary overlap. For text this is stricter than desktop needs; it simply folds less.

Adjacency. Desktop merges into rows[rows.length - 1] and only when that row is a text row, so a tool call between two deltas ends the row. iOS finds its target by searching for the item id and merges across gaps. Folding is therefore adjacency-only — any intervening event closes the run. Folding across it would move the tool call after the whole message.

Note for anyone extending this: mergeStreamingText (chatTranscriptRows.ts:634) is not the text merge — its only call sites are :959 (diffs) and :984 (command output). It does have a cumulative startsWith branch, which is live on those types, so extending the fold to file_change or command must handle a growing-diff-per-event runtime. Every fixture here is text-shaped and would not catch it.

Other types stay unfolded for the same reason, not for lack of value:

• command merges its output and file_change merges its diff through the streaming merge (chatTranscriptRows.ts:959,984) — append-merges, so keep-last would drop output.
• plan is a field-wise merge with fallbacks (mergePlanTranscriptEvent, :488): an event with empty steps preserves the previous steps, so keep-last loses them.

Each is foldable under its own provable-agreement predicate — follow-up work, not a guess to make here. An unrecognized event type is never folded.

Sequence and cursor safety

The documented failure class here is host eventSequence restarting per rehydration, producing sessionId:sequence collisions that silently dropped iOS AskUserQuestion cards. Three rules keep the fold clear of it:

1. A folded run is emitted at the position of its first delta (where both clients place the message) and carries the last delta's sequence/timestamp, so no consumer can watermark inside a collapsed run.
2. Delivery bookkeeping marks the pre-fold envelopes. A collapsed delta still has its own delivery key; leaving it unmarked lets the transcript pump re-send it as an event the client would render twice.
3. The replay-buffer resume path is not folded. Its per-event seq monotonicity is load-bearing for the client's seq <= lastSeq drop rule, and it carries only a small recent gap.

Cursors are untouched: tailStartOffset, cursorKind and hasOlderHistory are computed before the fold and still address the same byte offsets. Contract sent to the t3-thread-reading lane, which owns page-cut placement.

Forward compatibility verified: syncHelloProtocol.ts:121 filters capabilities to non-empty strings with no allowlist, so an older host receiving foldedReplay ignores it rather than rejecting the connection.

Tests

24 tests in chatReplayFold.test.ts:

• Fold equivalence per type — folded text equals what a client derives from the unfolded run, with the desktop merge reproduced verbatim; every folded pair is asserted to satisfy both it and iOS's pre-overlap guards.
• Explicit non-folding — plan, command, file_change, tool_call, tool_result, context_usage, and an unknown future type pass through untouched.
• Named sequence regression — two host epochs both numbering from 1 replayed into one snapshot: distinct messages stay distinct, no two emitted events share a delivery key, a folded run's sequence is >= every sequence it absorbed.
• Ordering, interleaved messages, turn/message separation, deltas with no stable id, replay-shaped deltas ending a run.
• Malformed envelopes — real transcripts contain lines with no event at all. This crashed the first implementation; caught by running the real transcript through the module, not by the synthetic tests.

567 sync tests pass.

Follow-up (not built here)

1. The fold shrinks the payload but does not deliver more history. The window is read byte-bounded before folding, so a phone gets the same conversation in fewer bytes rather than more conversation in the same bytes. Reading a larger window and folding down to the budget is the bigger prize — deliberately not done here because it moves what tailStartOffset points at, which the t3-thread-reading lane owns.
2. A wire-side id dictionary would attack the 98.7% directly, and applies to live traffic too, not just replay.

🤖 Generated with Claude Code

Greptile Summary

The PR capability-gates replay folding so compatible clients receive adjacent clean-append text and reasoning deltas as single snapshot events while legacy clients retain unchanged behavior.

• Adds conservative replay-folding logic and equivalence, ordering, seam, malformed-envelope, and sequence-regression tests.
• Advertises foldedReplay from iOS and defines the shared sync capability.
• Integrates folding only into full chat_subscribe snapshots while preserving pre-fold delivery bookkeeping and leaving replay-buffer resumes unfolded.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains in the reviewed follow-up scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
apps/desktop/src/shared/chatReplayFold.ts	Introduces a conservative adjacency-only fold that preserves client merge semantics, event ordering, and source delivery identities.
apps/ade-cli/src/services/sync/syncHostService.ts	Capability-gates folding on full snapshots and marks every pre-fold envelope to prevent transcript-pump duplicates.
apps/desktop/src/shared/chatReplayFold.test.ts	Covers fold equivalence, unsupported types, sequence behavior, malformed envelopes, cumulative streams, and page-seam composition.
apps/desktop/src/shared/types/sync.ts	Adds the additive foldedReplay capability constant without changing existing wire shapes.
apps/ios/ADE/Services/SyncService.swift	Advertises foldedReplay support while retaining compatibility with hosts that ignore unknown capabilities.
apps/ade-cli/src/services/sync/syncHostService.test.ts	Verifies host wiring sends folded snapshots only to capable peers and leaves legacy snapshots unchanged.

Sequence Diagram

sequenceDiagram
  participant Client
  participant Host as Sync host
  participant History as Transcript history
  Client->>Host: hello(capabilities)
  Client->>Host: chat_subscribe
  Host->>History: Read bounded snapshot
  History-->>Host: Events and byte cursor
  alt Client declares foldedReplay
    Host->>Host: Fold adjacent clean text/reasoning appends
    Host-->>Client: Folded chat_subscribe snapshot
    Host->>Host: Mark every original source event delivered
  else Legacy client
    Host-->>Client: Unchanged event-by-event snapshot
  end
  Note over Host,Client: Replay-buffer resume remains unfolded

Loading

_{Reviews (10): Last reviewed commit: "Pin that a folded snapshot half composes..." | Re-trigger Greptile}

Context used:

• Knowledge Base — ade-cli: CLI, RPC daemon, and ade code TUI
• Knowledge Base — Desktop Renderer UI

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
ade	Ignored	Preview	Aug 10, 2026 5:06am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: dfab5220-dc63-4451-856d-3c5effca1a2b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[arul28]

Superseded by #1065. GitHub closed this irrecoverably when its stacked parent (#1057) was merged and its base branch deleted — the base could not be retargeted on a closed PR. #1065 is the same branch and commits, rebased onto main.