fix(drivers): 聚合函数拒收带上 ADR-0112 信封,并把两类条件分开措辞 (#5907)

[os-zhuang]

Fixes #5907

前提复核(先证后改)

在 origin/main @ 80f7dc6a3 双面实测,两处裸 Error 都还在(行号已漂到 sql-driver.ts:7071 / remote-transport.ts:726,与派发一致),两类输入的现行为如下:

REMOTE median          -> THREW code=undefined status=undefined msg="Unsupported aggregate function: median"
LOCAL  median          -> THREW code=undefined status=undefined msg="Unsupported aggregate function: median"
REMOTE count_distinct  -> THREW code=undefined status=undefined msg="Unsupported aggregate function: count_distinct"
LOCAL  count_distinct  -> THREW code=undefined status=undefined msg="Unsupported aggregate function: count_distinct"
REMOTE array_agg       -> THREW code=undefined status=undefined msg="Unsupported aggregate function: array_agg"
LOCAL  array_agg       -> THREW code=undefined status=undefined msg="Unsupported aggregate function: array_agg"
REMOTE string_agg      -> THREW code=undefined status=undefined msg="Unsupported aggregate function: string_agg"
LOCAL  string_agg      -> THREW code=undefined status=undefined msg="Unsupported aggregate function: string_agg"
REMOTE count           -> RESOLVED  SELECT count("stage") AS "n" FROM "deal"
LOCAL  count           -> RESOLVED  [{"n":0}]

前提成立,两类今天确实同一句话,code/status 皆 undefined。

改了什么

两面同改,同一信封体例、首句逐字一致(#5240),体例取 PR #5921(invalidFilterError 形态):

条件	code / status	首句
第 1 类:协议未声明的函数名(median)	INVALID_QUERY / 400	Aggregate function "median" is not a declared aggregate function.
第 2 类:协议已声明、本后端编不出(count_distinct / array_agg / string_agg)	NOT_IMPLEMENTED / 501	Aggregate function "count_distinct" is declared but not implemented by this backend.

• packages/drivers/driver-sql/src/sql-driver.ts —— mapAggregateFunc 的 switch 换成一张降级表(SQL_AGGREGATE_FUNCTIONS),拒收消息里的「本面编得出什么」从这张表读,不再手抄一份(driver-memory 的 analytics 面静默丢弃大半个 filter:$or/$not 整条丢,$between/$startsWith/$null/$regex 因无 cube 映射而丢 —— 聚合结果被放大 #5345 的教训);
• packages/drivers/driver-turso/src/remote-transport.ts —— 同形的孪生实现。该文件刻意不依赖 knex / SqlDriver(见文件头),所以是孪生而非共享导入,与 driver-sql ↔ driver-memory 既有的 unsupportedFilterError / filterArrayReachedDriverError 孪生先例一致。

「已声明」的集合从 @objectstack/spec 的 AggregationFunction 读,不在驱动里复述。

第 2 类为什么选 NOT_IMPLEMENTED / 501(裁决要求说明理由)

目录里四个候选,按既有语义与 status 映射实测比较:

候选	归属	仓内既有语义 / status	判定
NOT_IMPLEMENTED	标准目录(StandardErrorCode)	注释即「Feature not yet implemented」;HttpStatusErrorCodeMap[501] 就是它;仓内 20+ 处 501 + 「not supported by this protocol/runtime」	选它
UNSUPPORTED	扩展账本(runtime / plugin-sharing)	两处发射点都是 400「这个分享链接不暴露消息」——资源配置不暴露,语义已被占	否
UNSUPPORTED_QUERY_PARAM	扩展账本(metadata-protocol)	400,且在 isExpectedQueryRejection 的「调用方点错参数名」清单上	否,方向相反
UNSUPPORTED_TRANSFORM	扩展账本(@objectstack/rest)	导入映射器的 transform,领域不符	否

另两条支撑:账本自己的规矩是「条件通用就用标准目录,不要注册同义词」,而驱动包今天在账本里没有条目(注册反而要新开一行);标准目录 + HttpStatusErrorCodeMap 让 code 与 status 互为镜像,不是本函数自己挑的。

第 1 类的 INVALID_QUERY 同理不是新拼法:协议门对同一条件已经在给这个码 —— metadata-protocol 的 invalidQueryError 对「aggregations 轴上一个枚举外的 function」refuse 的就是 400 INVALID_QUERY(#4254)。于是进程内调用方与 REST 调用方读到同一个答案。

一处被迫做的判断:按调用方写的原始拼写分类

两面的归一化本来就不一样(remote 先 .toLowerCase(),local 不动),实测:

COUNT           REMOTE -> RESOLVED "SELECT count(...)"        LOCAL -> THREW
COUNT_DISTINCT  REMOTE -> THREW "…: count_distinct"           LOCAL -> THREW "…: COUNT_DISTINCT"

若各面按自己归一化之后的名字分类,COUNT_DISTINCT 会在 remote 拿 501、在 local 拿 400 —— 一条今天两面答案一致的输入,被本 PR 劈成新的叉,正是本单要关的东西。所以分类一律判调用方写的那串字节对 AggregationFunction(大小写敏感的 z.enum)的成员关系:任何规范拼写两面完全一致;任何错误大小写两面都落第 1 类。归一化差异本身(COUNT 在 remote 编得出)未触碰,如实钉在用例里并另立 #6203。

测试

新增两个文件,进两包既有拒收族(命名沿用各自族的惯例):

• packages/drivers/driver-sql/src/sql-driver-out-of-contract-aggregate-function.test.ts —— 14 例
• packages/drivers/driver-turso/src/remote-transport-aggregate-function-refusal.test.ts —— 16 例,含 4 条跨包 parity 用例:比对 SqlDriver 与 RemoteTransport 两个运行时消息(不是两份字面量),这半边只改一个包是满足不了的。

⚠️ 每一例都断言 code 与 status,不只断言「它抛了」——未修驱动本来就抛(见上方实测),只断言抛出的用例会恒绿、对本缺陷完全失明(#6144)。

反向验证(方向先判后跑),两个方向都测了

预判:未修驱动对这些输入本来就抛,所以还原裸 Error 后,每条拒收用例应当挂在第一条断言(err.code → undefined),没有一条该走 refusalOf 的「它居然 resolved」分支;控制组保持绿。

实测:

1. 两面同时还原 —— driver-sql 10 failed / 4 passed(共 14),driver-turso 8 failed / 8 passed(共 16)。全部挂在 expected undefined to be 'INVALID_QUERY' / 'NOT_IMPLEMENTED',无一条挂在「resolved」,与预判一致。
   但预判有一半错了,如实记下:4 条 parity 用例这时是绿的 —— 两面都匿名,就都在 undefined/undefined 上「一致」。parity 测的是一致性,不是正确性。
2. 只还原一面 —— 最初是踩到 @objectstack/driver-sql 的陈旧 dist/ 意外测到的(本包源码已修、依赖包是旧的):4 条 parity 用例以 expected 'NOT_IMPLEMENTED' to be undefined 全红。

(2) 才是这个文件存在的方向:本单防的不是「某一面沉默」,而是「两面对同一条查询给不同答案」,所以必须变红的是单面改动。两条测量都写进了测试文件的 docblock。

命令与结果

pnpm --workspace-concurrency=2 --filter '@objectstack/driver-sql' --filter '@objectstack/driver-turso' typecheck
  driver-sql typecheck: Done / driver-turso typecheck: Done

driver-sql   全量  Test Files 66 passed | 4 skipped (70)   Tests 920 passed | 46 skipped (966)
driver-turso 全量  Test Files 25 passed (25)               Tests 804 passed (804)
driver-sqlite-wasm 全量(继承 mapAggregateFunc) Test Files 18 passed (18) Tests 254 passed (254)

check:error-code-casing / check:route-envelope / check:driver-conformance /
check:empty-changeset / check:adr-anchors / check:doc-authoring / check:nul-bytes  全绿

消费半径已扫:全仓没有任何测试同时构造 SQL 驱动与这三个函数;Unsupported aggregate function 的旧措辞除本 PR 新增文件外只出现在两处文档,已一并订正(不是 content/docs/releases/)。

边界

• ⛔ spec 半边不夹带:那三个「声明了无 SQL 实现」的函数按 ADR-0049 的去留归 [spec] AggregationFunction 声明 8 个,SQL 族只实现 5 个 —— count_distinct / array_agg / string_agg 按 ADR-0049 enforce-or-remove 定去留 #6188,query.zod.ts 一字未动;第 2 类的消息把这条路指过去。
• ⛔ 未触 fix(driver-turso): RemoteTransport 拒收条件层的 $-算子键 —— 不再编译成静默空集/全表写 (#5769) #5921 的条件层拒收闸、fix(driver-turso): remote 模式对齐 NULL-safe 语义 —— $not/$ne/$nin/$notContains 四算子 + $exists 拒收闸 (#5903) #6047/fix(drivers): undefined 比较数一律拒收 —— 闸落在任何发射器/守卫之前,两个毛病同闸消灭 (#6050) #6142 的 NULL/undefined 闸。
• 与 [finding][drivers] 五个驱动的 find/count/… 仍声明 query: QueryAST，而调用方已可省略 object —— 双变让它编译，但声明开始说谎 #6075 零重叠(签名区 vs 聚合区)。
• 实测后果,写在 uncompilableAggregateFunctionError 的 docblock 里,免得被当成驱动 bug 重查:/data 路由上 mapDataError 的状态直通只覆盖 4xx,所以这条声明的 501 到不了线上,会落到 UNCLASSIFIED_FAULT 的 500 INTERNAL_ERROR(连 code 一起被覆写)。那是 REST 边界的缺口 mapDataError 的显式状态直通只覆盖 4xx,数据路由上一个声明了 502/503 的生产者拿不回自己的状态码(与 resolveErrorResponse 不对等) #5582 —— 本 PR 是它的第一个活体生产者,已在该单补上证据;驱动侧该做的(在抛出点如实声明,ADR-0112)已经做完。

顺带记录的发现(未在本 PR 修)

• mapDataError 的显式状态直通只覆盖 4xx,数据路由上一个声明了 502/503 的生产者拿不回自己的状态码(与 resolveErrorResponse 不对等) #5582(既有单,已评论补证):mapDataError 4xx-only 直通把本 PR 的 501 压成 500 INTERNAL_ERROR,连语义码一起丢;该单原本自评为观察类「没测到活体生产者」,现在有了。
• drivers(turso): 聚合函数名的大小写归一化 local/remote 不一致 —— COUNT 在 remote 编得出、在 local 被拒(同一个 TursoDriver,取决于 url) #6203(新开,finding):聚合函数名大小写归一化两面不一致 —— COUNT 在 remote 编得出、在 local 被拒。仓内无活体发送方、协议门也表达不出该输入,故记为观察类,严重度请分诊判定。

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01WyvqvKMG6asi9aXjKE6xtx

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 7, 2026 11:04am

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/driver-sql, @objectstack/driver-turso.

12 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via @objectstack/driver-sql, @objectstack/driver-turso)
• content/docs/deployment/cli.mdx (via @objectstack/driver-turso)
• content/docs/deployment/environment-variables.mdx (via @objectstack/driver-turso)
• content/docs/deployment/self-hosting.mdx (via @objectstack/driver-turso)
• content/docs/getting-started/glossary.mdx (via @objectstack/driver-sql, @objectstack/driver-turso)
• content/docs/kernel/services-checklist.mdx (via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx (via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx (via @objectstack/driver-sql, @objectstack/driver-turso)
• content/docs/protocol/kernel/index.mdx (via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx (via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx (via @objectstack/driver-sql)
• content/docs/releases/implementation-status.mdx (via @objectstack/driver-sql)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.