---
id: AGD-0051
ticket: pbs-lsp-performance-cache-and-snapshots
title: PBS LSP Performance Cache and Snapshots
status: open
created: 2026-07-15
resolved:
decision:
tags: [studio, lsp, vscode, compiler-pbs, editor, performance, caching]
---

## Pain

Domain owner: `studio/lsp`

Several PBS LSP requests rebuild or reanalyze substantial project state, which can become slow or jittery as projects grow and as richer features are added.

## Context

The current bridge favors correctness and simplicity by invoking compiler pipeline analysis for diagnostics and editorial documents. A complete LSP needs snapshot caching, invalidation, cancellation, and predictable latency.

## Open Questions

- [ ] What is the canonical project/document snapshot boundary for LSP requests?
- [ ] Which requests can reuse semantic read surfaces safely across document changes?
- [ ] How should cancellation, stale responses, and background reanalysis be handled?

## Options

### Option A - Request-local analysis

- **Approach:** Keep each LSP request self-contained and rebuild analysis as needed.
- **Pro:** Simple, deterministic, and less stateful.
- **Con:** Latency grows with project size and feature richness.
- **Maintainability:** Good for correctness, weak for interactive performance.

### Option B - Project snapshot cache

- **Approach:** Maintain per-project analysis snapshots with document overlays, invalidation, and cancellation-aware request handling.
- **Pro:** Required for responsive definition, references, rename, and semantic tokens.
- **Con:** Introduces lifecycle complexity and stale-result risks.
- **Maintainability:** Strong if snapshot ownership and invalidation are explicit.

## Tradeoffs

A complete LSP needs shared state, but shared state must not leak stale analysis into edits. The decision is about the boundary, not just caching.

## Recommendation

Prefer Option B before implementing workspace-wide features like references and rename.

## Discussion

Define snapshot lifecycle, invalidation triggers, and cancellation policy.

## Resolution

Ainda em aberto.

## Next Step

Decide whether snapshot caching is a prerequisite for references/rename or can be staged later.