fix(service-analytics): the draft preview groups a bucketed time dimension and reads a qualified filter member as the live faces do; ObjectQL serves a backed RELATION.id dimension - #28742

📓 Docs Drift Check

5 anchor(s) derived from 1 changed package(s); no hand-written page names any of them, so this run has nothing to list — not a clean bill of health. This check sees only pages that NAME a derived anchor: one that documents this change in prose, or enumerates it in an authoring dialect, names none and stays invisible to it on every run.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 3148c8a2a57541aa897dfa5e3ffda14ef20d9d60 && git checkout 3148c8a2a57541aa897dfa5e3ffda14ef20d9d60
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin db357f6da9f787ff6285c20c70bc02a1bc138d35 400154ac098acb0cc64c2db977d659d0d660153d && git checkout -B drift-repro db357f6da9f787ff6285c20c70bc02a1bc138d35 && git merge --no-ff 400154ac098acb0cc64c2db977d659d0d660153d

node scripts/docs-audit/affected-docs.mjs --json db357f6da9f787ff6285c20c70bc02a1bc138d35

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 400154ac098acb0cc64c2db977d659d0d660153d
Local-runs: none

Read: cards #28690, #28691, #28692 (bodies, triage records 6558905217 / 6558915201 / 6558925351, claims 6559855795 / 6559874127 / 6559890848, os-dev-report 6560773894; no earlier contract record or ruling on any of the three), PR #28742 body and file list (5 files), the net diff git diff 4bf48a8cc 400154ac (merge base with main; main has not touched packages/services/service-analytics since), and the head's check-runs. The face is the declaration face: the tree carries no packages/spec file, no published schema and no governed path, and the PR body carries Clause-②: yes (widening).

① Derived judgments

Accept-set and public-surface changes the diff implies, each judged:

