docs: clarify API request phases and native input ordering

src/runtime/api.rs

@@ -5,6 +5,9 @@
 //! main::main 调用 start，shell 持有 RuntimeControl；HTTP 请求经 handle/submit 入队，原生输入经 dispatch_native 入同一队列。
 //! worker 子模块拥有实际 ReplSession；本文件的线程循环只决定继续哪个请求、何时等待、如何响应和退出。
 //! 本地端点、观察器和 EventLoopProxy 都是 Tessera 宿主适配，不能把整个文件直接作为无 GUI 的 Nexus 核心。
+//!
+//! 成功入队仅表示接受执行请求，最终回执由 worker 完成或明确拒绝后发出；它与发布 revision 并非同一事件。
+//! 普通请求队列和退出通道相互独立，pending 保存原请求与继续状态；退出优先于下一量子，但不由 HTTP 线程抢先操作 VM。
 mod guide;
 mod worker;
 
@@ -298,6 +301,7 @@ fn start_server_observed(
                         current.document.frame.session = 0;
                         current.document.frame.focus = None;
                         for view in current.document.windows.values_mut() {
+                            // 共享 VM 已清理，每个副窗保留画面都必须撤销交互会话和焦点，避免退出期间仍向旧目标投递输入。
                             view.frame.session = 0;
                             view.frame.focus = None;
                         }
@@ -376,6 +380,7 @@ fn start_server_observed(
                             worker.repl = None;
                         }
                         if wait.is_zero() {
+                            // 活跃续体/协程采用零接收超时；此处仅让出线程调度机会，下一循环仍先检查退出并推进原 VM。
                             thread::yield_now();
                         }
                     }
@@ -748,6 +753,7 @@ fn submit(
     }
     // 仅完整 Code 请求分配新 submission，事件/REPL/表达式继承当前身份，保留共享域输入顺序。
     let submission = match if kind == RequestKind::Code {
+        // 先计算候选接受号而不改 current.submission；只有下面 try_send 成功才让旧提交失去发布资格。
         current.next_submission()
     } else {
         Ok(current.submission)
@@ -831,6 +837,7 @@ fn read_code(request: &mut Request) -> Result<String> {
         .read_to_string(&mut code)
         .context("read code")?;
     if code.len() as u64 > MAX_CODE_SIZE {
+        // code.len() 是 UTF-8 字节数，流读取上限多留一个字节用于探测，不能以字符数替代 1 MiB 源码预算。
         anyhow::bail!("code exceeds the 1 MiB limit");
     }
     Ok(code)