docs: consolidate design documentation and standardize crate English

crates/worker-runtime/README.md

@@ -1,45 +1,10 @@
 # worker-runtime
 
-`worker-runtime` owns the Runtime authority surface for Worker management. A Runtime process bundles Worker lifecycle management, the HTTP/WebSocket control API, and the Worker execution backend.
+Manages Worker creation, stopping, and Restore, execution connections within the Runtime, and Workdir materialization. The Backend owns Workspace records and grants; the Worker controller owns model execution and input acceptance. Optional features provide HTTP/WebSocket and filesystem persistence.
 
-## Run the local Runtime server
+## Reference index
 
-From the repository root:
-
-```bash
-cargo run -p worker-runtime \
-  --bin yoi-runtime \
-  -- --bind 127.0.0.1:38800
-```
-
-By default the server listens on:
-
-```text
-127.0.0.1:38800
-```
-
-To bind another address explicitly:
-
-```bash
-cargo run -p worker-runtime \
-  --bin yoi-runtime \
-  -- --bind 0.0.0.0:38800
-```
-
-The REST server is intended for a trusted Backend/proxy, not direct browser access.
-Workspace requests authenticate the actual HTTP request with the Workspace's current
-signing identity. The Runtime verifies signatures against its explicitly enrolled
-Workspace public key and binds the Runtime audience, Workspace/Worker scope,
-operation, method, path/query, body digest, expiry, and single-use token ID. A
-connection test is an ordinary signed `/v1/ping`; no prior handshake or saved
-verification evidence is required or consulted.
-
-Keep `trust-workspace add`, `replace`, and `revoke` as explicit operator actions.
-A self-reported public key cannot grant trust. Trust record IDs are administrative
-only and must not be copied into Backend registration or request claims. Replay
-protection uses Workspace plus the trusted key fingerprint, so re-enrolling the
-same key or rotating away and back cannot reset consumed requests. Reaccepting a
-key does permit fresh, unconsumed requests signed by that key until their short
-expiry; it does not create a separate sender-controlled enrollment namespace.
-
-For authenticated remote Runtime setup, see [`../../docs/development/server-runtime-auth.md`](../../docs/development/server-runtime-auth.md).
+- [`Runtime`](crate::Runtime): lifecycle operation acceptance, Workspace boundaries, and execution connections.
+- [`execution`] — execution backends and operation-specific results.
+- [`working_directory`] — repository materialization, session resources, and safe deletion.
+- [`workspace_issuer`] — Workspace signature verification and replay prevention.

crates/worker-runtime/src/execution.rs

