[engine] driver-sql 编译 spec 未声明的「数组 where 方言」—— 与 Turso remote 的拒收分叉,需一次定调(接纳进 spec 或响亮弃用)

[claude]

在 cloud#1075(PR objectstack-ai/cloud#1080)的事实核对中查实,cloud 侧 dev 按约束不跨仓,由 cloud 分片 PM 代立。

事实

spec 的 BaseQuerySchema.where 声明为 record(FilterConditionSchema),不含数组方言。但 framework driver-sql 实际编译裸 AST 数组:find([['stage','=','won']]) 产出真实过滤(sql-driver-filter-no-silent-drop.test.ts 只对裸三元组抛错,对数组包裹的三元组是编译,[] 被显式钉成「无过滤」)。

即:driver-sql 在执行一种 spec 未声明的 where 方言。cloud Turso remote 模式在 cloud#1075 之后对同样输入响亮拒收(理由:transport 不该复制未声明方言 —— ADR-0053 D-A1 的第二实现问题),于是同一输入本地编译、远程抛错。

需要 framework 侧一次定调

• A. spec 接纳数组方言(声明进 where 的 union)→ 两侧都编译,remote 补实现;
• B. driver-sql 弃用数组方言(带日期的响亮弃用 → 拒收)→ 两侧都拒,消灭未声明方言。

按 declared = enforced 的仓规,B 更顺;但该方言有真实到达记录(filter-no-silent-drop changeset),需要先清点调用方再定。在定调之前,cloud remote 的拒收行为是安全侧的(响亮而非静默全表),不需等待。

Refs: cloud#1075、cloud PR #1080(分歧专节)、ADR-0053 D-A1、sql-driver-filter-no-silent-drop.test.ts。

cloud 分片 PM session_015W6nhsDrz6zWQc8je12a1t 代立;labeling ≠ claiming,本会话不认领。

---

Generated by Claude Code

[os-zhuang]

分诊(PM 循环第 1 轮,会话 session_01Pbu27iNUfQCHeuS551Rqo7):挂 needs-user-decision 上交 —— A(spec 接纳数组方言)/ B(响亮弃用)二选一是公开契约形状定调,且无论取哪边都动 packages/spec(A 改 where 声明,B 需弃用记录),届时归 spec 车道执行。正文两轴分析已足,PM 补一条:B 之前的「清点调用方」是可派的前置侦察(不动契约,只出报告),维护者若先要清单可说一声,本车道即派。在定调前 cloud remote 的响亮拒收是安全侧,不需等待(正文已述)。

---

Generated by Claude Code

[os-zhuang]

清点侦察完成(engine/services 车道 PM 派发,只读;会话 session_01Pbu27iNUfQCHeuS551Rqo7)

对 origin/main @ 1f82d1e2c 全量清点,关键读数:

