runa/CHANGELOG.md

# Changelog

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

## [Unreleased]

### Changed

- Pretty-print actor state and mailbox JSON with two-space indentation while
  preserving exact integers and actor-reference markers.
- Rename the actor's virtual log file to `actor.log` for automatic VS Code log
  highlighting and show syslog-style priority, actor, sequence, and severity fields.

- Expand VS Code actors into directories with read-only `meta.json`/`log`,
  live-editable `config.json`, and guarded natural-JSON `state.json`/`mailbox.json`.
- Allow reload/become to repair failed actors' implementations without clearing
  failure, state, or reserved messages; restart remains explicit.

- **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

- Server startup restoration with `--restore <file>` / `RUNA_RESTORE`, reusing
  snapshot validation and actor scheduling rules without merging bundled
  sources or falling back to a fresh image on errors.

- Explicit versioned disk image save/restore through the CLI, REPL, protocol and
  VS Code commands. Preserve source/history, actor identities, committed state,
  mailbox envelopes and retained logs; reject unfinished handlers, pause runnable
  actors on save and restore their scheduling eligibility with fresh incarnations.
  Snapshot files are server-local; replacement requires explicit authorization
  and is atomic.
- Atomic snapshot replacement with `save --overwrite`; VS Code prompts before
  replacing an existing server-local snapshot.

- Native VS Code debugger attachment to failed actors for retained-state,
  reserved-message and failure inspection, plus DAP exception details for both
  existing and newly observed failures. Debug controls never retry failed actors;
  no post-mortem stack is fabricated.

- Read-only snapshot-path watches and Debug Console lookups using
  `actor/<JSON Pointer path>`, with Add to Watch paths on actor variables,
  expandable results, exact integers and explicit rejection of Rune expressions.

- Read-only VS Code debugger actor-snapshot scopes with expandable committed
  state, mailbox, configuration and identity, exact integer formatting, paged
  children, and stale-handle invalidation. Invocation drafts and frame locals
  are not exposed or evaluated.

- Native VS Code **Debug Actor** attach sessions with exact loaded sources,
  gutter breakpoint verification, call stacks, pause/continue and bounded toolbar
  stepping. Sessions terminate on actor removal, implementation/incarnation change
  or image disconnect; detaching never kills or implicitly resumes the actor.

- Bounded source step-over and step-out through the runtime, image API, protocol,
  and VS Code actor commands, preserving nested breakpoints and async stop boundaries.

- Actor-local, implementation-bound source breakpoints with explicit line
  verification and scheduler pauses that retain active drafts and buffered sends.
- Bounded source step-into through the image API/protocol and VS Code actor
  actions, with stop reasons, exact loaded-source navigation, and async/lifecycle safety.

- Read-only execution-stack inspection with exact loaded source identities,
  bounded nested Rune frames, UTF-16 locations, and explicit pending-await status.
- VS Code **Inspect Execution Stack...** actor action, navigating frames in
  immutable loaded-source documents even after shared or temporary source edits.

- Structured Rune compilation errors and warnings through a read-only
  `check_source` protocol operation and compilation-failure error details.
- Automatic VS Code inline/Problems diagnostics for open image sources and
  actor-specific behavior documents, including unsaved edits, correct UTF-16
  locations, and stale-response/session isolation.

- Source file creation, rename/move with confirmed actor path updates and
  history preservation, and deletion guarded against running actor users.
- Server-owned actor-specific temporary behaviors, safe-boundary compile-on-save,
  and VS Code Edit Current Behavior, Go to Behavior, and confirmed Update Behavior
  actions. Temporary scripts appear as an actor's `behavior` file and are cleared
  by reload without implicitly committing shared source.

- 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.