LSP#

A filesystem makes stored and derived documents broadly accessible, but some work is not naturally a file. A query has a result, a mutation needs preview and confirmation, and a long-lived client must learn when committed data changes. Inventing separate protocols for editors and agents would make the same capabilities behave differently in each environment. One established bidirectional protocol gives both kinds of client the same interface for direct actions and subscriptions.

One interface for editors and agents#

The Language Server Protocol already connects editors to long-running processes through requests, responses, and notifications. It defines initialization, capability discovery, cancellation, progress, diagnostics, document synchronization, and a standard envelope for extensions. Stardust exposes an LSP bridge from each mount, so an editor and an agent discover and invoke the same capabilities through the same session model.

This choice provides editor behavior through the same interface that agents use. Completion, hover, navigation, diagnostics, and code actions operate on JSON and DUST documents in the mount. An agent can use these features, execute the same commands, and receive the same change signals. No adapter must translate an editor API into an agent API. Each client uses only the capabilities it needs.

Feedback before the save boundary#

FUSE can refuse invalid content when a program writes it, but the kernel can give only a coarse filesystem error. LSP sees the open document buffer as it changes, before that buffer is written to the mount. Stardust can therefore report syntax, schema, reference, and semantic problems at their source ranges while the author is still editing.

Standard diagnostics explain the problem, and code actions can offer a precise repair. An editor can display that feedback beside the affected text. An agent can inspect the same diagnostics and apply the same edits. The filesystem remains the authority that accepts or refuses the eventual save. LSP explains the boundary before the author reaches it.

Direct actions use one standard request#

LSP's workspace/executeCommand method gives direct actions a common request-and-response shape. Stardust advertises its available commands during initialization, including expression evaluation, query execution, mutation execution, entity creation, entity validation, and backup-definition creation. A patch file can create entities with temporary names. The SDK patch methods use the bridge to receive the resolved IDs. A client discovers that registry rather than assuming which operations a particular server implements.

The command contract also states which operations preview work or require confirmation. Read-only queries and expressions can give their results directly. A mutation can first give the selected entities and intended patch, then require explicit confirmation before it commits. The protocol stays uniform while the command records the safety rules appropriate to its effect.

jsonrpc '2.0'
id      1
method  workspace/executeCommand
params  {command   stardust.query.execute
         arguments [{document {find [?entity]}}]}

Notifications make the connection live#

The session continues after one response, so the server can report later commits on the same channel. A client opts into Stardust's advertised entitiesChanged or documentsChanged notifications during initialization. Generated SDKs use entity changes for subscriptions, while editors use document changes to refresh open projections, diagnostics, and generated files.

A notification says that current state changed. It is not a second transaction log. Notifications may combine when commits arrive faster than a client reads them. Subscribers then read current state or evaluate their query again. Delivery stays bounded, and the database remains the authority. Durable history remains available through the mounted transaction files.

Editors and agents therefore share initialization, capability negotiation, direct actions, subscriptions, cancellation, errors, and one long-lived connection. Client libraries can wrap that protocol with types, but they do not have to invent another transport or a separate product interface.