t3-code-android-nightly/docs/internals/performance-regressions.md

Performance regression checks

The v2 transport has a focused regression command:

vp run test:perf:v2-wire

It exercises the real v2 projection and client reducers. This matters because the older built-app benchmark fixtures seed v1 orchestration events; running those fixtures against a v2 client can produce reassuring timings while missing the active transport path.

The v2 checks pin these invariants:

• Client cold opens target 75 recent timeline rows and about 1 MiB of encoded data. Required control records and the at-least-one-row rule can exceed the byte target; it is not a hard cap.
• The bounded snapshot does not retain the full duplicate conversation-message table.
• Older activity is fetched in bounded HTTP pages and merged without disturbing the live scroll window.
• Clients with confirmed history paging opt into socket snapshot fallbacks that use the same bounded recent-history window and carry the cursor needed to fetch older history. Older clients and WebSocket-only starts retain the compatible full-snapshot fallback.
• Snapshot queries bound timeline reads per fork ancestor, not total rows: dependency and control records still accompany the window. Smaller socket frames alone do not establish a whole-server memory reduction.
• Resume catch-up checks the original 1 MiB persisted-payload budget before decoding, then replays at most 128 thread events and 1 MiB of projected event JSON before falling back to a snapshot. Raw JSON bytes are not a heap-memory cap. Raising this budget merely because output projects small can increase server allocations on repeated large tool updates.
• Raw command output, dynamic-tool result bodies, and inline file-change bodies are omitted at the wire boundary, including small outputs. Explicit failure flags and bounded result IDs preserve status and grouped action counts without shipping those bodies. Persisted events remain complete; the existing diff endpoints still provide file content when requested.
• The initial shell contains active navigation rows only. Archived rows use the dedicated archive query, and transcript message bodies stay in thread detail regardless of message size.
• Shell resume sends deltas plus compact repository-enrichment metadata, not another full project and thread snapshot.
• Auto, steer, and restart sends resolve delivery from authoritative state inside the server's per-thread dispatch lock. Model selection and identified-checkpoint rollback also dispatch without first fetching a full thread projection when the server advertises support. Older servers retain projection-based validation. Explicit start sends already skipped that read, so this saving does not apply to every client send path.

When changing projection schemas, paging, shell synchronization, or thread state, run this command alongside the focused package typechecks and a real-client pass on every affected surface. The transport performance fixtures validate contract encoding and compare pre-compression RPC JSON for the same synthetic workload, preserving historical application-object counts separately. These are neither compressed WebSocket captures nor measurements of server RSS, and command fixtures exclude unrelated settings calls and subscription events. Payload budgets belong in these tests so regressions fail locally.

Event store and startup

Sequence cursors must seek an index rather than scan retained history. The application sequence index contains project events and v2 thread events; the per-thread sequence index contains only v2 thread events. Legacy-only and unknown threads must return zero without scanning other threads. Catch-up queries keep sequence ranges and optional thread or command predicates indexable.

Startup selects recovery candidates from current projection state before reading full thread projections. Candidate selection includes queued runs, pending runtime requests, live provider sessions, background work, and unfinished delegated deliveries. Archived threads still participate where recovery requires them. Completed thread history is not loaded merely to discover that no work remains.

Projection verification decodes canonical rows in bounded pages, including shared provider records and fork ancestry. Rebuild replays event pages through a fixed sequence within its transaction; it must not collect the entire event log before projecting it.

The focused regression coverage lives in OrchestrationEventStore.sequence.test.ts, ProjectionRecovery.test.ts, and the provider runtime recovery tests under apps/server/src.

Background work and navigation

The settlement worker reads active, unpinned threads without explicit settlement overrides from ProjectionStore.getSettlementCandidates. It reads the latest run and user-message timestamps, rejects active runs and pending requests, and checks background work using the same derivation as the shell. It does not load archived histories, fork ancestry, transcript counts, or provider sessions. The orchestrator still validates the current thread before applying settlement.

Read receipts use ProjectionStore.getThread to load only canonical thread metadata. A visit advances lastVisitedAt monotonically without changing updatedAt or decoding history. Shell queries use a covering thread/run index for item counts and a partial index for nonterminal background items, including idle items. Latest user-message reads use an index ordered by update time.

Command palette results keep live VCS and linked pull-request queries leased to the visible viewport, including a small overscan region. Cached badges remain available while leases are released. Local Git status reads skip divergence calculations; callers that need ahead/behind counts keep the full status path. Cached fetch failures share the existing backoff and log only the actual failed attempt. Unchanged desktop environment bootstrap reads retain their array identity so polling does not invalidate subscribers.

Relay awareness queues one pending publication per thread and retains a follow-up when the thread changes during a send. Transcript deltas and tool output do not enqueue awareness work. Run, request, and relevant thread metadata events do. Configuration is checked before shell reads, and connection changes invalidate published identities so relinking can publish unchanged state. Failed publications retry the latest state up to five times with exponential delays. A new relevant event resets the budget; successful publication, disabling, or unlinking cancels retries. After the budget is exhausted, publication waits for another relevant event instead of generating continuous traffic during an outage.

Focused coverage: ProjectionSettlement.test.ts, ThreadSettlementService.test.ts, runtimeLayer.test.ts, AgentAwarenessRelay.test.ts, GitVcsDriverCore.test.ts, ThreadStatusIndicators.subscriptions.test.tsx, and desktopLocal.test.ts.