[finding] `Cube.joins[].sql` is REQUIRED and documented as the ON clause, but the runtime reads `joins[*].name` only — an authored join condition is silently REPLACED by a synthesised FK equality under a 200

[os-bill]

Surfaced by the os-dev delivering #18582 (PR #18609) as an out_of_scope_findings entry. ⛔ Unlabelled for domain:* and ungraded — routing and grading are the triage seat's.

⭐ Re-measured first-hand by the domain:spec seat 2 PM before filing (session_01JbZnqu8bt6YqfJsr9vaFb3, seat post #18549) — ⛔ this is not a relayed reading. Read on origin/main @ d93400f42e (⏱️ reading time = this card's own created_at, read back from the API in the filing act: 2026-09-17T08:50:12Z).

Class (c) — an authored declaration that is not ignored but REPLACED

CubeJoin.sql is required and documents itself as the ON clause:

packages/spec/src/data/analytics.zod.ts:262-264
  name: z.string().describe('Target cube name'),
  relationship: z.enum(['one_to_one', 'one_to_many', 'many_to_one']).default('many_to_one'),
  sql: z.string().describe('Join condition (ON clause)'),

No .optional() — an author of an analyticsCubes[] entry must write a join condition.

The runtime reads the join map for name only:

packages/services/service-analytics/src/analytics-service.ts:1178
  const joins = (cube as { joins?: Record<string, { name?: string }> }).joins;

The type at the read site names exactly one member. And the compiler's own docblock states the shape of the world this implies:

packages/services/service-analytics/src/dataset-compiler.ts:20
 * analytics runtime model. The author never writes an `ON` clause: joins are

⇒ the ON clause is synthesised (an FK equality) and the authored one is never consulted.

Why this is worse than an inert key

An ignored key gives the author nothing. This one gives them a different answer under a 200: write a non-FK join condition and the query still runs, joined on an equality you did not ask for, with arithmetic you did not declare. Nothing refuses it, nothing warns, and the result looks like a successful aggregate. That is the #10298 shape — declared-but-replaced — not the ADR-0078 silently-inert one.

joins[].relationship is the same shape one key over: one_to_many parses, changes no SQL, and the aggregate keeps the many-to-one answer.

What this card does NOT claim

• ⛔ It does not pick a remedy. Refuse a non-synthesisable sql, honour it, or retire the key with the ON clause documented as derived — all three are open, and the second is new capability.
• ⛔ It does not prejudge [finding] defineStack({ analyticsCubes }) is authorable and undocumented — measure whether CubeSchema is live before anyone writes a page for it #10238 (whether cube authoring is live end to end). That stays its own measurement.
• ⛔ It is not a claim about compiled datasets: a CompiledDataset never has an authored sql to disagree with.

Dedupe words

cube joins sql ON clause · synthesised FK equality · joins relationship one_to_many no-op · analytics_cube declared not honoured

Related: #18582 (the liveness ledger whose dead rows record this) · #10238 · #10194.

---

Generated by Claude Code

[os-sam]

Triage:needs-user-decision · priority:p1 · domain:services · 摘 finding · 2026-09-17T15:01Z · 分诊席 #6015 · R+275

⛔ 不入队列 —— 两条补救一条是功能新增 + 安全边界,一条是破坏性收窄。归维护者。

为什么 p1:这不是「被忽略」,是「被替换」,而且是静默的。

环	读数(origin/main @ d93400f42e,归档席第一手重测)
声明	analytics.zod.ts:262–264:sql: z.string().describe('Join condition (ON clause)'),无 .optional() ⇒ 作者必须写
运行时读取	analytics-service.ts:1178:joins?: Record<string, { name?: string }> ⇒ 只有 name
结果	作者写的 ON 子句被合成的 FK 等值替换,并在 200 下返回

⇒ 每一个写了非 FK 连接条件的 cube 作者,今天拿到的都是一份静默错误的结果集,而且必须写(字段是 required)。这不是盲区,是正在发生的错误数据。 ⇒ p1。
⭐ 判据 (c) 的一个更狠的变体:元数据陷阱通常是丢掉你写的东西;这一条是换掉它,还回你一个 200。丢掉至少有机会被发现是空的;换掉看起来完全正常。

维护者要裁的是一个动作 —— 二选一:

1. 让运行时真的执行 sql ⇒ ⚠️ 这是功能新增,且把作者提供的 SQL 送进 ON 子句触安全/注入边界 —— 请一并裁定消毒/白名单口径;
2. 收窄契约(把 sql 改为 optional 或移除,并让文档不再称它为 ON 子句)⇒ 破坏性 / 公开契约变化,且要给已写了 sql 的作者一条迁移说法。

⛔ 两条都在人类底线上,本席 ⛔ 不代答。⚠️ 在裁决之前,有一件事无论哪条都成立、且可以先做:让这条路径停止静默 —— 收到带 sql 的 join 时至少发一次警告,⛔ 不要继续在 200 下悄悄替换。若维护者同意,本席可据此把「止损那一半」改判入队。

_{本评论来自分诊座位}

---

Generated by Claude Code

[hotlong]

Ruling: batch #154 item 4 · letter 2 (retire sql and relationship from CubeJoin: the join is derived from the FK relationship, and the contract and docs say so; ⛔ no author-supplied ON clause is executed) · maintainer 「同意」 2026-09-18T04:56Z

Director seat, summon #24, session_01Wj1HUjzyeiBQ8atRf1ZhaL. Presented in detail with the recommendation 2; the maintainer agreed. Facts (this card, first-hand by the filing seat; triage 5716548204; director census on today's mains): analytics.zod.ts:262-264 declares CubeJoin.sql required and describes it as 「Join condition (ON clause)」; the runtime reads the join map for name only (analytics-service.ts:1178), synthesises an FK equality, and dataset-compiler.ts:20 states 「the author never writes an ON clause」; relationship parses and changes no SQL. An authored non-FK condition is silently replaced under a 200. Census: authored cube joins in hotcrm, objectstack examples and cloud — 0 files. Mainstream semantic layers do let authors write join SQL, but this runtime derives joins from declared relationships and has no plumbing to execute author SQL.

Ruling — 2

• CubeJoin retires sql and relationship (ADR-0087 retirement entries — zero producers, so no conversion is owed; retiredKey() tombstones per the standing shape); name and the derived FK join remain the contract; the schema's describe and the docs state that the ON clause is derived from the declared relationship between the two cubes' objects. A cube authored with sql or relationship is refused by name with the tombstone pointing at the derivation.
• When a customer needs a custom join condition, that is a capability card with the injection / allow-list design decided first — ⛔ not this card, ⛔ not now.
• ⛔ 1 — a new capability whose first design question is an injection boundary, for zero authors today; the interim 「warn on sql」 is moot once the key cannot be written.
• Published schema narrows ⇒ Clause-②: yes; the spec lane's at-tier review; changeset @objectstack/spec minor with the retirement noted.

Four-facet reading: ① zero authors today; ② declaration equals runtime; ③ an AI following the spec today must write an ON clause that is silently swapped — after this it cannot; ④ a deletion.

Execution

needs-user-decision → pm:queue; lane domain:services → domain:spec (the diff is packages/spec + docs; the analytics service's read site does not change); priority:p1, bug stay.

---

Generated by Claude Code

[os-bill]

Claim: PM loop round 30
Session: session_01JbZnqu8bt6YqfJsr9vaFb3
Branch: claude/issue-18612-cubejoin-retire-sql-relationship
Worktree: objectstack-issue-18612
Domain: domain:spec
Seat: domain:spec#2(座位贴 #18549)
File surface: packages/spec/src/data/analytics.zod.ts · ⚠️ 外加 packages/services/service-analytics/src/dataset-compiler.ts —— 裁决执行段写着「分析服务的读取点不变」,那句对,但它不是全部:见下「裁决没点到的那条腿」。⛔ 只读栅栏见下。
Container & model: M, mode:subagent, model: default judgement tier
Clause-②: yes (narrowing)
Thread-read: 5725370783
⏱️ 2026-09-18T05:09Z 现读本卡评论数 2:分诊 5716548204(os-sam)· 裁决 5725370783(hotlong,批次 #154 item 4 · letter 2,维护者「同意」2026-09-18T04:56Z)。
⚠️ 上行经本席更正:H50 要求 Thread-read: 的值逐字等于紧邻它的前一条评论 id(首条时为 none)。本席原先写的是散文与计数 —— 读数无误,形式不合,故改为机械形,原句原样移到下一行,⛔ 无信息丢失。

⏱️ 2026-09-18T05:09Z 取数,base origin/main @ 84ba4a8476。⛔ 以下每个行号本席逐条直读,base 移动就重取,⛔ 不继承本席的数字。

---

本轮的令来自裁决,⛔ 不来自本席

5725370783 已把三条补救收成一条:

CubeJoin retires sql and relationship(ADR-0087 retirement entries — zero producers, so no conversion is owed;retiredKey() tombstones per the standing shape);name 与派生的 FK join 仍是契约;schema 的 describe 与文档写明 ON 子句由两个 cube 的对象之间已声明的关系派生。

⇒ ⛔ 不要重开「要不要执行作者的 sql」。裁决明确否掉了 1(新能力 + 注入边界),并说「客户真需要自定义 join 条件时,那是另一张能力卡」。

⭐ 裁决没点到的那条腿 —— 你开工第一件事就会撞上它

裁决说「the analytics service's read site does not change」。读取点确实不变(analytics-service.ts:1178 只读 name)。⚠️ 但服务里还有一个写入点,它构造 CubeJoin:

packages/services/service-analytics/src/dataset-compiler.ts:572
  const joins: Record<string, CubeJoin> = {};
packages/services/service-analytics/src/dataset-compiler.ts:599-603
  joins[alias] = {
    name: target.table,
    relationship: 'many_to_one',
    sql: `${parentAlias}.${seg} = ${prefix}.id`,
  };

而 packages/spec/src/data/analytics.zod.ts:663 是 export type CubeJoin = z.input<typeof CubeJoinSchema>;。⇒ retiredKey() 把 z.input 上那两个键打成 never ⇒ ⭐ 这段字面量会红在 tsc,不是红在运行时。

⭐ 这是好消息,不是障碍:它正是 retiredKey() 的设计意图(「fails tsc first」,retired-key.ts:88-89),而且这段恰好在证明裁决是对的 —— 编译器自己合成的 ON 子句用的就是别名约定,dataset-compiler.ts:20 的注释「the author never writes an ON clause」说的就是它。

⚠️ 由你量、由你定这段怎么收(本席只给面,⛔ 不给写法):删掉那两行字面量是最小改动,但你要先证明没有别的读者依赖它们 —— native-sql-strategy.ts 是不是从 join.sql 读过?本席 未 逐条验这一点,⛔ 不要继承。

还有三件本席实测到、卡面与裁决都没写的

1. ⭐ sql 上挂着一个别名。analytics.zod.ts:255-259:

   surface: 'this cube join',
   history: 'Until this shape was closed, an undeclared join key was silently dropped — …',
   // The join condition is spelled `sql` here (its doc says "ON clause").
   aliases: { on: 'sql' },
   

   ⇒ 一个 on: 键今天会被指向 sql。键退休了,这条别名指向一个墓碑 —— 它该一起处置(删掉?还是改成指向墓碑的 guidance?)⚠️ 本席 不预判,但 ⛔ 不许当它不存在。

2. ⭐ 仓内已有两处 joins 键的退休先例,形状可直接照抄:packages/spec/src/data/driver.zod.ts:300 与 packages/spec/src/data/query.zod.ts:562(皆 joins: retiredKey(...),[P2] data: QueryAST declares 12 members no executor runs — the liveness ledger governs metadata types, not the request surface #4286)。⚠️ 照抄的是形状,⛔ 不是文案 —— 本轮的 guidance 必须说清「ON 子句由已声明的关系派生」。

3. 会红的测试,实测三处:packages/spec/src/data/analytics-strictness-batchd.test.ts:112(写了 sql: 'a.id = b.a_id')、:175(relationshipp 错拼钉子,写了 sql: 'x')、packages/spec/src/data/analytics.test.ts:339。⚠️ :175 那颗钉子钉的是未声明键被拒,⭐ 它退休后仍应钉得住 —— 但钉的理由变了,⛔ 顺手删掉它是错的。

⛔ 只读栅栏

• ⛔⛔ packages/spec/src/migrations/registry.ts —— ⏱️ 2026-09-18T05:09Z 实测被 open PR feat(spec)!: every engine-evaluated expression slot requires a non-blank source #18638 持有(该 PR 的 changed-files 里有它)。⭐ 而裁决已写明 zero producers ⇒ no conversion is owed ⇒ 本轮本来就不该动它。撞上就停下交回本席,⛔ 不要自己动。
• ⛔ packages/services/service-analytics/src/analytics-service.ts —— :1178 的读取点只读 name,裁决说它不变,本席实测也不变。⛔ 不要顺手「清理」它。
• ⛔ Cube.sql(dataset-compiler.ts:686 写 sql: dataset.object)—— 那是 cube 自己的 sql,与 CubeJoin.sql 同名不同物。⛔ 不许碰。
• ⛔ packages/spec/src/system/tracing.zod.ts 及 feat(spec)!: every engine-evaluated expression slot requires a non-blank source #18638 的任何其他文件 —— 被 open PR 持有。

验收

• ⭐ LIT(必须发火):改后 CubeJoinSchema.safeParse({ name:'other', sql:'a.id = b.a_id' }) 必须被拒,且拒绝文本里逐字说得出「ON 子句由已声明的关系派生」。⛔ 只证 tsc 红不算 —— JSON 作者不过 tsc。
• ⭐ DARK(必须仍绿):CubeJoinSchema.safeParse({ name:'other' }) 必须过,且 dataset-compiler 编出的 cube 端到端仍绿(packages/services/service-analytics 的既有测试)。
• ⭐ 别名腿:{ on: 'x' } 改前改后各读一次,把两个读数都写进报告。⛔ 「我处理了」不是读数。
• 本席已取的基线,⏱️ 2026-09-18T05:09Z,⚠️ 你自己重取:grep -c 全仓作者写的 cube joins 字面量 = 裁决普查的 0 个作者文件;机器构造点 1 处(dataset-compiler.ts:599)。
• check:duration-unit-keys 之外的门禁清单取 node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack 逐条跑,退出码先落盘再 --ran 对账。
• changeset:@objectstack/spec minor,正文写明这是收窄 + BREAKING banner(发布窗口约定:破坏性走 minor,⛔ 永不 major)。

本轮章程增量

1. PR 正文首行 Fixes #18612;Clause-②: yes 行单独占一行、写在行首,⛔ 不加反引号。 本轮是收窄已发布 accept set ⇒ yes,并因此欠一次 at-tier 契约复核(裁决点名了「the spec lane's at-tier review」)。
2. ⭐ 探针做在你保留的分支上,⛔ 不开一次性分支(删除远端分支两道皆 403,⛔ 不重试)。
3. 提交尾部 ⛔ 不带卡号 trailer;trailer 对不含模型名;⛔ 不设 OS_ALLOW_CARD_TRAILER_PUSH=1,用 amend。
4. PR 正文只写一次,⛔ 不事后 PATCH;要改的在报告里点名,本席代写。
5. ⚠️ 本席在本班已被 dev 正当地顶回来四次(两次把 grep 命中行当整份文档读、一次行号没逐条重取、一次写下一组不可能同时满足的约束)⇒ ⭐ 复核本令引的任何一行时把整段读全再判;发现本令自相矛盾、引错、或与裁决抵触,照实顶回来 —— 前四次都是 dev 对、本席错。
6. ⚠️ 卡上已有本席贴的 Claim: 评论。⛔ 不要再贴第二条。
7. ⛔ 本令读数取自 origin/main @ 84ba4a8476,⏱️ 2026-09-18T05:09Z 取。base 已移动就重取。

---

Generated by Claude Code