chore: scaffold Phase 0 repository structure

Move the updated architecture specification into docs, add the Rune adapter library scaffold, and reserve the planned repository directories.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

AGENTS.md

@@ -4,11 +4,11 @@
 
 Runa (short for **Rune Actors**) is an experimental Rust project whose long-term
 goal is a persistent, live programming world built around isolated Rune actors.
-The current workspace is a minimal Rust executable; Rune integration and the
+The current workspace contains a minimal Rust executable and a Rune adapter
-actor runtime are not implemented yet.
+scaffold; Rune integration and the actor runtime are not implemented yet.
 
 The architecture, design goals, constraints, and implementation roadmap are
-documented in [runa-spec-architecture.md](runa-spec-architecture.md). Treat
+documented in [docs/architecture.md](docs/architecture.md). Treat
 proposed capabilities as plans, not existing behavior.
 
 ## Architecture and constraints
@@ -30,8 +30,14 @@ proposed capabilities as plans, not existing behavior.
 
 - `Cargo.toml`: Rust workspace definition.
 - `crates/runa/`: current executable crate and entry point.
-- `runa-spec-architecture.md`: architecture, roadmap, risks, and acceptance
+- `crates/runa-rune/`: Phase 0 Rune compilation and execution adapter scaffold.
-  scenario.
+- `docs/architecture.md`: architecture, roadmap, risks, and acceptance scenario.
+- `docs/decisions/`: architectural decisions.
+- `runa-std/`: default Rune scripts for an image.
+- `scripts/`: general-purpose development automation.
+- `tests/`: system and end-to-end tests; require an explicit runner rather than
+  assuming Cargo discovers tests at a virtual workspace root.
+- `examples/` and `vscode/`: reserved for examples and the VS Code extension.
 - `README.md`: project overview and current getting-started instructions.
 
 ## Commands

Cargo.lock

@@ -5,3 +5,7 @@ version = 4
 [[package]]
 name = "runa"
 version = "0.0.0"
+
+[[package]]
+name = "runa-rune"
+version = "0.0.0"

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
 resolver = "3"
 members = [
-    "crates/runa",
+    "crates/runa", "crates/runa-rune",
 ]

README.md

@@ -9,7 +9,8 @@ image.
 ## Status
 
 Runa is at an early prototype stage. The current repository contains a minimal
-Rust executable; the actor runtime, Rune integration, graphical world, and
+Rust executable and a scaffold for the Rune adapter library; the actor runtime,
+Rune integration, graphical world, and
 development API described in the architecture spec are planned, not yet
 implemented.
 
@@ -25,7 +26,7 @@ interruptibility, and debugging capabilities before building the actor kernel.
 - Expose the same runtime capabilities to in-world tools and external clients.
 - Be explicit about execution, delivery, and persistence guarantees.
 
-See [runa-spec-architecture.md](runa-spec-architecture.md) for the full vision,
+See [the architecture spec](docs/architecture.md) for the full vision,
 architecture, roadmap, and open questions.
 
 ## Getting started
@@ -46,7 +47,27 @@ At this stage, it prints `Hello, world!`.
 .
 ├── Cargo.toml
 ├── crates/
