[Decision] analytics field gate (#20917): an authored cube member whose `sql` is an expression — keep the stand-down, judge its identifiers, refuse it, or retire expressions

[objectstack-fleet]

Ruled: 5921156712 · letter D · 2026-09-30T23:01Z

Filed by the domain:services seat (#6021, session session_01XY5uCwTjZj7884yYtyur4H) as a decision card. #20917's dev left an open_questions entry that triage's direction does not settle: report 5919006124 on #20917, accepted in 5919159814, and escalated by the at-tier review 5919318329. #20917 has closed, so this card is the question's anchor. ⛔ Not a claim.

⚠️ Disclosure discipline (security family). This card and its comments carry no request body, header, field spelling or returned value.

The question

PR #20931 (landed as 1571aedc) judges every member an analytics query names against the caller's readable fields, at the analytics door and before either strategy runs. A member of an authored cube whose sql is an expression (for example a CASE WHEN … or a ratio of aggregates) names no single field the gate can attribute.

• What happens today, pinned: the gate stands down on such a member.
• As a result: an expression that reads a field the caller may not read is still answered on the native-SQL strategy. The ObjectQL strategy refuses expression measures outright.
• The permission rule itself is unchanged for every other position.

This is a permission-boundary question, so it is the maintainer's. Four options follow; the analysis is in Chinese in the next comment.

• A. Keep the stand-down: an authored expression is the cube author's declared derived value, like a formula field.
• B. Judge the expression's identifiers against the object's declared fields, and refuse when any is unreadable.
• C. Refuse an expression member for any caller who cannot read at least one field of the object.
• D. Retire raw expressions in a cube member's sql at the contract (the spec lane), per ADR-0021's "zero raw expressions". A derived value then has to be declared in a form the platform can judge.

Governing text

• security(analytics): the native-SQL strategy answers a query naming a field the caller has no field-level read permission for, where the engine and the ObjectQL strategy refuse 403 #20917 triage 5917636106: "the gate judges the underlying fields a member resolves to, not the cube's alias". It does not address a member that resolves to no single field.
• packages/spec/src/data/analytics.zod.ts: a measure's sql is "SQL expression or field reference", and a dimension's is "SQL expression or column reference".
• ADR-0021 (docs/adr/0021-analytics-dataset-semantic-layer.md), design principle: "Zero raw SQL / zero raw expressions — every escape hatch is at once a hallucination source, an injection risk, and an un-reviewable blob."

---

Generated by Claude Code

[objectstack-fleet]

决策请求 · domain:services seat (#6021) · session_01XY5uCwTjZj7884yYtyur4H · 2026-09-30T21:09Z

⚠️ 披露纪律:本评论只按类别描述,不含任何请求、字段名或返回值。

背景

• security(analytics): the native-SQL strategy answers a query naming a field the caller has no field-level read permission for, where the engine and the ObjectQL strategy refuse 403 #20917(p0 安全)已由 PR fix(service-analytics)!: one field-level read gate at the analytics door, before either strategy (#20917) #20931 落地(1571aedc)。分析层入口现在有一道字段级读取闸:在对象级准入之后、任何策略运行之前,把查询点名的每个成员解析成它读的字段,用安全服务的 getReadableFields 判定;不可读就回引擎原文的 403。
• 有一类成员解析不到单个字段:作者手写 cube 里,sql 是表达式的成员,例如 CASE WHEN …,或两个聚合相除的比率。闸对它放行(已钉死),这是改动前的原状,不是裁决。
• 后果:这类表达式如果读了调用方无权读的字段,原生 SQL 策略照样给出答案;ObjectQL 策略则直接拒绝表达式度量。
• dev 在报告 5919006124 里提了这个分叉,达档复核 5919318329 把它升级。它落在安全与权限边界上,属于人工地板,所以呈给您。

Governing text

• security(analytics): the native-SQL strategy answers a query naming a field the caller has no field-level read permission for, where the engine and the ObjectQL strategy refuse 403 #20917 分诊方向 5917636106:「闸判定成员解析到的底层字段,而不是 cube 的别名」。表达式解析不到单个字段,这句没有覆盖。
• packages/spec/src/data/analytics.zod.ts:度量的 sql 是「SQL expression or field reference」,维度的是「SQL expression or column reference」。契约今天允许表达式。
• ADR-0021(已接受)设计原则:「Zero raw SQL / zero raw expressions」与「Safety enforced by the engine, not the author」。D1 把作者面收窄到 dataset:比率这类派生度量用 derived: { op: 'ratio', of: [...] } 按名字引用其他度量,不写原始表达式。它管的是 dataset,没有明文退役 analytics_cube 成员上的表达式。

前提(每条带复核命令)

• P1 放行已在 main:git grep -n "Anything else is an EXPRESSION" -- packages/services/service-analytics/src/analytics-service.ts。
• P2 契约允许表达式:git grep -n "SQL expression or field reference" -- packages/spec/src/data/analytics.zod.ts。
• P3 仓内用量:git grep -n "CASE WHEN" -- examples/app-showcase/src/data/analytics/showcase.cube.ts。全仓只有一个表达式成员 done_rate,读的是可读字段;sql: '*' 只用于计数,不读字段值。
• P4 结构化替代存在:git grep -n "DerivedMeasureOp" -- packages/spec/src/ui/dataset.zod.ts。dataset 的度量有自带 filter 和 derived 比率,所以 done_rate 可以写成「带筛选的计数 ÷ 计数」。

Q1 作者 cube 里的表达式成员,字段闸怎么对待?

一句话问题: 一个表达式成员可能读到调用方无权读的字段,但闸看不出它读了哪个字段。今天闸放行。要不要改?

选项 × 真实代价:

选项	做什么	客户可感知的后果
A 维持放行	把表达式视为 cube 作者声明的派生值,类似公式字段	零改动。表达式读了隐藏字段时,原生路径静默给出答案
B 解析表达式	在分析层对表达式里的标识符做分词,逐个按字段判定	分析层多出第二个 SQL 解析器;标识符碰巧与隐藏字段同名时会误拒
C 一刀切	调用方在该对象上只要有一个不可读字段,就拒绝所有表达式成员	不碰隐藏字段的表达式也会被拒;受限用户的看板大面积报错
D 契约退役表达式	在 spec 契约层把 cube 成员的 sql 收窄为字段引用;派生值改用 dataset 的 filter 与 derived 声明;done_rate 随之迁移	作者无法再写绕过权限的成员;已有表达式要迁移(仓内一个,云端与客户部署未知)

业务直译:

• A:会计手写的公式单元格照常显示,即使公式引用了他看不到的列。
• B:在报表层再写一个公式解析器,逐个检查引用。
• C:只要你有一列看不到,所有公式单元格都不给你看。
• D:不再允许手写公式,只能从一张「已认证公式」清单里选。

四轴(业务立场):

1. 长远: ADR-0021 已定方向:作者面零原始表达式,安全由引擎保证而不是作者。D 与之一致,在契约层结构性堵住;A 把一个已知例外长期留在权限闸里;B 是在消费端补丁式再解析一次 SQL,违背「单一派生、契约优先」;C 过宽。
2. 业务拉动: 实测拉动为零:仓内唯一的表达式成员读的是可读字段,也没有读隐藏字段的表达式。云端与客户部署的作者 cube 本席读不到。D 的迁移成本在仓内只有一处,而且已有结构化替代。
3. 防 AI 犯错: D 最强:AI 根本写不出绕过权限的成员。B 次之,能响亮拒绝但会误报。A 最弱,AI 写出一个读隐藏字段的表达式,没有任何提示。
4. 不扩散: A 零改动。D 是能力退役,属于「从紧」而非扩张,但要动 spec 契约和一次迁移。B 新增一个解析器。C 新增一条粗粒度规则。

推荐:D;D 落地之前维持 A。 回退是 A。

• 理由以长远轴领起:这就是 ADR-0021 已接受原则在 cube 层的收尾,而且结构化替代已经存在。
• 置信缺口:云端与客户部署里的作者 cube 表达式用量不可读;维度上的 CASE 分桶有没有结构化等价物,未实测。仓内没有这种用法。
• 自检:只看①选 D;②③④ 是否翻转:②零拉动偏向 A 但不翻转(D 本身是收窄);③ 支持 D;④ 在 A 与 D 之间持平。

裁后执行

• 选 D: 本卡转为 spec 车道的退役卡(domain:spec,由分诊定级),带 ADR-0087 处置与 done_rate 迁移。闸在迁移落地前维持 A;退役后,闸的放行分支变成不可达代码,一并删除。
• 选 A: 本卡以「维持现状」关闭,原文写进 analytics.zod.ts 的文档说明。
• 选 B 或 C: 本卡回到本车道,改动闸的实现(service-analytics),钉子按所选选项写。

os-decision-facets

• ① 项目长远合理性:D 在契约层落实 ADR-0021「零原始表达式、安全由引擎保证」,不在分析层再解析 SQL;A 留一个长期例外。
• ② 实际业务拉动:实测零拉动:仓内唯一的表达式成员读可读字段;云端与客户部署不可读。
• ③ 防 AI 犯错:D 让 AI 写不出绕过字段权限的成员;A 下这类成员被静默放行。
• ④ 创业阶段不扩散:D 是能力退役(从紧),不新增门禁;B 新增解析器,C 新增粗粒度规则。
  Prior rulings read: expression,stand-down,formula,raw,cube,field-level → 42 hits; ADR-0021 D1 (the dataset author surface: no raw SQL, derived measures by name — read, does not retire analytics_cube member expressions), ADR-0032 Decision §2, ADR-0058 D8, ADR-0120 D3, ADR-0005 Decision §5, ADR-0030 Decision §6, ADR-0031 Decision §2, ADR-0032 Decision §1 — each other a term match on another subject, none answers Q1; thread: none; repo: objectstack-ai/objectstack
  推荐:Q1 D(落地前维持 A)。自检:只看①选 D;②③④ 是否翻转:否。
  置信缺口:云端与客户部署的作者 cube 表达式用量不可读;维度上的 CASE 分桶有无结构化等价物未实测。

回批一行即可,例如 Q1 D 或 Q1 A。

Release: not applicable — this card was filed as a decision card and was never claimed. The landed code (PR #20931, 1571aedc) keeps the stand-down until the ruling.

---

Generated by Claude Code

[objectstack-fleet]

Ruling: batch #259 item 2 · letter D · maintainer 「同意」 2026-09-30T22:57Z

Director seat, summon #31, session_01PGMD6TRDaZY8Ubyo7Ukm66 (GitHub os-litant; written as objectstack-fleet[bot] via the relay). Batch #259 was presented in the live director chat (four cards; this one item 2, director recommendation D with A held until D lands); the maintainer answered the batch with one word, 「同意」. The seat's analysis 5919778230 reached the same letter; this ruling was derived from axis ① first and the letters coincide.

The ruling

D — retire raw expressions in a cube member's sql at the contract. A cube member's sql admits a field or column reference only (and '*' for a count); a derived value is declared in a form the platform can judge — the dataset form (derived: { op, of: [...] } over named measures, and a filtered count). A stays as the interim: the gate's stand-down on an expression member remains exactly as PR #20931 landed it until the retirement is on main, and then that branch is deleted as unreachable. B (a second SQL parser in the analytics layer) and C (refuse every expression member for a partially restricted caller) not taken.

Readings (this summon, origin/main 013f97d)

• P1 stand-down: packages/services/service-analytics/src/analytics-service.ts:409 ("Anything else is an EXPRESSION the cube's author wrote") — verified.
• P2 contract: packages/spec/src/data/analytics.zod.ts:250 measure sql "SQL expression or field reference"; :305 dimension sql "SQL expression or column reference" — verified.
• P3 in-repo usage: examples/app-showcase/src/data/analytics/showcase.cube.ts:41 done_rate (SUM(CASE WHEN status = 'done' THEN 1 ELSE 0 END) * 100.0 / COUNT(*)) is the only expression member in the tree; git grep -l 'analytics_cube|defineCube|AnalyticsCubeSchema' -- examples packages/apps packages/plugins names that file alone; sql: '*' at :26 is the count — verified.
• P4 structural replacement: packages/spec/src/ui/dataset.zod.ts:136 DerivedMeasureOp = ['ratio', 'sum', 'difference', 'product'], :79 a derived measure combines other measures by name — verified; a measure-level filter on dataset measures — the seat's reading, unverified this summon.
• ADR-0021 docs/adr/0021-analytics-dataset-semantic-layer.md:62, :118 ("Zero raw SQL / zero raw expressions"), :133, :164-167 (derived measures reference other measures by name only) — verified. The ADR governs dataset and does not itself retire analytics_cube member expressions, which is why this ruling exists.
• Prior rulings read: raw expression|zero raw|expression measure|cube member|member.*sql over AGENTS.md docs/adr packages/spec/src → 18 hits; deciding: ADR-0021 (above); the rest are the cube inner-name retirement (ADR-0049, spec(analytics): retire the inner name on cube measures and dimensions; the record key is the identity (2 keys) #20300) and the single-granularity default — term matches on other subjects; thread: 5919778230.

四棱(本裁决新记录)

• ① 长远:D 在契约层落实 ADR-0021「零原始表达式、安全由引擎保证」,不在分析层再解析 SQL;LookML 式的表达式靠成员级授权补,本平台没有也不新建。
• ② 拉动:仓内零拉动(唯一表达式成员读可读字段);云端与客户部署不可读。
• ③ 防错:D 让 AI 写不出绕过字段权限的成员;A 下静默放行。
• ④ 不扩散:D 是能力退役(从紧),不新增门禁。
• 只看①选 D;②③④ 是否翻转:否。

Execution parameters (ruled here; no further decision card)

• Lane / state: this card leaves the decision box to pm:queue in domain:spec (domain:services replaced in the same stroke); security, priority:p1 and area:access stay. The domain:spec seat claims it as a retirement card: level L, mode:cloud or mode:subagent at the seat's call, Clause-②: yes (narrowing) — BREAKING, with the ADR-0087 disposition in the changeset and the full kit of the spec-property-retirement skill (refusal guidance on an expression value naming the dataset form, liveness ledger row, regenerated baselines, docs, pins).
• The shape after: AnalyticsCubeSchema measure and dimension sql admit an identifier (a field or column reference) and '*'; any other value is refused at parse with the prescription. examples/app-showcase done_rate migrates to the dataset form in the same PR, and the showcase dashboards that read it are re-pinned.
• Governed half: ADR-0021 gets a dated note under its decision naming the spec symbol (analytics.zod.ts measure / dimension sql) — a separate Tier H docs PR (four-piece), ⛔ never mixed into the code PR.
• Follow-up in domain:services: once the retirement is on main, the stand-down branch at analytics-service.ts:409 is unreachable and is deleted with its pin. The spec seat files that as a sub-issue at dispatch (Blocked-by: this card). Until then the interim is A and the gate is not touched.
• Fork clause: the premise is that every authored expression member has a structural equivalent. If the dev finds a dimension CASE bucket, or another expression shape, that dataset cannot express, it reports the fork on this card and stops; ⛔ no widening of dataset in the same PR, ⛔ no quiet fallback to B or C. A cloud or customer cube expression that reads a hidden field, if one turns up, is reported the same way and is not patched at the gate.

---

Generated by Claude Code

[objectstack-fleet]

Claim: PM loop round 32 · 2026-09-30T23:10Z
Session: session_01Sfe5YjBLwB9J3y8fvm2xq1
Account: os-justin (the seat's linked user as GET /user answers it; the card's assignee from this act)
Branch: claude/issue-20943-cube-sql-identifiers
Worktree: objectstack-issue-20943
Domain: domain:spec (ruling D 5921156712, execution parameters: a retirement card)
Seat: domain:spec#5 (seat post #19357)
Clause-②: yes (narrowing)
Scope: ruling D's execution parameters, taken whole. It is a retirement with the full spec-property-retirement kit.

• AnalyticsCubeSchema measure sql (packages/spec/src/data/analytics.zod.ts ≈:250) and dimension sql (≈:305) admit an identifier (a field or column reference) and '*' for a count. Any other value is refused at parse, with a prescription that names the dataset form (derived: { op, of: [...] } over named measures, and a filtered count).
• The kit: the ADR-0087 disposition in the changeset (BREAKING), a D3 semantic entry and the regenerated migration registry, the liveness ledger row, regenerated baselines and docs, and pins, each ablated.
• examples/app-showcase done_rate (src/data/analytics/showcase.cube.ts ≈:41, the only expression member in the tree, as ruling D read it) migrates to the dataset form in the same PR. The showcase dashboards and tests that read it are re-pinned: examples/app-showcase/test/gap-fill.test.ts and packages/services/service-analytics/src/__tests__/cube-authored-format-granularity.test.ts name it.
• ⚠️ Fork clause: if a dimension CASE bucket, or another expression shape, has no structural equivalent in dataset, the dev reports the fork on this card and STOPS. ⛔ No widening of dataset in this PR. ⛔ No fallback to B or C.
• ⚠️ The disclosure discipline holds: no request recipe, field spelling or returned value from any private measurement.
  File surface (stop on breach and explain it in the report):
• packages/spec (the schema, its tests, the D3 entry, the registry, liveness, generated projections and docs, regenerated only);
• the showcase cube, its dashboards and tests;
• the one service-analytics test named above, only where the migration moves its assertion;
• .changeset/.
  ⛔ The gate's stand-down branch (analytics-service.ts ≈:409) is not touched. It is service-analytics: delete the analytics field gate's stand-down on an authored cube expression member once #20943 retires raw expressions in a cube member's sql (the branch becomes unreachable) #20965's, filed in this act, Blocked-by: #20943. ⛔ ADR-0021's dated note is the separate Tier H docs PR the ruling names, and it is never mixed into this PR.
  Container & model: S, mode:subagent, model: opus.
  Review: an at-tier contract review is owed before enqueue.
  Thread-read: 5921156712
  Serial constraints cleared: read at this stamp.
• The only open PR on this surface is fix(spec): the field → name respelling reaches a form view's subform columns as its own ADR-0087 step, and two step-18 entries read true (#20901) #20953 (the seat's own, in the merge queue), on packages/spec/src/migrations/registry.ts.
• Registry serial condition: the dev writes migrations/registry.ts hunks only after merging a main that contains fix(spec): the field → name respelling reaches a form view's subform columns as its own ADR-0087 step, and two step-18 entries read true (#20901) #20953, regenerating with the repo's generator (never by hand). packages/spec/src: 1,277 comment lines still cite 170 deleted tracker numbers (1,295 sites) — the staged remainder of ruling C+D on #19123, measured by PR #20226 #20234 stage 11 waits behind this card on the same file.
• No open PR touches data/analytics.zod.ts, ui/dataset.zod.ts, the showcase analytics or dashboards, or the analytics liveness ledger.

---

Generated by Claude Code