[spec] 声明 FilterArray 为仅输入的授权糖(#5158 拍板 C 第 1 步,拆单移交 spec 车道)

Part of #5158(维护者 2026-08-04 15:22Z 拍板 C:单一下沉缝;本单是其唯一阻塞前置,engine 半边在本单落地前无法开工)。

要做什么(#5158 裁决第 1 步原文范围)

在 packages/spec 正式声明 FilterArray 为仅输入的授权形状(React props / FilterBuilder / wire $filter 面的授权糖),消灭「有名无定义」状态 —— 今天它被四份已发布契约教作者写(README×3、llms.txt、skills×4、spec TSDoc×4、query-adapter,见 #5158 侦察清点),协议层却从未声明,是 AI 作者的纯陷阱。

要点(依据 #5158 的侦察评论与裁决评论,执行前全文重读):

声明为仅输入:FilterArray 获得正式的 spec 定义,语义 = 授权入口收到后经 parseFilterAST 下沉为 FilterCondition;BaseQuerySchema.where 的存储/协议形状不变(不接纳数组方言进 wire 契约 —— 那是被否掉的选项 A);
TSDoc/describe 写明「仅输入、下沉单点」语义与下沉函数指向;
配套 pin 测试:声明存在、形状正确、且不进入 where 的 union(防止未来有人顺手把它扩进协议面);
spec 生成基线按 os-regen 纪律整体重生成;changeset(spec minor,理由:新增导出类型)。

⛔ 不动 engine(engine.ts:4309 Door 2)、不动四驱动、不退役 engine-findone-contract pin —— 那是 #5158 第 2 步,engine 车道(session_01Pbu27iNUfQCHeuS551Rqo7)在本单落地后接手。

关联

#5158(裁决 C 全文 + 侦察清点数据)、cloud#1075 / cloud PR #1080(分叉现场)、ADR-0053 D-A1。

spec 车道 PM session_01ErbEDVAg1No9gdg1pgDAGB 按跨分片移交协议立单;维护者已列为高优先(同时卡 engine 车道)。

认领:PM 循环第 2 批补位(spec 车道,batch:5;A3 —— 同时卡 engine 车道第 2 步)
会话:session_01ErbEDVAg1No9gdg1pgDAGB
分支:claude/issue-5285-filterarray-input-only
Worktree:objectstack-issue-5285
域:domain:spec
文件面:packages/spec/src/ 查询/过滤相关 zod 文件(FilterArray 声明落点,以实测为准并在 PR 里写明)、配套 pin 测试、spec 生成基线(与同批 #5015/#4938/#5235/#5271 生成物重叠,os-regen 四步互保)、.changeset/*.md。⛔ 不动 BaseQuerySchema.where 的协议形状、不动 engine/驱动。

执行依据:#5158 维护者拍板 C(2026-08-04 15:22Z)第 1 步;侦察清点数据见 #5158 评论。

Generated by Claude Code

验收:ACCEPT(PM 复核毕,PR #5306)

复核依据(GitHub 实据):

落点与派生正确:声明落 data/filter.zod.ts(算子词表、结构判定、下沉函数同文件,派生不复述);FilterArrayOperator = keyof typeof AST_OPERATOR_MAP(satisfies 保字面量键集,A filter with an operator outside VALID_AST_OPERATORS is silently dropped, not rejected — single-condition views return unfiltered results #3948 教训),行为零变化由六个消费包全量测试作证(driver-sql 729 / objectql 1868 / protocol 376 等);
形状三权威互证(isFilterAST / FilterBuilder 16 方法 / lint filterFieldRefs),大小写不敏感由存量 view 元数据实测定调 —— 无歧义,无需升级;
负向 pin 承重:where 与 FilterCondition 双层拒收数组方言、下沉后接受 —— 未来任何「顺手放宽」直接红并指回 [engine] driver-sql 编译 spec 未声明的「数组 where 方言」—— 与 Turso remote 的拒收分叉,需一次定调(接纳进 spec 或响亮弃用) #5158 裁决;授权门与运行时判定的两处刻意差异逐条钉住;
反向验证的失败被如实报告:首轮预测失败牵出 spec 测试层类型断言惰性问题,解除排除后方向吻合(唯一 TS2578 正是本声明的收窄);类型块在文件内显式标注「CI 不检查」附手工复现 —— 不伪造证据,正确;
6 文件对账吻合,changeset minor 合理,post-merge(main 已动)复测通过。

后续:PR #5306 排在落地串行链第 5 位(#5289 已入队 → #5293 → #5300 → #5304 → 本单),轮到时同步重生成后入队;落地即在 #5158 知会 engine 车道接第 2 步。dev 顺手立的 #5305 与 #5286 为同一缺陷(两个 dev 同日独立发现,后者已带处置 A 入队)—— PM 按跨报告查重职责合并,#5305 关 duplicate,其 17 处清单并入 #5286。

Generated by Claude Code

chore(spec): regenerate os-regen artifacts against main @ 04fab5e (#5285

feat(spec): 声明 `FilterArray` 为仅输入的授权糖(objectstack-ai#5158 拍板 C 第 1 步) (…

fix(objectql,driver-sql,driver-memory,driver-mongodb)!: `FilterArray`…

fix(service-analytics): lower a `where` FilterArray instead of droppi…

test(objectql): type the new #5869 call sites instead of erasing them…

Navigation Menu

Repository navigation

[spec] 声明 `FilterArray` 为仅输入的授权糖(#5158 拍板 C 第 1 步,拆单移交 spec 车道) #5285

要做什么(#5158 裁决第 1 步原文范围)

关联

验收:ACCEPT(PM 复核毕,PR #5306)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[spec] 声明 FilterArray 为仅输入的授权糖(#5158 拍板 C 第 1 步,拆单移交 spec 车道) #5285

Description

要做什么(#5158 裁决第 1 步原文范围)

关联

Activity

os-zhuang commented on Aug 4, 2026

os-zhuang commented on Aug 4, 2026

验收:ACCEPT(PM 复核毕,PR #5306)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

[spec] 声明 `FilterArray` 为仅输入的授权糖(#5158 拍板 C 第 1 步,拆单移交 spec 车道) #5285