-│   └── runa/
+│   ├── runa/             # Main binary
-│       └── src/main.rs
+│   └── runa-rune/        # Phase 0 Rune adapter scaffold
-└── runa-spec-architecture.md
+├── docs/
+│   ├── architecture.md
+│   └── decisions/
+├── runa-std/
+│   ├── core/
+│   ├── actors/
+│   ├── ui/
+│   └── tools/
+├── scripts/
+├── vscode/
+├── examples/
+└── tests/
 ```
+
+`runa-std/` is reserved for the default Rune scripts loaded into an image.
+`scripts/` is for general-purpose development automation. Root-level `tests/`
+is reserved for system and end-to-end tests; it is not automatically discovered
+by Cargo. Add an explicit runner when those tests are introduced, keeping Rust
+crate integration tests within each crate.
+
+Only the Phase 0 crates are scaffolded. The remaining crates in the spec will
+be added as their functionality is implemented.

crates/runa-rune/Cargo.toml

@@ -0,0 +1,6 @@
+[package]
+name = "runa-rune"
+version = "0.0.0"
+edition = "2024"
+
+[dependencies]

crates/runa-rune/src/lib.rs

@@ -0,0 +1,3 @@
+//! Rune compilation and execution adapter for Runa.
+//!
+//! This crate is a scaffold; Rune integration is not implemented yet.

docs/architecture.md

@@ -1,6 +1,6 @@
-# **R**un**A** — Project Specification and Architecture
+# Runa — Project Specification and Architecture
 
-**Status:** Initial architecture, revision 2  
+**Status:** Architecture specification, revision 4 (Runa naming)  
 **Primary host language:** Rust  
 **Initial embedded language:** Rune  
 **Inspirations:** Smalltalk/Squeak/Pharo, Morphic, Erlang/OTP  
@@ -8,7 +8,7 @@
 
 ## 1. Vision
 
-Build a self-contained, persistent, live programming world. Its fundamental computational entities are actors, not shared mutable objects. The environment itself is programmable and inspectable, with live actor spawning, message sending, state inspection, behavior editing, debugging, and hot code upgrades. A VS Code extension provides an equally capable external interface to the *same* running image via a programmatic API.
+Build a self-contained, persistent, live programming world. Its fundamental computational entities are actors, not shared mutable objects. The environment itself is programmable and inspectable, with live actor spawning, message sending, state inspection, behavior editing, debugging, and hot code upgrades. A VS Code extension provides an equally capable external interface to the _same_ running image via a programmatic API.
 
 Rust supplies a minimal, reliable substrate; increasingly much of the actor framework, graphical world, and development tools should be implemented in Rune. The end state is a Smalltalk-like image with Erlang-inspired actor isolation and modern tooling.
 
@@ -265,10 +265,75 @@ Implement persistence incrementally:
 
 Start with SQLite or another simple durable store plus Git-friendly source export. Define snapshot consistency explicitly. Never assume arbitrary Rune stacks, closures, and native resources can be serialized and restored. Preserve mailbox and state transaction invariants across recovery.
 
-## 11. Proposed Repository
+## 11. Workspace Boundaries and Dependency Direction
+
+The Rust workspace uses **acyclic, inward-pointing dependencies**. The executable (`runa`) is the composition root. Higher-level services depend on lower-level contracts; low-level crates never import graphical, transport, or application code.
+
+### 11.1 Dependency diagram
+
+Arrows mean **"depends on"**, not runtime data flow:
 
 ```text
