Skip to content

DriverCapabilities.streaming 在 findStream 退休后指向不存在的能力,且从来没有读者(ADR-0049,#4484 收尾发现) #4634

Description

@os-zhuang

#4484(退休 IDataDriver.findStream)时闭合调用图,发现能力标志 DriverCapabilities.streaming 是同一处死声明的另一半,单独留下会比原来更糟。未在 #4484 里一并处理,是因为它的爆炸半径不同(每个 driver 的能力字面量,含三方 driver),值得单独定夺。

位置

packages/spec/src/data/driver.zod.ts:273-276

  /**
   * Whether the driver supports streaming large result sets.
   */
  streaming: z.boolean().default(false).describe('Supports result streaming (cursors/iterators)'),

证据

  1. 零读者。 全仓(framework + cloud,排除 node_modules / dist)没有任何一处读 supports.streaming / capabilities.streaming。命中全部是
packages/plugins/driver-memory/src/memory-driver.ts:202     streaming: true,   // 注释原文曾是 "Implemented via findStream()"
packages/plugins/driver-mongodb/src/mongodb-driver.ts:115   streaming: true,
packages/plugins/driver-sql/src/sql-driver.ts:552           streaming: false,
packages/spec/src/api/registry.example.ts:219               streaming: false,
packages/core/API_REGISTRY.md:306                           streaming: false,

没有查询规划、没有能力协商、没有 REST discovery 字段读它。它是纯粹写进去就再没人看的一位。

  1. 写进去的值本身就是错的,而且没人发现——这正是零读者的直接后果:SqlDriver 声明 streaming: false 却实现了 findStreamInMemoryDriver 声明 streaming: true,实现却是 await this.find() 之后再逐条 yield(把整表读进内存,恰好是 streaming 的反面)。三个 driver 里只有 mongo 的 true 是名副其实的,而它现在也随 IDataDriver.findStream 没有任何调用方,两个 driver 的实现还正好做了它承诺要避免的事(ADR-0049 enforce-or-remove) #4484 一起删掉了。

  2. IDataDriver.findStream 没有任何调用方,两个 driver 的实现还正好做了它承诺要避免的事(ADR-0049 enforce-or-remove) #4484 之后它指向空。 findStream 是这个标志唯一可能描述的东西(memory driver 的注释直说了 // Implemented via findStream())。契约方法删掉后,streaming: true 描述的是一个平台不再声明的能力——下一个读到它的人(或 agent)会据此推断存在一条流式读路径,这正是 IDataDriver.findStream 没有任何调用方,两个 driver 的实现还正好做了它承诺要避免的事(ADR-0049 enforce-or-remove) #4484 要消除的假可供性,只是往上挪了一层。

处置倾向

remove,理由与 #4484 同源。真要做流式读,路径是"先有调用方,再有契约方法,再有描述它的能力位",而不是留一个描述空洞的布尔。

需要先定夺的是范围:DriverCapabilitiesSchema 有近 30 个位,streaming 未必是唯一一个零读者的(queryCachepreparedStatementsvectorSearchgeospatialQuery 值得一并查)。两条路:

  1. 只删 streaming——干净、与 IDataDriver.findStream 没有任何调用方,两个 driver 的实现还正好做了它承诺要避免的事(ADR-0049 enforce-or-remove) #4484 同源、当天可完成;代价是同一份审计要再做一遍。
  2. 对整个 DriverCapabilities 做一次活性审计,按 ADR-0049 一次性处置所有零读者的位;代价是范围大得多,且要处理三方 driver 的能力字面量(删一个 key 会让写它的对象字面量报 excess-property 错误)。

我倾向 先做 2 的审计、再按结果一次性 remove:逐位退休会让每个 driver 作者被迫改三四次能力字面量,而一次审计只改一次。

相关

未指派 —— 按 AGENTS.md 的约定,这是一条记录下来的 finding,谁开工谁认领。

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions