runa/CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

Changed

• Breaking: Successful graceful stop and immediate kill now remove actors, discarding their state, mailbox, and retained logs. Failed actors remain until killed. Restart remains an independent, identity-preserving operation.
• Default the bundled self-incrementing counter's missing/null state to zero when it handles its first message.
• Mark removed actors' open VS Code inspection snapshots read-only with removed: true while removing them from the actor list.
• Breaking: Handler and shutdown-hook unit returns (including omitted returns) now retain the previously committed state instead of replacing it with null. Draft mutations are discarded; valid sends and message acknowledgement still commit.
• Change the bundled counter to an inc operation that logs each increment and continuously queues another increment to itself using ctx.this.
• Breaking: Protocol v5 adds actor log thresholds to snapshots, guarded editing operations, and opt-in log-history/follow operations and notifications.
• Move image sources and actors into a dedicated Runa Activity Bar sidebar, with the source file tree first and both views visible by default.
• Remove the VS Code Add Source Folder to Workspace command; image files are accessed exclusively through the automatic image-source Explorer view.
• Show the image's editable virtual source filesystem automatically in the VS Code Explorer without adding a workspace folder.
• Require an explicit runa-cli subcommand: repl starts the interactive session, and each image operation is also available as a one-shot command.
• Rename the REPL actor listing command from actors to ps, remove its cancel command, and rename mise run cli to mise run repl.

Fixed

• Refresh saved actor inspection JSON through filesystem notifications instead of an unavailable VS Code revert command.
• Always prompt for JSON state when Spawn with State is invoked from a source context menu, including multi-selection menu arguments.
• Close extension connections with a WebSocket handshake on disconnect, reconnect, and deactivation instead of terminating the transport immediately.
• Exit the REPL on Ctrl+C and complete the WebSocket close handshake instead of returning to the prompt.
• Complete the WebSocket close handshake when the CLI exits, preventing normal disconnects from producing a connection-reset protocol error on the server.

Added

• Editable VS Code inspection JSON for inactive actors, restoring protected fields with a warning; actor-reference copy actions and a scheduler toolbar button.

• Read-only ctx.this actor reference for transactional self-messaging.

• Guarded actor state and reserved/queued message editing through the CLI, REPL, and VS Code for paused/stopped/failed actors without active execution.

• Immediate actor logs via ctx.log(level, message) and severity helpers, per-actor thresholds, bounded retained history, and server-filtered CLI logs [-f|--follow] [actor...] subscriptions.

• Mutable image-owned source files organized beneath source/, with independent commit history and generated readable revision IDs. Spawn compiles the current working file whether committed or not.

• Internal sender/data envelopes and actor contexts with send and send_from; sends remain transactional and actors cannot construct privileged system commands.

• Graceful stop with optional on_shutdown(state), force kill, restart, pause/resume, and safe-boundary reload/become.

• VS Code image source filesystem, file-context spawn actions, and source commit/history/rollback controls.

• VS Code behavior explorer with revision history, implementation identities, and read-only Rune source documents isolated by connection and revision. Image notifications refresh behavior listings without changing historical source documents.

• VS Code actor spawning with explicit behavior and initial state, structured message sending, pause/resume/stop/restart controls, and explicit scheduler ticks. JSON inputs preserve i64 integers and $actor/$record markers.

• Lossless, size-bounded mutation requests and real-server/extension-host coverage for actor controls.

• Non-destructive image_changed server notifications with coalesced per-connection revisions and automatic VS Code tree/inspector refresh.

• Tests for WebSocket subprotocol negotiation, invalid messages, multi-client notifications, and automatic mailbox/lifecycle/failure inspector updates.

• Initial TypeScript VS Code extension with explicit localhost connection management, an actor explorer, and read-only state/mailbox/execution snapshots.

• Bounded protocol-v3 extension client with lossless 64-bit JSON integers, correlation checks, disconnect handling, and no automatic retries.

• Extension transport tests, real Rust-server interoperability coverage, and a VS Code host test for inspector refresh and reconnect isolation.

• Portable structured actor values: null, booleans, signed 64-bit integers, strings, lists, records, and distinct NanoID actor references.

• JSON state/message literals in the REPL, including named $actor references, $record escaping, and actor-reference completion inside nested values.

• Value conversion limits and tests for nested-state isolation, copied sends, cyclic/unsupported Rune output, and all-or-nothing structured transitions.

• Reusable loopback TCP protocol client with bounded messages, correlation checks, explicit connection failures, and no automatic request retries.

• Multi-client and reconnect tests proving that actors remain in the server-owned image after development clients disconnect.

• Typed, instruction-sliced Rune invocations with preserved async execution, wake-driven resumption, and cancellation tests.

• Minimal single-worker actor runtime with bounded FIFO mailboxes, private integer state, structured messages, immutable implementation IDs, explicit message effects, inspection, lifecycle events, stop, and restart.

• Runnable two-actor counter demonstration and tests for runaway fairness, pending-message isolation, failures, backpressure, and all-or-nothing effects.

