fix(objectql,service-analytics): 报告对象「实际所在」的 datasource,而非它声明的那个 (#5288)

[os-project-manager]

Closes #5288

问题

plugin.ts 把 analytics 的探针接成了对象声明的值:

getObjectDatasource: (objectName) => dataEngine()?.getObject?.(objectName)?.datasource

这是 ObjectQL.getDriver 五步解析顺序里的第 1 步。而 ObjectSchema.datasource
带 .default('default'),'default' 在引擎里的含义恰恰是「没有显式绑定,继续往下查」,
不是「主库」。于是被 datasourceMapping 规则、ADR-0057 §3.6 生命周期分流、或所属
package 的 defaultDatasource 路由走的对象,探针一律回答 'default'。

sys_audit_log 就是活标本:靠 lifecycle.class: 'audit' 落到 telemetry,全程没有
任何声明可读。#5033 那条查询期诊断存在的唯一意义就是点名「表不在哪个库」,而它点错了:

改前: table "account" is not on datasource "default",   which is where its base object "sys_audit_log" lives
改后: table "account" is not on datasource "telemetry", which is where its base object "sys_audit_log" lives

(两条都是本 PR 新增测试里实测抓下来的完整文案,不是手写示意。)

改动

1. packages/objectql/src/engine.ts —— 新增 resolveEffectiveDatasource(objectName)。

getDriver 的解析顺序抽成一份私有的 resolveDatasourceBinding()(返回「名字 + 是哪一步
定的」),getDriver 改为消费它并负责「名字 → driver」以及驱动缺失时的两条诊断;公开的
resolveEffectiveDatasource() 只取名字。顺序只存在一份,不是两份 —— 这正是 #4462
抽出 resolveMappedDatasource 的理由,本 PR 在同一个文件里照着同一个形状写。

getDriver 行为逐条不变:优先级不变;声明 / 映射到的 datasource 没有活驱动时仍然拒绝
回落默认库(#4462),两条文案一字未改;第 3/4/5 步仍然只在驱动已注册时才成立;两行
debug 日志留在「它描述的那个决定」上,但改由 getDriver 发出,好让解析器保持无副作用
—— 探针问一次名字不应该在日志里留下一条从未发生的路由事件。

什么都没绑定、纯粹骑着部署默认驱动的对象,访问器答 undefined,这是刻意的:默认驱动
保留自己的自然名(#3826,drivers.has('default') 按构造为 false),那是驱动名,不是
谁把这个对象绑上去的 datasource;而 undefined 也正是消费方早就写在文档里的口径
(analytics-service.ts: "bound to, or undefined when it rides the default one")。
需要默认驱动名字的调用方仍然有 getDefaultDriverName()。顺带把「探针答案取决于对象有没有
被 Zod parse 过」这个隐患也消掉了:parse 过的对象带 'default',没 parse 的带 undefined,
现在两者都归一到 undefined。

2. packages/services/service-analytics/src/plugin.ts —— 探针改问引擎。 只此一行。
路由规则没有在 analytics 侧重算 —— 那正是本单存在的意义。

3. 注释订正(dataset-compiler.ts / analytics-service.ts)。 #5115 的闸门注释原文写着
「判据只认显式的 object.datasource……那些规则在这里看不见」,输入换了之后这句话就不成立了。
判据一字未改,注释改成如实描述新的输入,并写清楚还是看不见什么。

测试

• packages/objectql/src/engine-effective-datasource.test.ts(新增,12 例):第 2/3/4 步
  各一例(mapping 规则 / 生命周期分流 / package 默认值)—— 都是探针以前答错的;显式声明这一
  例保持不变;每一例都同时断言 getDriverForObject 挑的就是同名驱动(一份顺序,两种形状的
  答案);「什么都没绑定」答 undefined;未注册对象答 undefined;Zod parse 过的对象声明
  值是 'default' 而访问器答 'telemetry';绑定的 datasource 没有驱动时报出名字而不抛
  (getDriver 该抛还是抛)。
• packages/services/service-analytics/src/__tests__/effective-datasource-probe.test.ts
  (新增,6 例):走真实的 plugin 接线,engine double 把「声明了什么」和「引擎路由到哪」
  分开作答 —— 缺陷就活在这个混同里,任何让 double 直接声明自己路由的测试都看不见它。含 (a)
  的钉子、显式绑定的不变性、以及引擎不实现该访问器时退回 pre-analytics 的 getObjectDatasource 报告的是「声明值」而非「有效 datasource」:#5033 的诊断会点错库,#5115 的编译期闸门看不见隐式路由的对象 #5288 文案的分级。
• 消费半径清扫:raw-sql-object-routing.test.ts 的 engine double 只实现了 getObject(),
  改动后它答不上新问题 —— 按「补声明」处置(它的 routing map 本来就是有效路由,execute
  就是按它选库的),而不是改断言。这一条是 CI 之前本地就跑红并修好的。

pnpm --filter @objectstack/objectql test           → 154 files, 2668 passed, 0 failed
pnpm --filter @objectstack/service-analytics test  →  70 files, 1421 passed, 0 failed
eslint(7 个改动文件)                              → 0 problems
check:nul-bytes / engine-double-contract / error-code-casing /
route-envelope / spec-parsed-alias / verify-stand-in / type-check-coverage → 全绿

反向验证(先写预测,再跑)

把探针从访问器上摘掉(恢复成读声明值),预测:analytics 那 6 例里红 4 绿 2 ——
两条「点名 telemetry」的钉子红;「引擎答不上时退回默认文案」那条也红,但方向是反的
(旧探针答 'default' 而新探针答 undefined,所以它红在文案变成了 datasource "default",
不是红在没退回);编译期拒绝那条红。绿的两条:显式绑定的不变性(第 1 步本来就对),以及
「一侧只是骑默认驱动就不判」(这条是为了错的理由而绿——旧探针整个答不上)。引擎那 12 例
不动,因为摘的是探针不是访问器。

实测:Tests 4 failed | 2 passed,红的正是预测的那 4 条,断言消息逐条对上。恢复后 6/6 绿。

关于 #5115 的闸门(报告,不动手)

判据没改。变的是它的输入:现在两侧都被绑定(无论是显式、mapping、生命周期还是 package
默认值)且不同名时,编译期就能拒绝 —— 以前只有双方都显式声明才拒,这类 join 照样执行
不了,只是晚一点炸。而催生 #5115 的那个场景(被绑定的对象 join 一个只是骑默认驱动的对象)
仍然看不见:后者答 undefined,而未作答的一侧永远不拒。要覆盖它,闸门得把「骑部署默认」
当成一个答案,那是 #5115 后续单的事,本 PR 只把边界钉成了测试。

停止条件(18:29Z 分诊 re-anchor)未触发:访问器是 getDriver 既有解析步骤之上的薄公开包装,
只算名字、不取 driver、无缓存、无新语义、顺序未变;packages/spec 未触碰。

engine.ts 冲突面复核:#5272 已关闭;当前 5 个 open PR 无一触及 packages/objectql/src/engine.ts;
main 上该文件最近一次提交是 4fedb11,已在本分支基线内。

---

🤖 Generated with Claude Code

---

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 8, 2026 11:01pm

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/objectql, @objectstack/service-analytics.

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

• content/docs/api/data-api.mdx (via @objectstack/service-analytics)
• content/docs/api/index.mdx (via @objectstack/service-analytics)
• content/docs/concepts/metadata-lifecycle.mdx (via @objectstack/objectql)
• content/docs/data-modeling/formulas.mdx (via packages/objectql)
• content/docs/deployment/migration-from-objectql.mdx (via @objectstack/objectql)
• content/docs/deployment/vercel.mdx (via @objectstack/objectql)
• content/docs/kernel/runtime-services/examples.mdx (via packages/objectql)
• content/docs/kernel/services-checklist.mdx (via @objectstack/objectql, @objectstack/service-analytics)
• content/docs/kernel/services.mdx (via @objectstack/objectql)
• content/docs/permissions/authentication.mdx (via @objectstack/objectql)
• content/docs/permissions/sharing-rules.mdx (via @objectstack/service-analytics)
• content/docs/plugins/index.mdx (via @objectstack/objectql)
• content/docs/plugins/packages.mdx (via @objectstack/objectql, @objectstack/service-analytics)
• content/docs/protocol/kernel/index.mdx (via @objectstack/objectql)
• content/docs/protocol/objectql/query-syntax.mdx (via packages/objectql)
• content/docs/protocol/objectql/state-machine.mdx (via @objectstack/objectql)
• content/docs/releases/implementation-status.mdx (via @objectstack/objectql, @objectstack/service-analytics)
• content/docs/releases/v17.mdx (via @objectstack/service-analytics)
• content/docs/releases/v9.mdx (via @objectstack/service-analytics)

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.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 31297526579 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (3/3) — 失败步骤: Run this shard's tests

  �[41m�[1m FAIL �[22m�[49m src/commands/database-driver-allowlist.pin.test.ts�[2m > �[22m#6860 — --database-driver allowlist agrees with resolveStorageDefinition�[2m > �[22mos start�[2m > �[22moffers e
  �[41m�[1m FAIL �[22m�[49m src/commands/database-driver-allowlist.pin.test.ts�[2m > �[22m#6860 — --database-driver allowlist agrees with resolveStorageDefinition�[2m > �[22mos dev�[2m > �[22moffers eve
  �[41m�[1m FAIL �[22m�[49m src/commands/database-driver-allowlist.pin.test.ts�[2m > �[22m#6860 — --database-driver allowlist agrees with resolveStorageDefinition�[2m > �[22mos start�[2m > �[22mparses e
  �[41m�[1m FAIL �[22m�[49m src/commands/database-driver-allowlist.pin.test.ts�[2m > �[22m#6860 — --database-driver allowlist agrees with resolveStorageDefinition�[2m > �[22mos dev�[2m > �[22mparses eve
  

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 10 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 在其他 PR 的同类评论里搜同名测试；出现过 ⇒ flaky 实锤，开 issue 修/隔离那条测试。修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[os-project-manager]

Queue-failure triage (services-lane PM, session_01USNUyHEr7uaU6MoEWXitei) — worked the checklist in the bot's comment rather than re-queuing blind.

Verdict: not this PR. Checklist item 3 (batch-mate conflict) or flakiness — re-queued exactly once, not repeatedly.

Item 1 — is the failing test in a package this PR changed? No. packages/cli/src/commands/database-driver-allowlist.pin.test.ts and the resolveStorageDefinition it pins against (packages/cli/src/utils/storage-driver.ts) are both CLI-internal; this PR's eight files are confined to packages/objectql + packages/services/service-analytics (plus the changeset). The pin is about --database-driver flag parsing agreeing with the CLI's own storage-definition resolver — no import path from ObjectQL.resolveEffectiveDatasource or the analytics probe reaches it. ⚠️ Stated as a measured file-face fact, not as "it's not my package": this PR does change a datasource-resolution surface, so the possibility deserved checking rather than dismissing.

Item 2 — broken on main for everyone? No. The test arrived on main with 9d425a9 (PR #6913, fixing #6860), and 12 commits have merged to main since — every one of them through the same queue, which runs the full suite. A pin that were simply red on main would have blocked all twelve.

So: item 3, or intermittent. Either way the bot's own guidance applies — a blind re-queue rebuilds everything behind it, and repeated re-queues burn the queue for nothing. Auto-merge re-armed once. If the identical signature comes back on the next attempt, that is flakiness confirmed by repetition and it gets its own card (fix or quarantine that test) rather than a third attempt.

Local verification note, so nobody repeats a dead end: I could not reproduce against the shared checkout — its HEAD sits at 2bd4e5e, behind origin/main (68feaad), so the test file is not in that working tree and vitest reports "no test files found". A real reproduction needs a worktree at origin/main; not spent, given the twelve-merges evidence above already answers the question this PR needed answered.

---

Generated by Claude Code