-live-world/
+                          runa
+                        /   |   \
+                       v    v    v
+                runa-world  runa-server
+                    |        /     \
+                    v       v       v
+              runa-image-api      runa-protocol
+                    |                  |
+                    v                  |
+                runa-runtime           |
+                /        \             |
+               v          v            |
+          runa-actor   runa-rune       |
+               \          /            |
+                v        v             v
+                 runa-core <-----------+
+
+runa-world also depends on runa-graphics (platform drawing/input
+contracts); runa-graphics depends only on runa-core when needed.
+runa-server depends on runa-image-api and runa-protocol.
+runa wires together world, server, runtime, storage and platform.
+```
+
+The diagram is conceptual; Cargo dependencies should be kept minimal. A dependency is permitted only when the importing crate actually uses that crate's public contracts. The VS Code extension is a separate TypeScript project and depends on the **wire protocol**, not Rust crates.
+
+### 11.2 Crate ownership
+
+| Crate            | Owns                                                                                                                                               | May depend on                          |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
+| `runa-core`      | Small, stable value types shared across independent layers: `ActorId`, `ImplementationId`, canonical message value types, common error identifiers | Minimal external libraries only        |
+| `runa-actor`     | Mailbox and state-transition semantics, message reservation, acknowledgment, effects, actor lifecycle definitions                                  | `runa-core`                            |
+| `runa-rune`      | Rune compilation, VM execution, suspension, interruption hooks, language-specific diagnostics                                                      | `runa-core`, Rune libraries            |
+| `runa-runtime`   | Scheduling, actor execution coordination, state commits, crash recovery, binding actor semantics to Rune execution                                 | `runa-core`, `runa-actor`, `runa-rune` |
+| `runa-image-api` | Authorized in-process operations for spawning, inspecting, sending, editing, upgrading, and debugging                                              | `runa-core`, `runa-runtime`            |
+| `runa-protocol`  | Versioned transport-neutral request/response/event DTOs and validation                                                                             | `runa-core`                            |
+| `runa-server`    | WebSocket/JSON-RPC transport, sessions, authentication, subscriptions                                                                              | `runa-protocol`, `runa-image-api`      |
+| `runa-graphics`  | Native window, rendering and input mechanisms; no actor policy                                                                                     | `runa-core` if necessary               |
+| `runa-world`     | Morphic-style graphical composition and in-world development UI                                                                                    | `runa-image-api`, `runa-graphics`      |
+| `runa`           | Startup, configuration, resource wiring, shutdown                                                                                                  | Top-level crates it instantiates       |
+
+**Important:** `runa-core` must not contain schedulers, mailbox implementations, persistence engines, Rune VM types, service traits used by only one crate, generic helper collections, or GUI abstractions. Prefer a type defined in its owning crate until two independent consumers demonstrably need a stable shared representation.
+
+### 11.3 Runtime interfaces and avoiding cycles
+
+- `runa-actor` defines actor rules and data contracts; it does **not** spawn threads or call Rune.
+- `runa-rune` executes Rune code but does **not** own actor scheduling, mailboxes, or image APIs.
+- `runa-runtime` coordinates both. Initially it can depend directly on `runa-rune`; introduce an execution-adapter trait only when a second implementation or test double justifies it. Place the trait at the lowest layer that actually consumes it, rather than automatically in `runa-core`.
+- `runa-image-api` is the single application-service entry point for in-world tools and external clients. Its methods enforce permissions, lifecycle invariants, and revision checks.
+- `runa-protocol` holds wire DTOs, **not** runtime service implementations. Translate DTOs at the server boundary; never serialize internal actor locks or VM references.
+- `runa-world` uses the same `runa-image-api` operations as the external bridge. It does not reach into runtime internals for convenience.
+- Native platform handles stay behind `runa-graphics` (or a later platform crate), not in `runa-core`.
+
+For content-addressed code, start with source/implementation IDs in `runa-core` and the actual canonicalization, hashing, storage and compilation-cache logic in the crate that owns those operations. If the code store becomes substantial, extract `runa-code` as a separate crate, depending on `runa-core`, and have `runa-runtime`/`runa-rune` consume its APIs through a clearly owned boundary. Do not move all code-store logic into `core`.
+
+For persistence, begin with a concrete adapter wired by `runa`. Extract `runa-storage` only when its durable mailbox, state, outbox and artifact contracts are clear. Keep database-specific details out of actor semantics and out of `runa-core`.
+
+### 11.4 Repository layout
+
+```text
+runa/
 ├── Cargo.toml
 ├── README.md
 ├── docs/
@@ -278,25 +343,28 @@ live-world/
 │   ├── protocol.md
 │   └── decisions/
 ├── crates/
-│   ├── world-core/
+│   ├── runa-core/
-│   ├── world-actor/
+│   ├── runa-actor/
-│   ├── world-runtime/
+│   ├── runa-rune/
-│   ├── world-rune/
+│   ├── runa-runtime/
-│   ├── world-protocol/
+│   ├── runa-image-api/
-│   ├── world-server/
+│   ├── runa-protocol/
-│   ├── world-graphics/
+│   ├── runa-server/
-│   └── world-app/
+│   ├── runa-graphics/
-├── scripts/
+│   ├── runa-world/
+│   └── runa/
+├── runa-std/
 │   ├── core/
 │   ├── actors/
 │   ├── ui/
 │   └── tools/
+├── scripts/
 ├── vscode/
 ├── examples/
 └── tests/
 ```
 
-These are intended boundaries, not an instruction to generate empty crates prematurely. Start with the smallest workspace that supports the current experiment.
+This is a **target layout**, not a request to generate empty crates. For Phase 0, begin with `runa-rune` and a small executable test harness. Introduce `runa-core`, `runa-actor`, and `runa-runtime` only as the corresponding functionality is implemented. Enforce the dependency direction through Cargo manifests and periodic dependency-graph checks; reject circular dependencies and upward imports in code review.
 
 ## 12. Implementation Roadmap