@@ -1,3 +1,11 @@
+//! Operation and result boundaries between Runtime and execution backends.
+//!
+//! Lifecycle operation IDs identify durable reconciliation; they are not interchangeable with
+//! controller command IDs or Submit/Notify request IDs. Catalog Idle/Stopped status alone does
+//! not determine input acceptance. Submit/Notify success rests on their durable receipts,
+//! not transport enqueueing or connection closure. Lost responses do not imply no effects;
+//! operation-specific unknown/settlement rules still apply.
+
 use crate::catalog::{
     ConfigBundleRef, ProfileSelector, RepositoryRefObservation, RepositoryRefObservationRequest,
     WorkingDirectoryRepositoryAccessRequest, WorkingDirectoryRequest, WorkingDirectoryStatus,
@@ -224,6 +232,13 @@ enum WorkerExecutionPublicationState {
     Discarded,
 }
 
+/// Publication boundary for protocol observations bound to Worker identity.
+///
+/// Restore candidates buffer events until the execution commit to the catalog succeeds.
+/// Events during activation join the same queue, so publication preserves event order.
+/// Discarding a candidate on rollback also suppresses its later events. This isolation prevents
+/// a newly started controller from exposing a live candidate inconsistent with the settled
+/// catalog; it does not prove execution cleanup.
 #[derive(Clone)]
 pub struct WorkerExecutionContext {
     worker_ref: WorkerRef,

crates/worker-runtime/src/fs_store.rs

@@ -1,3 +1,21 @@
+//! Filesystem persistence for the Runtime catalog and Worker aggregates.
+//!
+//! Atomically publishes settled Worker status, execution binding, and pending lifecycle operations
+//! as one Worker record. Session content and metadata projections use separate stores;
+//! sockets and run paths do not substitute for durable identity.
+//!
+//! Legacy conversion copies the Runtime tree into staging under the OS owner lock, validates
+//! Worker record/metadata/Manifest identity consistency, then syncs and switches trees.
+//! Partially converted trees are not opened as normal authority. Duplicate identities, existing
+//! targets, missing Workspace bindings, and metadata identity mismatches are rejected, not guessed away.
+//! After interruption, staging/backup and validation determine which tree to publish;
+//! writes do not continue into an incomplete tree.
+//!
+//! Directories without Worker records are archived, not adopted into the normal catalog.
+//! Archive target collisions are rejected; data of unknown ownership is never overwritten or deleted.
+//! Symlinks/special files are rejected except recognizable stopped sockets. Preserving historical
+//! data and deciding whether execution hints can migrate are separate judgments.
+
 use crate::catalog::{
     ConfigBundleRef, CreateWorkerRequest, LogicalWorkdirAttachment, ProfileSelector,
     WorkerRestoreIntent, WorkerStatus, WorkingDirectoryAttachmentClaim,

crates/worker-runtime/src/lib.rs

@@ -1,10 +1,4 @@
-//! Embedded Runtime domain API for Worker management.
-//!
-//! `worker-runtime` owns the Runtime authority surface and, for the standalone
-//! process, wires that Runtime to the real Worker host. Filesystem persistence is
-//! available only through the optional `fs-store` feature, and the REST/WebSocket
-//! server is available only through the optional `http-server` / `ws-server`
-//! features.
+#![doc = include_str!("../README.md")]
 
 pub mod auth;
 pub mod catalog;

crates/worker-runtime/src/runtime.rs

@@ -300,13 +300,25 @@ impl Drop for RuntimeEventSelectorSubscription {
     }
 }
 
-/// Concrete embedded Runtime domain entity.
+/// Domain entity managing Worker lifecycles and Runtime-local resources.
 ///
-/// The default implementation is memory-backed and tools/provider-less by
-/// design.  An optional `fs-store` feature adds filesystem persistence while
-/// preserving the same typed authority boundary. It can later be adapted by
-/// backend registries or web servers without making sockets, sessions, or paths
-/// public authority.
+/// Memory-backed by default, with persistence provided by `fs-store`. Workspace registry
+/// projections do not authorize controller input admission. Scoped operations validate current
+/// Workspace membership and delegate to execution backends/controllers. Per-Worker operation
+/// locks serialize lifecycle changes.
+///
+/// Workdir cleanup reserves target IDs under the state mutex, then inspects and deletes files
+/// outside it. Conflicting use/cleanup of the same target is rejected without blocking unrelated
+/// Worker observations on long I/O. Transient reservations replace neither durable deletion
+/// evidence nor Backend attachment authority.
+///
+/// Restore/Stop separate settled status from pending operations, persisting intent before backend
+/// side effects. Pending operations reject conflicting input, lifecycle, deletion, and retention
+/// even when status appears Idle/Stopped. Startup reconciles pending Stop first and does not
+/// auto-restore Workers whose stop is confirmed and committed. Restore reuses the same operation
+/// ID; candidates with uncertain commit/cleanup are not replaced by new executions. Successful
+/// commit publishes backend observation registration and buffered protocol events; rollback
+/// discards the candidate.
 #[derive(Clone, Debug)]
 pub struct Runtime {
     inner: Arc<Mutex<RuntimeState>>,
@@ -1858,6 +1870,18 @@ impl Runtime {
             .into_legacy_result()
     }
 
+    /// Admits Restore with a fixed observation token and request ID.
+    ///
+    /// Revalidates the token under the Worker operation lock and saves the request owner and
+    /// `pending_restore` operation ID in the same Worker record before preparation/execution.
+    /// The same request reuses its stored payload; replaying a terminal receipt never restarts
+    /// a Worker stopped later. New intent with an old token conflicts. This token is an admission
+    /// boundary distinct from controller command IDs and cleanup-plan digests.
+    ///
+    /// If a saved pending operation has no public owner, binds recovery to that operation without
+    /// substituting another request or preparing a new candidate. Uncertain commits/responses
+    /// retain ReconciliationRequired, never implying no effect or rollback. Accepted denotes
+    /// Restore commit, not success of a subsequent Run.
     pub fn restore_worker_operation_scoped(
         &self,
         scope: &RuntimeWorkspaceScope,
@@ -3533,6 +3557,12 @@ impl Runtime {
     }
 
     #[cfg(feature = "ws-server")]
+    /// Checks the authorized Worker against the captured execution endpoint before operating.
+    ///
+    /// Validates scope, pending lifecycle settlement, and endpoint freshness before durable mutation.
+    /// Never forwards send/Shutdown to the next execution of the same WorkerRef, even if this
+    /// connection has not observed the old execution ending. Continued registry observation
+    /// and the operational connection have separate lifetimes.
     pub fn send_connected_protocol_method_scoped(
         &self,
         scope: &RuntimeWorkspaceScope,

crates/worker-runtime/src/worker_backend.rs

@@ -1,11 +1,19 @@
-//! Adapter from `worker-runtime` execution backend boundary to the real
-//! `worker` crate controller/run lifecycle.
+//! Adapter connecting Runtime execution contracts to the existing Worker controller.
 //!
-//! The adapter intentionally owns real `WorkerHandle`s internally and exposes
-//! operations addressed by `WorkerRef` to callers. Browser/API
-//! projections therefore keep the existing runtime redaction boundary: no raw
-//! socket paths, session paths, manifests, credentials, or handles leave this
-//! module.
+//! Separates durable Worker/Session identity from a single controller launch. Fresh runs use unique
+//! IDs; Restore runs use lifecycle operation IDs. Reuses registered controllers for the same Restore
+//! operation. Even after restart, exclusive creation of operation-bound run directories prevents
+//! overwriting existing runs. Run artifacts or sockets alone prove neither controller liveness nor cleanup.
+//!
+//! Opens Session and metadata stores within the aggregate through trusted WorkerRef, with no
+//! process-global root fallback. Restore preserves identity while rebuilding Workspace connections
+//! and Workdir bindings. Candidate controller observation registration waits for activation after
+//! catalog commit. Cleanup checks the actual controller and session resources, deleting only
+//! operation-owned disposable run artifacts. It implies neither Session/metadata deletion nor
+//! retention of all past runs.
+//!
+//! WorkerHandle is owned internally; external operations take WorkerRef. Socket/session paths,
+//! Manifests, credentials, and handles are not passed to browser/API projections.
 
 use std::collections::{BTreeMap, HashMap};
 use std::future::Future;

crates/worker-runtime/src/working_directory.rs

@@ -1,3 +1,20 @@
+//! Ownership of Runtime-local repository materialization and session resources.
+//!
+//! Independently of Backend inventory, Runtime checks duplicate primary Workdir ownership and
+//! current bindings. Usability depends on materialization identity, current state, and occupancy,
+//! not creation provenance alone. Per-target provider leases exclude competing creation, access,
+//! and cleanup; the admission bookkeeping mutex is not held during filesystem work.
+//! Fresh roots are created exclusively; failures do not delete another creator's tree.
+//!
+//! Binding clones are passive; only activating session resources inhibits cleanup.
+//! Resource clones held by sessions and commands maintain that protection. Deletion invalidates
+//! the materialization generation, so recreating the same ID cannot activate old bindings.
+//!
+//! Deletion is a provider operation checking current identity, mounts, and remaining content.
+//! Partial-deletion witnesses are stored outside the tree. CleanupPending/unknown inventory status
+//! does not guarantee current cleanliness. Detailed inspection and remaining-content checks
+//! are limited to cleanup retries.
+
 use crate::catalog::{
     MaterializerKind, RepositoryRefObservation, RepositoryRefObservationRequest,
     RepositorySshMaterializationAccess, WorkingDirectoryCleanupTarget,

crates/worker-runtime/src/working_directory/cleanup.rs

@@ -1,8 +1,14 @@
-//! Ordinary removal authority, not a recovery lifecycle. The content witness is
-//! outside the tree being removed so a crash/partial unlink cannot erase it.
-//! Every retry checks current identities, mounts and remaining content. Missing
-//! entries are expected after partial deletion. The same intact clean checkout
-//! may renew its witness after owner recovery, never discarding new ignored content.
+//! Mount-safe deletion and content checks after partial deletion.
+//!
+//! Content witnesses are stored outside the deletion tree, surviving partial unlinking.
+//! Witnesses describe past facts; every retry revalidates current identity, mounts, and remaining
+//! content. Missing entries count as partial deletion, but new or changed content is not discarded.
+//! Only the same intact clean checkout can refresh an old witness. List/detail check saved identity
+//! only; they infer neither remaining file hashes nor current cleanliness.
+//!
+//! Rejects deletion if Linux openat2 or /proc mount checks are unavailable; no unchecked recursive
+//! deletion fallback. Does not implicitly unmount resources or delete other owners' data.
+//! OS errors stay in Runtime-private logs; public diagnostics contain only closed causes and safe messages.
 use super::*;
 use std::io;
 

crates/worker-runtime/src/workspace_issuer.rs

@@ -1,3 +1,14 @@
+//! Runtime request authentication through explicitly registered Workspace issuers.
+//!
+//! Matches actual HTTP method, path/query, body digest, operation, Runtime audience, Workspace/Worker
+//! scope, expiry, and single-use token ID against signed claims. Ping is an ordinary signed request;
+//! prior handshakes or saved connection tests do not authorize it. No fallback to self-reported
+//! public keys, Server-global trust, or static bearers.
+//!
+//! Trust IDs are administrative, not namespaces for sender claims. Replay tracking uses Workspace
+//! and trusted key fingerprints, so re-registering or rotating the same key cannot revive consumed
+//! requests. This does not guarantee invalidation of unconsumed, unexpired requests from a reaccepted key.
+
 use std::collections::HashMap;
 use std::fmt;
 use std::fs;

crates/worker-runtime/src/workspace_request.rs

@@ -1,3 +1,10 @@
+//! Runtime-originated HTTP requests bound to Workspace boundaries.
+//!
+//! Signs the actual request method/path/body with Runtime identity, using the Backend URL from
+//! an explicit Workspace issuer bundle as audience. Connection hints alone do not create
+//! Account/Worker authority. Reads bounded responses with an async client; no blocking HTTP
+//! clients on async Worker/runtime paths.
+
 use std::error::Error as _;
 use std::io::Read;
 use std::time::{Duration, SystemTime, UNIX_EPOCH};