1. ObjectQL strategy, executeCrossObject groupBy (analytics: the ObjectQL strategy refuses a backed account.id dimension with INVALID_QUERY because the cross-object expand groups by the related id twice #28692). Accept-set widening. Right. Two shapes the strategy used to send the engine with one column named twice now name it once: account.id beside account.name (one FK column for two cross dimensions), and the FK column account beside account.name in either order (a base dimension reuses the FK column already grouped; fkGrouped holds only for a non-bucketed base dimension whose field is a cross dimension's fkField). Each used to fail with INVALID_QUERY / 400 and is now served with native's groups. rebucketCrossObject keys on baseDimFields and each cross dimension's fkField separately, so one grouped column serves both readers. Nothing that was served before is refused now.
2. ObjectQL strategy, resolveFkAttr (analytics: the ObjectQL strategy refuses a backed account.id dimension with INVALID_QUERY because the cross-object expand groups by the related id twice #28692). Accept-set widening. Right. For attr === 'id' the call is now groupBy: ['id'] instead of ['id', 'id']. A backed RELATION.id used to be refused with INVALID_QUERY and is now served. The scope arms (the read-scope asserts and the RESTRICTED bucket for hidden ids) come before the groupBy and do not change.
3. Engine duplicate-groupBy refusal. Unchanged. Right. packages/objectql is not in the diff, so the engine's guard still refuses every other caller's duplicate. The fix is in the strategy, where the card says the duplicate comes from.
4. Draft preview grouping set (analytics: the dataset draft preview drops a bucketed timeDimensions entry that is not also in dimensions, so it answers one total instead of the time groups #28690). The answer changes; the accept set does not. Right. evaluateAnalyticsQueryOverRows now groups by projectedDimensions(query) (order-key-door.ts), the set the ObjectQL projection and buildFieldMeta already read. That set is dimensions, then each bucketed timeDimensions entry not already among them. fields reads the same set, so the bucket column carries the cube dimension's type. Queries the preview already served now get the live faces' rows and columns. A window-only time dimension still projects nothing. No refusal is added or removed.
5. Draft preview where member resolution (analytics: the dataset draft preview answers [] for a runtimeFilter member spelled OBJECT.region that both live strategies resolve to the declared dimension #28691). The answer changes; the accept set does not. Right. The card allowed resolve or refuse. Resolve is the choice that keeps the preview no narrower than the live faces, which the PR measures as serving every spelling. previewWhereColumns reads leaves with the strategies' reader (normalizeAnalyticsFilterTree + collectFilterLeaves) and resolves each with declaredMemberEntry(cube, member, 'any'), the lookup assertWhereFields uses. It lists only members whose resolved column differs and is a bare identifier. The where tree is not rewritten: the match reads a listed member from its column (whereRow). The original row is what gets filtered on, so the time window and the grouping still read columns. The typed reader (whereType) now feeds the where lowering's isDatetimeColumn and the storage-form comparison with the column's declaration. windowLowering keeps the window on declaredType exactly as before. Neither arm of the lowering refuses on a declared type, so a query the preview served before is not refused now. It is read with the live faces' column type.
   • Unnamed but implied: the 'any' arm also falls through to cube.measures, so a where on a measure key whose sql is a bare column (revenue over annual_revenue) is now read from that column in the preview. This matches the strategies' filter resolution as declaredMemberEntry's own doc states it, and it is the same class as the changeset's "a member such as…". Right, but no test covers it (S2).
6. evaluateAnalyticsQueryOverRows gains an optional trailing whereColumns. No public-surface change. Right. The package's exports map is "." alone, and src/index.ts does not export preview-evaluator.ts. The parameter is optional and last, so in-package callers compile unchanged. previewWhereColumns is module-private. ObjectQLStrategy is exported, but only its private methods' bodies change, not their signatures.
7. No spec key, export, error code or status added. The changeset's own closing sentence says so, and the diff agrees.

Card "Wanted" lines against the diff:

• analytics: the dataset draft preview drops a bucketed timeDimensions entry that is not also in dimensions, so it answers one total instead of the time groups #28690: grouped whether or not the member is in dimensions. Met.
• analytics: the dataset draft preview answers [] for a runtimeFilter member spelled OBJECT.region that both live strategies resolve to the declared dimension #28691: one member resolution shared with the dimension face, no second walker; never a silent []. Met, through the declaredMemberEntry resolution. The leaf reader is called again rather than reimplemented, but it is now the third copy of the same five lines in this file (S1).
• analytics: the ObjectQL strategy refuses a backed account.id dimension with INVALID_QUERY because the cross-object expand groups by the related id twice #28692: the expand does not add a column the dimension already names. Met.

Tests: preview-time-filter-fk-parity.test.ts, 17 cases on real SQLite (5 for #28690, 7 for #28691, 5 for #28692 including the #28555 preview-refusal control). Each case is asserted on every face it claims. The red-on-base and ablation readings are the dev's (os-dev-report) and are not re-run here (read-only).

② Semver level

• Changeset .changeset/28690-preview-time-buckets-filter-columns-fk-id.md: '@objectstack/service-analytics': patch, the only package the diff moves. It carries Clause-②: yes (widening) and Metadata-protocol: none, line-initial. The PR body carries both lines the same way. No skip-changeset label (the PR has no labels), which is correct because this is a published package.
• The level matches what the diff publishes. AGENTS.md Post-Task Checklist step 3 says the level follows the Metadata-protocol kind alone: none takes patch, and a non-protocol widening ships patch. There is no packages/spec file and no authorable key, so Metadata-protocol: none is right, and so is patch.
• Clause-②: yes (widening): right. Shapes 1 and 2 in ① move INVALID_QUERY / 400 to served on a published package's strategy, which widens the accept set. Shapes 4 and 5 correct answers without moving the accept set. Nothing in the diff refuses what was served, so no (narrowing) arm is owed, nor a BREAKING banner or ADR-0087 marker. The dev's dogfood-battery skip, on the grounds that the change is widening only, holds.

Gate verdicts: the head's check-runs, read 2026-11-01T16:54:21Z: 48 check-runs, all completed — 35 success, 13 skipped (UI, docs, dogfood and opt-in jobs this path set does not trigger), 0 failure / cancelled / timed_out. Build Core, all eight Test Core shards, every Lint and Type Check job and Check Changeset among the successes.

③ Boundary flags

• open_questions: []. Nothing to answer.
• flags: the os-dev-report has no flags key. Its three deviations were read as flags, and none bears on the contract:
  • The remote branch was recreated with no force push.
  • The first ablation pass was discarded and every ablation re-run on the committed de8aeea7.
  • The PR was opened with no labels, which is correct with a changeset present.
  • Head 400154ac is de8aeea7 plus a two-spelling change to the changeset text (the diff confirms no code differs), and the dev re-ran the six changeset- and citation-reading gates there.
• out_of_scope_findings[0] is escalated to the seat (not fixed here, correctly): on the ObjectQL strategy's direct, non-cross-object path, two dataset dimensions over one base column (region and zone over region) still answer INVALID_QUERY / 400 (duplicate groupBy), while native and the preview serve both names. It has the same root as analytics: the ObjectQL strategy refuses a backed account.id dimension with INVALID_QUERY because the cross-object expand groups by the related id twice #28692 on execute()'s groupBy. The diff confirms it is untouched: fkGrouped reuses only a column that is a cross dimension's fkField. It is class a, measured, with reach given, so the seat files or dedupes it as a card. It does not block this PR, which neither causes it nor makes it worse. (Not part of this review's inputs, so not relied on here: an open card analytics: the ObjectQL strategy refuses two dataset dimensions over one column with INVALID_QUERY (duplicate groupBy), while native and the preview serve both names #28744 carries that title. The seat confirms it is this finding.)
• The claim's file surface allowed packages/objectql/src/**. The diff does not use it, which the claim named as a possibility, not a requirement.

Should-fix (non-blocking, not a condition of the verdict):

• S1. analytics-service.ts now holds three copies of the same guarded leaf read (collectFilterLeaves(normalizeAnalyticsFilterTree({ where }, NO_DATETIME_COLUMNS)) in a try/catch): filterMembers in the named-fields reader, relationshipMembers, and the new previewWhereColumns. Extract one whereLeafMembers(query) and have all three read it. That is the copy-drift this file's own declaredMemberEntry doc warns about.
• S2. Add one case for a where on a measure key over a bare column (①5, sub-bullet), the one resolution arm previewWhereColumns adds that the suite does not exercise.

Must-fix: none.

Implemented-by: claude/project-thread-0o422x
Reviewed-by: session_01FEkQ5kE5BrPUPNMMyv6oCH

VERDICT: PASS

domain:server#3 · os-project-manager · session_01FEkQ5kE5BrPUPNMMyv6oCH

席位核对 · ACCEPT · PR #28742 · 2026-11-01T16:55Z

Head-sha: 400154ac098acb0cc64c2db977d659d0d660153d

维护者速读(席位终稿)

• 改了什么:数据集三处答法对齐线上：草稿预览把只出现在 timeDimensions 的时间维度按粒度分组(不再合成一个总数);预览把 OBJECT.region 这类带对象前缀的筛选成员解析到声明的维度(不再静默答 []);ObjectQL 策略对 account.id 这类关联 id 维度不再重复加分组列，答出与原生相同的分组(不再 400)。
• 为什么改:analytics: the dataset draft preview drops a bucketed timeDimensions entry that is not also in dimensions, so it answers one total instead of the time groups #28690、analytics: the dataset draft preview answers [] for a runtimeFilter member spelled OBJECT.region that both live strategies resolve to the declared dimension #28691、analytics: the ObjectQL strategy refuses a backed account.id dimension with INVALID_QUERY because the cross-object expand groups by the related id twice #28692,PR fix(service-analytics)!: members read through a relationship path answer one refusal on the native, ObjectQL and draft-preview faces #28686 的 dev 实测出的三处三出口不一致。
• 风险与回滚:低。只让原来答错或拒绝的查询答对;没有原来能答的被拒，引擎的重复列拒绝不变，未碰 packages/objectql。回滚即 revert。
• 先看:packages/services/service-analytics/src/preview-evaluator.ts;strategies/objectql-strategy.ts。
• 两分钟验证:pnpm --filter @objectstack/service-analytics exec vitest run src/__tests__/preview-time-filter-fk-parity.test.ts(main 上红)。
• 需要你做的:无。席位按常设授权落地，合并即关三张卡。
• 席位意见:契约复核 PASS,可落。

核对六项

1. 形态:draft → main;Fixes #28690/#28691/#28692 各占一行，合并关卡正确，与派单 pm-orders/server/order-28690.md 一致。文件 5 个，在认领 6559855795/6559874127/6559890848 申报面内(仅 service-analytics,未用到申报里可选的 packages/objectql)。
2. 前提实测:dev 在真实 SQLite 上对三张卡各出口先红后绿，并逐项消融;analytics: the dataset draft preview answers [] for a runtimeFilter member spelled OBJECT.region that both live strategies resolve to the declared dimension #28691 选"解析"而非"拒绝",因两个线上出口对实测的每种写法都能答。
3. 门禁:本 head check-runs 35 success、13 skipped(路径未命中)、0 失败或待跑。dev 本地：完整构建后 62 条派生门禁全部 exit 0,typecheck 与手动门禁 exit 0。
4. 接受的偏差:dev 三条偏差均为过程性(远端分支在 fix(service-analytics)!: members read through a relationship path answer one refusal on the native, ObjectQL and draft-preview faces #28686 合并后被删，推送新建;一次消融还原误删未提交修改，已恢复并在 de8aeea7 重跑全部消融;PR 未带标签)。复核两条 should-fix 记为后续，不挡落地:(S1)analytics-service.ts 中同一受保护 where 叶子读取有三份，可抽一个 helper;(S2)缺"筛选落在映射到普通列的度量键"的用例。
5. 范围外去向:dev 实测的 ObjectQL 直连路径"两个维度同列"仍 400,已立卡 analytics: the ObjectQL strategy refuses two dataset dimensions over one column with INVALID_QUERY (duplicate groupBy), while native and the preview serve both names #28744(p3,pm:blocked 待本 PR 合入后转队列)。Metadata-protocol: none,Skills-docs: none(已核)。
6. 落地条款:Clause-②: yes (widening),非 spec 路径 ⇒ TIER_DEFAULT 复核 PASS(6560982865,Head-sha 与现 head 一致)。semver:service-analytics patch,与 changeset 一致(非协议扩大取 patch,Check Changeset 本 head success)。check-governed-merges --pr 28742:NOT governed,411 行。落地授权，维护者原话:「按照 pm-dispatch 规则复核过的都授权」(2026-10-25T11:35Z)。