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

analytics 的 `getObjectDatasource` 探针读的是 `getObject(name).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 那条查询期诊断 —— 它存在的唯一意义就是
点名「表不在哪个库」—— 点错了库。

引擎侧新增 `ObjectQL.resolveEffectiveDatasource(objectName)`:`getDriver`
既有解析顺序的公开、只算名字的那一面,抽出来是为了让这个顺序只存在一份
(与 #4462 抽出 `resolveMappedDatasource` 是同一个理由:第二份更短的路由
实现必然少一步,而且是悄悄地少)。`getDriver` 改为消费同一个解析器,行为
逐条不变 —— 优先级、声明/映射的 datasource 无驱动时拒绝回落到默认库、
两条诊断文案都原样保留。

对象什么都没被绑定、纯粹骑着部署默认驱动时,访问器答 `undefined`:默认驱动
保留自己的自然名(#3826),那是驱动名而不是谁把这个对象绑上去的 datasource;
而这也正是消费方早已写在文档里的口径。

analytics 侧只做一件事:探针改问引擎。路由规则**没有**在 analytics 侧重算。
#5115 的编译期闸门判据一字未改,变化的是它的输入现在能对隐式路由的对象作答。


Claude-Session: https://claude.ai/code/session_01USNUyHEr7uaU6MoEWXitei

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

.changeset/effective-datasource-accessor.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/objectql": patch
+"@objectstack/service-analytics": patch
+---
+
+fix(objectql,service-analytics): report the datasource an object is actually on, not the one it declares (#5288)
+
+Analytics' `getObjectDatasource` probe read `getObject(name).datasource` — the
+object's **declared** value, which is step 1 of the five `ObjectQL.getDriver`
+resolves by. `ObjectSchema.datasource` carries `.default('default')`, and
+`'default'` means "no explicit binding, keep looking" inside the engine, so
+every object placed by a `datasourceMapping` rule, by the ADR-0057 §3.6
+lifecycle split, or by its package's `defaultDatasource` answered `'default'`
+and was read out here as "the primary DB".
+
+`sys_audit_log` is the live specimen: `lifecycle.class: 'audit'` puts it on the
+`telemetry` datasource with nothing declared to read. So #5033's query-time
+diagnostic — whose entire job is to NAME the database a table is missing from —
+named the wrong one:
+
+```
+before: table "account" is not on datasource "default",   which is where its base object "sys_audit_log" lives
+after:  table "account" is not on datasource "telemetry", which is where its base object "sys_audit_log" lives
+```
+
+**New engine accessor — `ObjectQL.resolveEffectiveDatasource(objectName)`.** The
+public, name-only face of the resolution order `getDriver` already routes by,
+extracted so the order exists exactly once (the same argument that produced
+`resolveMappedDatasource` in #4462: a second, shorter copy of a routing order
+drifts by one step, silently). `getDriver` now consumes the same resolver and
+keeps every existing behaviour — precedence, the refusal to fall through to the
+default store when a declared or mapped datasource has no live driver, and both
+of its diagnostics.
+
+It answers `undefined` when nothing binds the object anywhere and it simply
+rides the deployment's default driver. That is deliberate and unchanged from
+what consumers already documented: the default driver keeps its natural name
+(#3826), so that name identifies a driver rather than a datasource anyone bound
+the object to. `getDefaultDriverName()` is still there for callers that want it.
+
+Analytics' probe now asks the engine instead of the declaration; the routing
+rules are **not** re-implemented on the analytics side. #5115's compile-time
+cross-datasource join gate keeps its predicate exactly as written — what changed
+is that its input can now answer for objects bound by a mapping rule, by the
+lifecycle split, or by a package default, so a join between two bound
+datasources is refused at registration instead of exploding at query time. A
+join from a bound object to one that merely rides the deployment default is
+still not decidable at compile time and remains the query-time diagnostic's
+business.

packages/objectql/src/engine-effective-datasource.test.ts

@@ -0,0 +1,251 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #5288 — `resolveEffectiveDatasource`: the datasource an object's rows are
+ * actually on, by NAME.
+ *
+ * The engine has five resolution steps (`getDriver`), and everyone who only
+ * needed the NAME used to read `object.datasource` — step 1. That value is the
+ * DECLARATION, and `ObjectSchema.datasource` carries `.default('default')`, so
+ * an object placed by a `datasourceMapping` rule, by the ADR-0057 §3.6
+ * lifecycle split, or by its package's `defaultDatasource` still answered
+ * `'default'` — which in `getDriver` means "no explicit binding, keep looking",
+ * never "the primary DB". Analytics' `getObjectDatasource` probe was such a
+ * reader, and #5033's query-time diagnostic composed from it therefore named a
+ * database the rows are not in.
+ *
+ * These cases pin the accessor against `getDriver` itself: for every routing
+ * mechanism, the NAME it answers is the name of the driver `getDriver` picks.
+ * One resolution order, two shapes of answer.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ObjectSchema } from '@objectstack/spec/data';
+import { ObjectQL } from './engine.js';
+
+/** Owning package for the probe objects — no manifest is registered for it, so
+ *  step 4 stays a no-op unless a case registers one. */
+const PKG = 'com.example.probe';
+
+function stubDriver(name: string) {
+  return {
+    name,
+    version: '0.0.0',
+    supports: {},
+    async connect() {},
+    async disconnect() {},
+    async checkHealth() {
+      return true;
+    },
+    async execute() {
+      return null;
+    },
+    async find() {
+      return [];
+    },
+    async findOne() {
+      return null;
+    },
+    async create(_o: string, d: Record<string, unknown>) {
+      return d;
+    },
+    async update() {
+      return {};
+    },
+    async upsert() {
+      return {};
+    },
+    async delete() {
+      return true;
+    },
+    async count() {
+      return 0;
+    },
+    async bulkCreate() {
+      return [];
+    },
+    async bulkUpdate() {
+      return [];
+    },
+    async bulkDelete() {},
+    async beginTransaction() {
+      return {};
+    },
+    async commit() {},
+    async rollback() {},
+  } as any;
+}
+
+describe('resolveEffectiveDatasource — one name per routing step (#5288)', () => {
+  let engine: ObjectQL;
+  let primary: any;
+
+  beforeEach(async () => {
+    engine = new ObjectQL();
+    primary = stubDriver('memory');
+    engine.registerDriver(primary, true);
+    await engine.init();
+  });
+
+  // ── Step 1: an explicit binding. The one step the old declared read got right ─
+
+  it('answers the explicit `datasource` — the step the declared read already had', () => {
+    engine.registerDriver(stubDriver('warehouse'));
+    engine.registry.registerObject({ name: 'wh_fact', datasource: 'warehouse', fields: {} }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('wh_fact')).toBe('warehouse');
+    // …and it is the driver `getDriver` picks, not a parallel opinion about it.
+    expect(engine.getDriverForObject('wh_fact')).toBe(engine.getDriverByName('warehouse'));
+  });
+
+  // ── Step 2: a datasourceMapping rule ────────────────────────────────────────
+
+  it('answers the mapped datasource for an object a mapping rule places (step 2)', () => {
+    engine.registerDriver(stubDriver('archive'));
+    engine.setDatasourceMapping([{ objectPattern: 'log_*', datasource: 'archive' }]);
+    engine.registry.registerObject({ name: 'log_request', fields: {} }, PKG);
+
+    // What the probe used to read — the declaration — says nothing at all here.
+    expect(engine.getObject('log_request')?.datasource).toBeUndefined();
+
+    expect(engine.resolveEffectiveDatasource('log_request')).toBe('archive');
+    expect(engine.getDriverForObject('log_request')).toBe(engine.getDriverByName('archive'));
+  });
+
+  // ── Step 3: the ADR-0057 §3.6 lifecycle split — #5033's own object ──────────
+
+  it('answers `telemetry` for a lifecycle-classed ledger (step 3) — the #5033 case', () => {
+    engine.registerDriver(stubDriver(ObjectQL.LIFECYCLE_DATASOURCE));
+    engine.registry.registerObject({
+      name: 'sys_audit_log',
+      lifecycle: { class: 'audit', retention: { maxAge: '90d' } },
+      fields: {},
+    }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('sys_audit_log')).toBe('telemetry');
+    expect(engine.getDriverForObject('sys_audit_log')).toBe(
+      engine.getDriverByName(ObjectQL.LIFECYCLE_DATASOURCE),
+    );
+  });
+
+  it('is Zod-parse independent: the declared read answers `default`, this answers `telemetry`', () => {
+    // The exact shape the defect wore in a real deployment. `ObjectSchema` gives
+    // `datasource` a `.default('default')`, so a PARSED object carries the
+    // string `'default'` — and the old probe reported it as if it were a
+    // database name, for an object the engine had routed elsewhere.
+    engine.registerDriver(stubDriver(ObjectQL.LIFECYCLE_DATASOURCE));
+    const parsed = ObjectSchema.parse({
+      name: 'sys_audit_log',
+      label: 'Audit log',
+      lifecycle: { class: 'audit', retention: { maxAge: '90d' } },
+      fields: { action: { type: 'text', label: 'Action' } },
+    });
+    expect(parsed.datasource).toBe('default');
+    engine.registry.registerObject(parsed, PKG);
+
+    expect(engine.resolveEffectiveDatasource('sys_audit_log')).toBe('telemetry');
+  });
+
+  it('does NOT invent lifecycle routing when no telemetry datasource is registered', () => {
+    // Step 3 is opt-in by the datasource's existence. Without it the ledger
+    // really is on the default store, and saying `'telemetry'` would be the
+    // same lie in the other direction.
+    engine.registry.registerObject({
+      name: 'sys_audit_log',
+      lifecycle: { class: 'audit', retention: { maxAge: '90d' } },
+      fields: {},
+    }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('sys_audit_log')).toBeUndefined();
+    expect(engine.getDriverForObject('sys_audit_log')).toBe(primary);
+  });
+
+  // ── Step 4: the owning package's defaultDatasource ──────────────────────────
+
+  it("answers the owning package's `defaultDatasource` (step 4)", () => {
+    engine.registerDriver(stubDriver('billing_db'));
+    engine.registerApp({
+      id: 'com.example.billing',
+      name: 'billing',
+      defaultDatasource: 'billing_db',
+      objects: [{ name: 'invoice', fields: {} }],
+    });
+
+    expect(engine.getObject('invoice')?.datasource).toBeUndefined();
+    expect(engine.resolveEffectiveDatasource('invoice')).toBe('billing_db');
+    expect(engine.getDriverForObject('invoice')).toBe(engine.getDriverByName('billing_db'));
+  });
+
+  it('ignores a package default whose datasource has no driver, exactly as getDriver does', () => {
+    engine.registerApp({
+      id: 'com.example.billing',
+      name: 'billing',
+      defaultDatasource: 'never_connected',
+      objects: [{ name: 'invoice', fields: {} }],
+    });
+
+    // Step 4 answers only when the driver exists — the rows are on the default
+    // store, and that is what both the driver lookup and the name report.
+    expect(engine.resolveEffectiveDatasource('invoice')).toBeUndefined();
+    expect(engine.getDriverForObject('invoice')).toBe(primary);
+  });
+
+  // ── Step 5 / no routing at all: unchanged, and deliberately `undefined` ─────
+
+  it('answers `undefined` for an object nothing binds — it rides the default driver', () => {
+    // Unchanged from what the declared read answered for such an object, and
+    // deliberate: the default driver keeps its NATURAL name (#3826, here
+    // `memory`), so that name identifies a DRIVER, not a datasource anyone bound
+    // this object to. Callers that want it have `getDefaultDriverName()`.
+    engine.registry.registerObject({ name: 'biz_account', fields: {} }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('biz_account')).toBeUndefined();
+    expect(engine.getDriverForObject('biz_account')).toBe(primary);
+    expect(engine.getDefaultDriverName()).toBe('memory');
+  });
+
+  it('answers `undefined` for an object this engine has never heard of', () => {
+    expect(engine.resolveEffectiveDatasource('no_such_object')).toBeUndefined();
+  });
+
+  // ── Precedence and the broken-deployment case ──────────────────────────────
+
+  it('keeps getDriver’s precedence: an explicit binding outranks lifecycle routing', () => {
+    engine.registerDriver(stubDriver(ObjectQL.LIFECYCLE_DATASOURCE));
+    engine.registerDriver(stubDriver('special'));
+    engine.registry.registerObject({
+      name: 'probe_pinned',
+      datasource: 'special',
+      lifecycle: { class: 'telemetry', retention: { maxAge: '14d' } },
+      fields: {},
+    }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('probe_pinned')).toBe('special');
+  });
+
+  it('keeps getDriver’s precedence: a mapping rule outranks lifecycle routing', () => {
+    engine.registerDriver(stubDriver(ObjectQL.LIFECYCLE_DATASOURCE));
+    engine.registerDriver(stubDriver('archive'));
+    engine.setDatasourceMapping([{ objectPattern: 'sys_audit_*', datasource: 'archive' }]);
+    engine.registry.registerObject({
+      name: 'sys_audit_log',
+      lifecycle: { class: 'audit', retention: { maxAge: '90d' } },
+      fields: {},
+    }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('sys_audit_log')).toBe('archive');
+    expect(engine.getDriverForObject('sys_audit_log')).toBe(engine.getDriverByName('archive'));
+  });
+
+  it('names a binding whose driver is missing instead of throwing', () => {
+    // A naming probe exists to be READ, including while the deployment is
+    // broken: `getDriver` refuses to serve this object (it will not silently
+    // write to the default store — #4462), and the name it refuses ON is
+    // precisely what a diagnostic needs to print.
+    engine.registry.registerObject({ name: 'wh_fact', datasource: 'warehouse', fields: {} }, PKG);
+
+    expect(engine.resolveEffectiveDatasource('wh_fact')).toBe('warehouse');
+    expect(() => engine.getDriverForObject('wh_fact')).not.toThrow();
+    expect(engine.getDriverForObject('wh_fact')).toBeUndefined();
+  });
+});