refactor(spec,drivers)!: retire IDataDriver.findStream (#4484) - #4652
Merged
Conversation
…called, and inverted in two of three impls (#4484) `findStream` was a REQUIRED method on the driver contract, documented as the read "optimized for large datasets to avoid memory overflow". Three things were true of it at once: - Nothing called it. Repo-wide, outside the declaration and the three driver implementations, every hit was a test double — and ~20 of those satisfied the required method by throwing `not implemented`. No test ever went red. - `SqlDriver` and `InMemoryDriver` awaited `find()` for the ENTIRE result set and then yielded row by row, so the memory peak it promised to avoid was reached before the first yield. SqlDriver carried a `TODO: Use Knex .stream()`. - `MongoDBDriver._findStream` did stream, but was the one read there never routed through `buildFindOptions`, hardcoding `projection: { _id: 0 }` and silently dropping `query.fields` (the divergence #4459 recorded; subsumed, not fixed). Removed from `IDataDriver` and `DriverInterfaceSchema`, all three implementations deleted, and the ~38 stub lines that existed only to satisfy a required method. Registered as the `data-driver-find-stream-retired` semantic entry on the protocol-17 chain step (ADR-0087 D3) — a TS/API surface, never stored metadata, so no source rewrite and, deliberately, no tombstone: nothing ever `.parse()`d a driver object, so tsc is the only channel that can carry the prescription, and it carries it at the call site. `DriverCapabilities.streaming`, the unread flag whose only referent was this method, is left standing and filed as #4634 — removing it breaks every driver's capability literal, third-party included, and that audit should cover all ~30 flags in one pass. Fixes #4484 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 4 package(s): 111 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
…dStream stub
Two defects found reviewing the retirement against the `spec-property-retirement`
checklist:
- The changeset declared `minor` for all four packages. Removing a REQUIRED
method from a published contract interface is breaking — the skill says
`major` for `@objectstack/spec`, and it is the house convention for every
other `!` spec change in this major (`session-dual-source-c4`,
`notification-dual-source-c3`). The driver packages drop a public method too,
so they go major with it.
- `protocol-batch-atomic.test.ts` still carried a `findStream() { throw new
Error('not implemented'); }` stub. It is typed `any`, so it compiles and is
simply dead — but it is exactly the stub this issue exists to sweep, and
leaving one behind lets the next reader infer the method still exists.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #4484
背景
IDataDriver.findStream是驱动契约上的必需方法，文档承诺它是"面向大数据集优化、避免内存溢出"的读取路径。但三件事同时成立：throw new Error('not implemented')。没有任何测试会因此变红。SqlDriver与InMemoryDriver做的恰好是承诺的反面。 两者都先await find()取回完整结果集，再逐行yield——它承诺要避免的内存峰值，在第一次 yield 之前就已经达到了。SqlDriver里还留着TODO: Use Knex .stream()。MongoDBDriver._findStream确实在流式读取，但它是那里唯一没有走buildFindOptions的读路径，硬编码projection: { _id: 0 }，静默丢弃query.fields（即 fix(objectql,driver-mongodb)!: findOne must say which record it wants, and executes every option it declares (#4419) #4459 记录的分叉；此处一并消解，而非修复）。一个必需的、零调用方的、且在三分之二实现里语义反转的契约方法，正是 ADR-0049「enforce-or-remove」要处理的对象。PM 在 issue 上的裁定是 REMOVE。
改动
IDataDriver（packages/spec/src/contracts/data-driver.ts）与DriverInterfaceSchema（packages/spec/src/data/driver.zod.ts）中移除findStream。SqlDriver、InMemoryDriver、MongoDBDriver._findStream。not implemented抛错）。data-driver-find-stream-retired语义条目（ADR-0087 D3），并同步spec-changes.json、docs/protocol-upgrade-guide.md。data-driver.test.ts/driver.test.ts断言findStream已不在契约与 Schema 上，防止回潮。关于 tombstone
这里刻意不加 tombstone：
findStream是 TS/API 表面，从来不是被存储的元数据——没有任何代码对驱动对象做过.parse()，因此 Zod 的 tombstone 通道无处生效。tsc 是唯一能承载这条禁令的通道，而它在调用点就已经承载了（移除后任何残留调用直接编译失败）。关于
DriverCapabilities.streaming这个从未被读取的能力位、其唯一指涉对象就是本方法，本 PR 保留不动，已单独立 #4634。原因：删掉它会打断每一个驱动的 capability 字面量（含第三方驱动），这类清理应当把全部约 30 个 flag 放在一次审计里做，而不是搭本 PR 的便车。
验证
本地在受影响包上跑
test/typecheck与check:generated，详见 PR 评论中的输出摘录。Generated by Claude Code