Skip to the content
Diaspar

Decision D020 · accepted

Diaspar has its own live protocol, defined once and adapted to other clients

A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.

Status: accepted (2026-11-15). Research: reports/REPL and live connection protocols.md.

Decision

An own protocol, with Swank's debugger model

The REPL, the debugger (D017), and connections to running programs (D018) speak a protocol designed for Diaspar, not nREPL. Its debugger model follows Swank's: a frozen computation is reported with its error, frames, and restarts as data, and the client picks a restart.

Why not nREPL as the native protocol: it brings evaluation, file loading, completion, and documentation, but has no way to say "this computation is frozen; here are its frames and restarts", which is the point of D017. Every existing protocol mirrors its own runtime (nREPL the JVM's threads, Swank Common Lisp's conditions, Jupyter a single-threaded kernel, DAP debuggers that stop threads); Diaspar's restarts that resume in place, effects as the only path outside, task scopes, and versioned cells would be hidden by any of them.

One typed core, adapters generated from it

The protocol's messages are Diaspar types. The wire schema, its documentation, and adapters to other protocols are generated from those types, so the protocol cannot drift undocumented as Swank's did.

MCP from the start

An MCP adapter is part of the first version, because coding agents will be the first heavy users of the live connection. MCP has had no sessions since its 2026-07-28 revision, so the adapter wraps the stateful native protocol: it carries session and handle identifiers that the Diaspar runtime issues.

nREPL much later

An nREPL adapter, for Clojure editor tools (CIDER, Calva, Conjure), comes much later, if at all, and is tested with nREPL's compatibility suite (proof) when it does. LSP, DAP, and Jupyter adapters follow the same pattern.

Redefinition is atomic and reports its impact

  • Loading several definitions at once (a file, a module) either applies all of them or none.
  • Every redefinition reports what it changed and which frames and tasks still run the old code, with a version hash for each definition.

Revise.jl, Erlang's module versions, and Clojure's tools.namespace all show the same failure classes when this is left implicit; Chrome removed live editing of JavaScript in 2026 largely because its failures were confusing. Redefinition through global cells (D003) stays immediate.

Policies (accepted)

Question Recommendation
Wire format JSON-RPC 2.0 with Content-Length framing; Unix socket by default, stdio when spawned; positions as UTF-8 byte offsets plus line and column
Is the terminal REPL a protocol client? Yes, over an in-process transport, so the debugger is built once
Debugger under run --repl Freeze only when a client with the debug capability is attached; agent sessions get a deadline; sibling tasks keep running unless their scope asks to freeze
Interrupts Polls at loop back-edges and calls in --repl builds; an interrupt opens the debugger; measure the overhead (answers D006's open question)
Session capabilities inspect, eval with an effect list, redefine, debug, admin, enforced by handlers; foreign code behind an Unsafe effect (D002, D005)
Agent features in version 1 Output budgets, check without running, deadlines, a runtime-instance id, a discovery file, scoped handles; scratch sessions next