Crate ty_plugin_protocol 

ty_plugin_protocol

The stable serialized contract between ty-extended and semantic extensions.

This crate intentionally contains data types only. It does not depend on checker internals, Salsa, AST ids, the plugin host, or a WASM engine. Manifests, requests, responses, claims, patches, diagnostics, and type expressions can therefore be serialized independently of ty’s implementation.

Most extension authors should depend on ty_plugin_sdk, which re-exports this crate as ty_plugin_sdk::protocol and adds the Plugin trait, ManifestBuilder, typed patch helpers, dispatch, and WASM exports.

Depend on ty_plugin_protocol directly when implementing a host, validating manifests, inspecting wire messages, or building protocol tooling.

Add the Dependency

[dependencies]
ty_plugin_protocol = "0.0.3"

Protocol Model

The main types are:

• PluginManifest: identity, compatibility, runtime, capabilities, claims, configuration, and stub overlays;
• PluginRequest: the tagged request enum sent by a host;
• PluginResponse: the tagged response enum returned by an extension;
• request summaries such as AnalyzeClassRequest, CallRequest, and ResolveMemberRequest;
• declarative outputs such as ClassPatch, MemberPatch, CallSignaturePatch, and ProjectIndexResponse;
• TypeExpr: source-level type data with expression, annotation, or stub mode;
• ProtocolVersion: compatibility negotiation between a host and extension.

The wire format is JSON with kebab-case field and variant names. A request is self-contained and a response is data; neither side shares memory objects from the checker.

Compatibility Negotiation

The protocol is pre-1.0. A host accepts the same protocol major and any extension minor version no newer than its own:

use ty_plugin_protocol::{ProtocolCompatibility, ProtocolVersion};

let host = ProtocolVersion { major: 0, minor: 3 };
let extension = ProtocolVersion { major: 0, minor: 2 };

assert_eq!(
    host.negotiate(extension),
    ProtocolCompatibility::Compatible,
);

Unknown JSON fields remain parseable for forward transport, but successful deserialization is not permission to use unsupported behavior. Always negotiate the version before dispatching requests.

Example Manifest Fragment

{
  "id": "my-extension",
  "name": "My extension",
  "version": "0.1.0",
  "protocol-version": { "major": 0, "minor": 3 },
  "ty-compatibility": { "requirement": ">=0.59.0,<0.60.0" },
  "runtime": {
    "kind": "wasm",
    "artifact": "my_extension.wasm"
  },
  "capabilities": {
    "call-return": true
  },
  "claims": {
    "functions": [
      { "qualified-name": "my_library.Field" }
    ]
  }
}

Use ty_plugin_sdk::ManifestBuilder instead of hand-writing production manifests; it keeps claims and capability flags aligned.

See the extension authoring guide to build a complete WASM extension and the ty_plugin_sdk API documentation for the author-facing interface.

Structs

AnalyzeClassRequest

ArgumentSummary

AssignmentSummary

AttributeClaim

BuildProjectIndexRequest

CallRequest

CallReturnPatch

CallSignaturePatch

CallValueSummary

CallableSignature

ClassClaim

ClassPatch

ClassSummary

ConstantSummary

Contribution

DependencyRequest

DiagnosticLocation

FieldPatch

FieldSummary

ImportBinding

LiteralDictEntry

MemberPatch

MemberSummary

MethodClaim

MethodSummary

ModuleClaim

MutationRequest

A syntax-level write or delete operation offered to a semantic plugin for validation.

MutationResponse

NestedClassSummary

Parameter

PluginCapabilities

PluginClaims

PluginDependency

PluginDiagnostic

PluginError

PluginManifest

ProjectContext

ProjectIndexResponse

ProtocolVersion

ReceiverSummary

ResolveMemberRequest

SemanticContext

SettingValueSummary

SettingsClaim

SettingsModuleSummary

StubOverlay

SubprocessRuntimeSpec

SymbolClaim

SymbolRef

SymbolSource

TextPosition

TypeExpr

TypeSnapshotExpression

TypeSnapshotField

TypeSnapshotMetadata

ValueSummary

VersionReq

VirtualTypeDefinition

VirtualTypeField

WasmRuntimeSpec

Enums

ArgumentKind

AssignedValueSummary

AttributeClaimKind

AttributeScope

CallOrSymbolSummary

ClassClaimKind

ContributionPatch

ContributionTarget

DiagnosticSeverity

LiteralValue

MemberAccessPatch

MemberPatchMode

MethodClaimKind

MutationOperation

ParameterKind

PluginRequest

PluginResponse

ProtocolCompatibility

The outcome of negotiating a plugin’s declared ProtocolVersion against the host’s.

RuntimeSpec

TypeExprMode

TypeSnapshot

Structural type data that survives a complete host -> plugin -> host round trip.

VirtualTypeShape

Constants

CURRENT_PROTOCOL_VERSION