docs: consolidate design documentation and standardize crate English

crates/server-api/README.md

@@ -0,0 +1,10 @@
+# server-api
+
+HTTP contract shared by Workspace Server and Rust clients. Owns public DTOs, API declarations, and generated client/server adapters. workspace-server determines persistent resource authorization and state transitions; worker-runtime determines Runtime execution state.
+
+## Contract entry points
+
+- [`ServerApi`] — HTTP operations and transport metadata
+- [`ServerRequestContext`] — Request context passed to Server authentication adapters
+- [`RequestActor`] — Human identity and authentication method
+- [`WorkerRestoreRequest`] / [`WorkerRestoreResult`] — Observation-based Restore intent and result

crates/server-api/src/lib.rs

@@ -1,8 +1,4 @@
-//! Shared Workspace HTTP resource contracts.
-//!
-//! This crate owns transport DTOs exposed by the Workspace Server and consumed
-//! by Rust clients. Runtime-internal projections remain in their owning crates;
-//! callers must explicitly construct these Server-authoritative resources.
+#![doc = include_str!("../README.md")]
 
 use std::collections::BTreeMap;
 
@@ -472,6 +468,17 @@ pub struct WorkspaceWorkerSessionHistoryResponse {
     pub observation: runtime_api::WorkerSessionHistoryAvailability,
 }
 
+/// Shared Workspace HTTP contract. Server/Runtime determine resource authorization and settlement.
+///
+/// # Restore intent and results
+///
+/// Replay keeps the [`WorkerRestoreRequest`] observation token and request ID fixed. The token
+/// identifies a Runtime observation, not a controller command ID or cleanup plan digest. GET
+/// comparisons do not replace admission checks under the Runtime operation lock; conflicts do
+/// not trigger automatic token replacement.
+/// [`WorkerRestoreState`] Accepted means Restore committed, not that the subsequent run succeeded.
+/// Distinguish read-only preflight Rejected, confirmed RolledBack after side effects, and
+/// ReconciliationRequired needing settled-state checks. Response loss does not imply rollback.
 #[api(reqwest, axum, openapi)]
 pub trait ServerApi {
     #[get("/health", status = 200, error_status = 400)]
@@ -3605,6 +3612,11 @@ pub struct ServerRuntimeSource {
     pub worker_id: Option<String>,
 }
 
+/// Request context built by Server authentication adapters, not authority selected via public JSON.
+///
+/// actor and Runtime/Worker sources are middleware verification results; operation services recheck
+/// current registrations, grants, and Accounts as needed. Transport headers are a Server-internal
+/// extension reusing existing authentication, excluded from generated client and OpenAPI inputs.
 #[derive(Clone)]
 pub struct ServerRequestContext {
     pub actor: Option<RequestActor>,
@@ -3685,6 +3697,8 @@ pub struct RequestActor {
     pub auth_method: ActorAuthMethod,
 }
 
+/// user_id identifies a human; account_id identifies the Workspace owner's namespace.
+/// Actor authentication is separate from Workspace resource authorization, checked by resource services.
 impl RequestActor {
     pub fn user(&self) -> AuthenticatedUser {
         AuthenticatedUser {

crates/server-api/src/repository_openapi_typescript.rs

@@ -1,3 +1,18 @@
+//! Converts schemas reachable from canonical OpenAPI operations to TypeScript.
+//!
+//! Unsupported keywords, references, and ambiguous unions cause generation errors: ignoring
+//! them would make types missing Rust constraints appear valid. Only the target operations'
+//! schema closure is validated and emitted; unused domains' schemas are outside the contract.
+//!
+//! Integer bounds are checked against format ranges and JavaScript's safe-number range;
+//! out-of-range or non-integer bounds are rejected. Type markers distinguish narrower ranges,
+//! but are not runtime validators. Mapping all Rust integers to number would hide precision
+//! loss and differing constraints.
+//!
+//! Defaults generated by Schemars from Serde defaults are annotations, not replacements for
+//! referenced types or constraints. required determines omission; schemas determine nullability.
+//! The generator does not fill defaults or make TypeScript types perform Serde normalization.
+
 use std::collections::{BTreeMap, BTreeSet};
 
 use serde_json::{Map, Value};