[spec] AggregationFunction 声明 8 个,SQL 族只实现 5 个 —— count_distinct / array_agg / string_agg 按 ADR-0049 enforce-or-remove 定去留

[os-zhuang]

从 #5907 分流而来(分诊 2026-08-06 明确:运行时说实话归 drivers 车道、声明面去留归 spec 座位,⛔ 不夹带)。

事实

packages/spec/src/data/query.zod.ts:108 的 AggregationFunction 声明 8 个:

'count', 'sum', 'avg', 'min', 'max', 'count_distinct', 'array_agg', 'string_agg'

后 3 个 —— count_distinct / array_agg / string_agg —— 没有任何 SQL 后端编译:SqlDriver.mapAggregateFunc(sql-driver.ts:7071 附近)与 RemoteTransport.aggregate(remote-transport.ts:726 附近)各自只编译前 5 个,后 3 个落同一句拒绝。非 SQL 族里 driver-mongodb(mongodb-aggregation.ts:139/144/147)与 driver-memory(memory-analytics.ts:866,count_distinct)实现了其中若干,且各后端实现的子集互不相同。

即 declared ≠ enforced,且「哪个后端能算什么」对作者不可预测。

需要一次裁决(spec 座位)

• A 保留声明:承认它是「部分后端支持」的能力面,则需要一个作者可查的能力矩阵(哪些后端支持哪些聚合),否则作者只能靠试;
• B 按 ADR-0049 摘除:三个键从 AggregationFunction 退役(走 ADR-0087 墓碑与生成物流程),已实现它们的 mongodb/memory 侧按各自冻结/退役状态处置;
• C 保留但标注实验/后端限定:需要 spec 侧有表达「按后端可用性」的位,{ field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240 曾拒绝为共享表临时发明例外位,此路需先设计。

drivers 侧的运行时半边(让第 2 类拿到能力缺口信封而不是被说成打错字)在 #5907 独立进行,不阻塞本单;本单的结论反过来会决定 #5907 那条措辞将来是长期存在还是随退役消失。

关联:#5907(运行时半边)、#5345(driver-memory 上同构的「协议没有」vs「本面降不下去」分线先例)、ADR-0049 enforce-or-remove、ADR-0087。

[claude]

Findings triage round (#4949 discipline): PROMOTED out of finding — to the decision inbox, not to the queue. finding removed; needs-user-decision + domain:spec + target:v17 applied.

This issue was filed 10:04Z carrying finding and no domain:* — invisible to every lane until routed. Routing it is the substantive act here.

Routing rationale (landing site)

domain:spec. The declared surface is AggregationFunction at packages/spec/src/data/query.zod.ts:110 (verified on origin/main), and all three options land there: A adds a capability matrix beside it, B retires three enum members from it, C adds a backend-availability bit to it. The driver-side compilers (SqlDriver.mapAggregateFunc, RemoteTransport.aggregate, mongodb-aggregation.ts, memory-analytics.ts) are consumers of that enum — the runtime half is already separately in flight as #5907 (pm:dispatched, domain:drivers, target:v17), and the 2026-08-06 triage split that kept the two apart is respected here.

Why not pm:queue

The three options are mutually exclusive and B — the ADR-0049 default route — would remove a shipped capability: count_distinct is implemented today by driver-mongodb and driver-memory, so retiring the enum members takes working functionality away from two backends. Step 0 names "removing a shipped capability" as needs-user-decision explicitly, and no dev agent can pick among A/B/C without guessing at product appetite. This is not a dead-key retirement the spec-property-retirement playbook can execute unattended — the liveness ledger would not return dead for keys with live implementations.

Why not finding (why it leaves the held state)

A finding is an observation with no user-visible bite today. This one bites today and the bite is documented in the same file: query.zod.ts:78 tells the author "count_distinct: Count unique values (SQL: COUNT(DISTINCT field))" — a promise the SQL backend does not keep. An author copying the schema's own documentation against a SQL backend fails. That is a defect card awaiting a direction, not an observation.

Release board

target:v17 on criterion ② and ④: the authorable schema declares eight aggregation functions and its own prose promises a SQL translation for one that no SQL backend compiles — declared ≠ enforced on shipped spec, and "copy what the docs say, watch it fail" in the first hour. Matches the label its runtime half #5907 already carries.

Stale-premise check

packages/spec/src/data/query.zod.ts has one commit since 2026-08-06 20:00Z (7f713b66, ADR-0122 XParsed naming — unrelated to the enum). The eight-member enum and the three unimplemented members are unchanged on origin/main.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — 2026-08-07. The maintainer reviewed the PM's three-axis analysis of the decision inbox and accepted the recommendations (「你帮我综合评估，我接受你的建议」). Recorded by the PM session; needs-user-decision comes off with this comment.

Decision: split the three keys.

1. array_agg / string_agg — retire from AggregationFunction (ADR-0087 route). Display conveniences with heavy dialect divergence and zero measured pull.
2. count_distinct — keep and enforce: implement in the SQL family (SqlDriver.mapAggregateFunc + RemoteTransport.aggregate). It is a dashboard staple with a trivial SQL lowering (COUNT(DISTINCT x)).

Option C (per-backend capability bits) is rejected — #5240 already refused ad-hoc exception machinery, and after this split it is unnecessary: every remaining declared function is enforced by the SQL family, so declared = enforced without a capability matrix.

Scope notes:

• This card keeps the spec retirement half (2 keys out). The count_distinct SQL implementation is filed as its own card (drivers side) — the declaration stays, enforcement catches up.
• mongodb / memory implementations sit inside the [裁决] driver-memory / driver-mongodb 投入冻结 —— 维护者 2026-08-05 口径（跨单锚点） #5499 freeze — untouched either way.
• drivers(sql,turso): Unsupported aggregate function 两面都是裸 Error(code/status 皆 undefined),且三个 spec 已声明的聚合函数无任何 SQL 后端编译 #5907 (runtime capability-gap envelope wording): once both halves land, the "declared but this backend cannot" message no longer has a subject among these keys — noted there when the retirement merges.

---

Generated by Claude Code