docs(architecture): clarify storage pass-through mode

docs/architecture/performance-principles.md

@@ -133,6 +133,7 @@ Main 负责窗口、生命周期、权限和消息转发。数据库查询、文
 - 重查询复用有界 Worker；必要写入不排在整个导入解析或模型请求之后。长事务先减少事务内无关计算，再测写入排队，不把阻塞简单搬进唯一存储队列。
 - 复用现有池、批处理和队列，记录在途数、排队数及实际资源使用。只有有明确依据时才设置容量；没有依据时将负载交给所属 Host，不因内部数字拒绝用户工作。有实测饥饿才引入最小调度调整，不预建通用优先级框架。
 - 控制和取消不等待新的执行槽位；如果外部或用户设置要求排队，按该语义执行。禁止静默丢失、无限重启或自动扩增进程；不能把未经证明的队列上限包装成稳定性。
+- `ReadonlyQueryReader` 的生产 storage 模式不传 `maxPending`，因此请求直接透传给 storage host；其等待队列只服务显式有界的调用方和测试，不构成第二个 storage owner。
 - 每个异步响应携带已有项目／会话／任务／操作归属；迟到响应不得覆盖新选择或新操作。归属检查先于改变共享请求代次、缓存或队列状态。
 
 ### P12 架构完整性与 KISS

docs/development/agent-feature-maintenance.md

@@ -136,6 +136,12 @@ write 也必须服从当前实现与测试。修改前先确认代码中的常
 Worker 发生故障时可以进入已有退避和恢复流程；这不应被伪装成负载上限。正常排队的
 解析、存储和 Host 工作不能因为一个未经测量的队列数字直接返回 busy。
 
+`ReadonlyQueryReader` 同时服务只读 Worker 和桌面 storage client。只有调用方显式传入
+`maxPending` 时，`waiting` 队列才承担有界等待语义；生产 storage client 不传该选项，
+请求直接交给 storage host。这个共享类不是第二个 storage owner，不能因为看到等待队列
+就给生产路径恢复默认 admission 上限。若未来实测证明某个边界需要容量策略，应先说明
+资源、故障和测量依据，再拆出最小的显式 wrapper 或增加调用方配置。
+
 ## 测试与真实验证
 
 单元测试用于确定字节边界、事务回滚、顺序、归属、取消竞态、失败清理和重试。行为改动

src/main/readonly-query-reader.ts

@@ -43,7 +43,11 @@ type Waiting = { start: () => void; cancel: () => void; fail: (error: Error) =>
 export type QueryTransport = Pick<EventEmitter, 'on' | 'once'> & Pick<Worker, 'postMessage' | 'ref' | 'unref' | 'terminate'>
 export interface QueryTransportOptions {
   createTransport: () => QueryTransport
-  /** Optional test or caller policy; production storage leaves this unset. */
+  /**
+   * Optional caller policy. Production desktop storage leaves this unset so
+   * requests pass through to the storage host; the waiting queue is only for
+   * explicit bounded readers and tests.
+   */
   maxPending?: number
 }
 
@@ -83,6 +87,9 @@ export class ReadonlyQueryReader {
     private readonly transportOptions?: QueryTransportOptions
   ) {}
 
+  // This class correlates requests for both read workers and storage. The
+  // storage client intentionally uses the unbounded pass-through mode; it does
+  // not create a second storage owner or impose a product capacity limit.
   private get maxPending(): number { return this.transportOptions?.maxPending ?? DEFAULT_MAX_PENDING }
 
   /** False while backing off after a crash or startup failure. */