Repository navigation
[spec] AggregationFunction 声明 8 个,SQL 族只实现 5 个 —— count_distinct / array_agg / string_agg 按 ADR-0049 enforce-or-remove 定去留 #6188
Description
从 #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。
Activity
claude commentedon Aug 7, 2026
Findings triage round (#4949 discipline): PROMOTED out of
finding— to the decision inbox, not to the queue.findingremoved;needs-user-decision+domain:spec+target:v17applied.This issue was filed 10:04Z carrying
findingand nodomain:*— invisible to every lane until routed. Routing it is the substantive act here.Routing rationale (landing site)
domain:spec. The declared surface isAggregationFunctionatpackages/spec/src/data/query.zod.ts:110(verified onorigin/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:queueThe three options are mutually exclusive and B — the ADR-0049 default route — would remove a shipped capability:
count_distinctis implemented today bydriver-mongodbanddriver-memory, so retiring the enum members takes working functionality away from two backends. Step 0 names "removing a shipped capability" asneeds-user-decisionexplicitly, and no dev agent can pick among A/B/C without guessing at product appetite. This is not a dead-key retirement thespec-property-retirementplaybook can execute unattended — the liveness ledger would not returndeadfor 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:78tells 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:v17on 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.tshas one commit since 2026-08-06 20:00Z (7f713b66, ADR-0122XParsednaming — unrelated to the enum). The eight-member enum and the three unimplemented members are unchanged onorigin/main.本评论来自分诊座位 Routine(#5474 试点),不构成认领。
Generated by Claude Code
os-project-manager commentedon Aug 7, 2026
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-decisioncomes off with this comment.Decision: split the three keys.
array_agg/string_agg— retire fromAggregationFunction(ADR-0087 route). Display conveniences with heavy dialect divergence and zero measured pull.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:
count_distinctSQL implementation is filed as its own card (drivers side) — the declaration stays, enforcement catches up.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
fix(driver-mongodb): refuse retired array_agg / string_agg instead of…
fix(driver-mongodb): refuse the retired array_agg / string_agg instea…
fix(scripts,spec): doc-authoring Rule 3 reaches refusal prose built i…
fix(spec): the protocol 16 → 17 conversion summaries and three descri…
fix(spec): conformance-case notes and names state each decision in wo…