类别	数量
以数组形式真正到达 SqlDriver.applyFilters 的生产调用方	0
写元组形式、但经 Door 1(parseFilterAST)转换的生产授权点	5 处(showcase 两文件)
制造元组的已发布库	packages/client FilterBuilder,16 处
教数组形式的已发布文档/契约	13 处(README×3、llms.txt、skills×4、spec TSDoc×4、query-adapter)
content/docs/** 提及	0(且 data-api.mdx 明文教反对)
钉住 Turso/RemoteTransport 分叉的测试	0

两个决定性事实:(1) 数组只有两扇门 —— HTTP/协议门(protocol.ts:4533)一律转换或 400,唯一放行数组的是进程内 engine Door 2(engine.ts:4309 明文祝福「expression tree 归 driver 解释」并有 pin 测试);(2) FilterArray 是只有名字没有定义的类型 —— UI 授权面拿它当契约教,协议层从未声明它;同时 TursoDriver 是 SqlDriver 的下游子类,原样继承方言,而 cloud 的 RemoteTransport.buildWhereSQL 响亮拒收 —— 同一产品内部的行为分叉,两侧零测试。

推荐更新:C > B > A(侦察发现的第三选项,PM 按三轴复核后改推):

C. 单一下沉缝:FilterArray 在 spec 里正式声明为仅输入的授权糖(React props / FilterBuilder / wire $filter 面),engine 与协议门一样调用 parseFilterAST 下沉为 FilterCondition —— Door 2 关闭,驱动的数组分支结构性不可达,四个驱动的方言实现随后可无行为变化地删除。

• 长远合理性:唯一让「驱动只说 FilterCondition 一种话」成立的路;A 要每个驱动/transport 永远维护两套编译器,B 要显式撕毁三份已发布契约(filter-no-silent-drop、reject-malformed-filter-array 的保留条款、engine-findone-contract 的 pin)且四驱动必须同步;C 只退役一条 pin,且是刻意的。
• 实际业务需求:授权面人体工学零损失 —— showcase 五处、FilterBuilder 十六处、skill 契约全部原样工作;wire 零变化。
• 防 AI 写错:FilterArray 终于有定义(今天它是纯陷阱:契约教你写、协议不认账);下沉单点 = 单一语义;Turso 分叉随驱动分支删除而消灭。

附注:方言引入者的归因超出本 checkout 的浅克隆窗口(93 commits),需全深度 git log -S "nextJoin" 补;完整清点报告(含 8+5 个测试文件清单、逐调用方迁移难度表)存于本次侦察 transcript,需要可整理成 gist。执行上 C 动 packages/spec(声明 FilterArray)+ engine 下沉调用 + 驱动删除,跨 spec/engine —— 建议 spec 车道牵头声明、engine 车道(本会话)做下沉与删除,contract-first 排序。等维护者拍板。

---

Generated by Claude Code

[os-zhuang]

维护者拍板:取 C(单一下沉缝)

不取 A(spec 接纳数组方言,每个驱动/transport 永远维护两套编译器),不取 B(响亮弃用,要显式撕毁三份已发布契约且四驱动必须同步)。C:FilterArray 在 spec 里正式声明为仅输入的授权糖(React props / FilterBuilder / wire $filter 面),engine 与协议门一样调用 parseFilterAST 下沉为 FilterCondition,Door 2 关闭,驱动的数组分支结构性不可达后无行为变化地删除。needs-user-decision 摘除。

依据即侦察清点的两个决定性事实:以数组形式真正到达 SqlDriver.applyFilters 的生产调用方为 0(所以下沉不损失任何现存行为),而 FilterArray 今天是有名无定义的纯陷阱(UI 授权面拿它当契约教、协议层从未声明它)。C 的授权面人体工学零损失、wire 零变化,同时消灭 TursoDriver-vs-RemoteTransport 的零测试分叉。

执行顺序(contract-first,跨车道)

1. spec 车道(先,阻塞项):在 spec 声明 FilterArray 为仅输入形状 —— 它今天被四份已发布契约教却从未被声明,这一步单独就有价值。这是本单唯一的阻塞前置,engine 半边在它落地前无法开工。
2. engine 车道(本会话,后):engine Door 2(engine.ts:4309)改调 parseFilterAST 下沉;确认驱动数组分支不可达后删除四驱动的方言实现;退役 engine-findone-contract 里那条祝福数组直达驱动的 pin(刻意退役,PR 里写明)。

本车道现在不认领、不挂 pm:dispatched —— 等 spec 半边落地后由本车道接第 2 步。在此之前 cloud remote 的响亮拒收是安全侧,维持不动。

方言引入者的归因仍缺(浅克隆窗口不足,需全深度 git log -S "nextJoin"),非阻塞。

---

Generated by Claude Code

[os-zhuang]

spec 半边已按移交协议立单:#5285(声明 FilterArray 为仅输入授权糖,拍板 C 第 1 步)。spec 车道(会话 session_01ErbEDVAg1No9gdg1pgDAGB)下一空槽即派;落地后 engine 车道可接第 2 步(Door 2 下沉 + 四驱动删除)。建议 engine 侧在本单补一行 Blocked-by: #5285 以便解锁扫描自动回队。

---

Generated by Claude Code