• Interactive local CLI for spawning actors, sending messages, advancing ticks, inspecting actors/events, and stopping/restarting actors.

• Versioned BLAKE3 source and implementation identities, original-source retention, a Rune compile-input fingerprint, and an in-memory compiled artifact cache.

• In-memory named behavior revisions with optimistic publish checks, immutable history, rollback revisions, and runtime installation at idle handler boundaries.

• CLI commands for named behavior publishing, history, rollback, and installation, plus mise run run to launch the local executable.

• Cooperative actor pause/resume between scheduler ticks, preserving active invocations and emitting lifecycle events.

• Explicit safe-point state migration during implementation installation, with atomic failure behavior and migration events.

• Explicit invocation cancellation that requeues the reserved message for retry, exposed in the CLI and documented with native side-effect caveats.

• Active actor execution telemetry in snapshots: completed VM steps, instruction pointer, and call-frame depth.

• Trusted in-process runa-image-api service boundary for code and actor operations, now used by the local CLI.

• Versioned, transport-neutral runa-protocol request, response, and event DTOs with serde support and request validation.

• Transport-neutral runa-server dispatcher routing protocol commands through the image API with typed replies and error codes.

• Local JSON-lines stdio transport for the protocol dispatcher, with a 1 MiB request limit and explicit malformed-input failures.

• Reusable local child-process client for issuing correlated protocol requests and shutting down the server process cleanly.

• Loopback-only TCP JSON-lines endpoint for local development clients, sharing the same live image as stdio and limiting concurrent clients.

• Execution-model decision and Phase 1 runtime documentation.

• Lifecycle tests proving failed-message retry from committed state and stop/restart preservation of reserved-first FIFO order.

• NanoID-based public actor references, explicit behavior-and-state spawning, named REPL actor bindings, tab completion, and command history navigation.

• NanoID-based public actor references, explicit behavior-and-state spawning, named REPL actor bindings, tab completion, and command history navigation.

• Runnable Phase 0 experiment pinned to Rune 0.14.2, covering script execution, native calls, async suspension, instruction budgets, frame inspection, stepping, and compiled-code sharing across isolated VMs and threads.

• Tests for feasibility results, invalid source, runtime errors, independent stacks, and cancellation by dropping suspended execution.

• Rune feasibility report with measured timings, shallow object sizes, limitations, and a proposed Phase 1 execution model.

• Initial Rust workspace with the runa binary and a runa-rune library scaffold for Phase 0. Rune integration is not implemented yet.

• Project README and agent guidelines.

• Base directories for architectural decisions, default image scripts, development automation, examples, system tests, and the VS Code extension.

• Mise tasks for formatting, Clippy linting, workspace tests, and sequential pre-commit validation.

• Tombi, rustfmt, and Clippy configurations.

Changed

• Breaking: Protocol v4 spawns by source path (for example actors/counter). Rune handlers are now handle(ctx, state, sender, message) -> state, with sends through the context instead of returned transition tuples.

• Breaking: CLI commit <path> replaces publishing; history and rollback use file paths and generated revision IDs. Source saves, commits, and actor reloads are separate operations.

• Renamed the server executable/crate from runa-server to runa, and the REPL from runa to runa-cli. The server now listens on 127.0.0.1:3737 by default.

• Clap derive/env argument parsing for both executables, including generated help/version, RUNA_LISTEN / RUNA_CONNECT, and flag-over-environment precedence.

• mise run start now starts the server; mise run cli launches the REPL.

• Replaced the plain TCP JSON-lines transport with loopback-only WebSockets using the required runa-debug subprotocol in the server, REPL, and VS Code. Stdio framing and version 3 request/response shapes are unchanged.

• Renamed the local REPL mise task from run to start.

• Protocol v3 and Rune's two-argument handle(state, message) replace the temporary integer-only state and kind/value/target_ref message envelope. Returned sends now contain (actor_reference, message) pairs; migrations, snapshots, and events preserve structured values.

• The REPL now connects to the localhost server rather than embedding its own image. Start the server first; --connect selects a loopback endpoint.

• TCP server startup publishes the bundled counter behavior once; connecting or disconnecting clients does not reset behavior revisions or actor state.

• Interactive CLI commands now use the versioned protocol dispatcher instead of calling the image API directly.

• Protocol version 2 replaces numeric actor IDs with NanoID actor references and adds optional target references for message effects.

• Protocol version 2 replaces numeric actor IDs with NanoID actor references and adds optional target references for message effects.

• Actor implementation IDs now identify compiled source/configuration content rather than using sequential process-local numbers.

• Expanded the architecture specification with crate ownership and dependency boundaries, and moved it to docs/architecture.md.

• Required agents to pass mise run pre-commit before every commit and document user-visible changes in this changelog.

Removed

• Stdio protocol transport and child-process client; external clients now use runa-debug WebSockets exclusively. Removed the serve and serve-network mise tasks.