Microsoft’s Type Server Protocol: Keep Type Results Tied to Their Snapshot

Microsoft’s Type Server Protocol: Keep Type Results Tied to Their Snapshot

A code-analysis tool can return a well-formed answer that no longer describes the code in front of you. If you are integrating Microsoft’s Type Server Protocol, make workspace state part of the result you track. That matters when a developer edits a file while a background query is still running.

Why the protocol is getting attention

Microsoft’s October 21, 2026 announcement describes TSP as a way to separate Pylance’s editor-intelligence layer from its type-checker backend, including support for Meta’s Pyrefly. This is an integration contract to examine, rather than a reason to assume every editor or checker combination already works.

Microsoft: Pylance, Pyrefly and the Type Server Protocol

A snapshot identifies the analysis state

The protocol overview defines a snapshot as a numbered view of the server’s analysis state. Returned objects are generally valid for that snapshot. Changes that could invalidate analysis must advance it. A request carrying an outdated snapshot should receive a retryable error; the documentation prefers ServerCancelled, code -32802.

TSP overview: snapshots, result identity and error handling

For example, an earlier query may finish after an edit. Keep the request’s state context, and check it before presenting the answer as current.

Check compatibility before interpreting results

The TypeScript protocol definitions identify version 0.4.1 and require clients to check supported versions. They warn that minor-version changes in the 0.x series may break compatibility. Record the client’s expected protocol and the server’s reported version in your integration diagnostics, rather than inferring compatibility from a package name.

Authoritative TypeScript definitions and version contract

Pyright documents a separate pyright-typeserver package driven by a client over the protocol, rather than an interactive command-line session. Its documentation distinguishes direct type-information queries from editor-oriented language-server features. A working connection therefore does not by itself demonstrate correct document synchronization or result handling.

Pyright: type-server role and client-driven operation

Turn the contract into a small integration trial

Start with a disposable project and one feature that consumes a type result. Save the software versions, document state and request details with each observation. The following are suggested acceptance checks, not results of a client tested for this article.

• Establish a baseline query against a known, unchanged file and inspect its response.
• Edit the relevant code while a query is outstanding; check that your feature does not present an outdated answer as current.
• Exercise the stale-snapshot error path and confirm that a retry obtains fresh state rather than repeating the same stale request indefinitely.
• Keep invalid-parameter and internal-error handling distinct from a retryable state change.
• Repeat the edit-and-query sequence several times and preserve unexpected responses.

Define a retry limit and a visible failure state for your own client. If edits continue faster than useful results arrive, it is better for the feature to show that analysis is pending than to conceal the mismatch. Preserve a minimal reproduction when behavior differs from the contract.

What this establishes

The documentation gives an implementer a concrete consistency contract to verify. It does not establish your client’s correctness, the performance of a particular checker, or the safety of a code change proposed from its output. No server, editor integration or protocol exchange was independently executed for this article.