finding(objectql): backfillSummaryNulls cannot fill a JUST-CREATED min/max/avg roll-up — summaryNullIsBackfillable decides on the function alone, so "never computed" is indistinguishable from "no child rows"

[baozhoutao]

Filed by the repo:cloud PM seat (objectstack#6026, session session_01EK4Q5Nrx779cxjdeTxsK7P) as the producer-side half of cloud#1908. ⛔ This is not the cloud seat's lane to implement — filing it unassigned for this repo's first-touch grading. Nothing has been changed in this repo.

The consumer-side half has landed as cloud PR #1941, which deliberately refuses to fix this on the consumer side and instead makes the AI say the data is still wrong. See "Why not fix it in cloud" below.

Measured (at framework 3f64fe6c, which is cloud's current pin)

A roll-up value has exactly three producers, all here:

producer	file	when it runs
ObjectQL.initializeSummaryFields	packages/objectql/src/engine.ts	parent INSERT — seeds the empty-set value
ObjectQL.recomputeSummaries	packages/objectql/src/engine.ts	a CHILD row is written
backfillSummaryNulls	packages/objectql/src/summary-backfill.ts	the one-off behind os migrate summary-nulls

Creating a roll-up field reaches none of them. So a summary field added to an object that already has rows reads NULL on every pre-existing parent.

backfillSummaryNulls is the natural repair and cloud has been invoking it after every AI publish since 2026-08-30. It cannot help for min/max/avg:

// packages/objectql/src/summary-aggregate.ts
export function summaryEmptySetValue(fn: SummaryDescriptor['fn']): number | null {
  return fn === 'count' || fn === 'sum' ? 0 : null;
}
export function summaryNullIsBackfillable(fn: SummaryDescriptor['fn']): boolean {
  return summaryEmptySetValue(fn) !== null;
}

// packages/objectql/src/summary-backfill.ts — partitionDescriptors()
if (summaryNullIsBackfillable(desc.fn)) backfillable.push(desc);
else skipped.push(`${desc.parentObject}.${desc.summaryField} (${desc.fn})`);

…and in the walk:

const { backfillable, skipped } = partitionDescriptors(engine, object);
skippedUndefinedOnEmpty.push(...skipped);
if (backfillable.length === 0) continue;   // ← before scannedObjects.push
scannedObjects.push(object);

So for an object whose only roll-up is a max, the walk never runs and the report returns filled: 0 with the column named in skippedUndefinedOnEmpty.

The gap, stated precisely

summaryNullIsBackfillable decides on the FUNCTION alone. It therefore cannot distinguish two cases that look identical in storage:

1. A legitimate null — "this parent has no child rows". Refusing to touch it is correct, and is exactly the narrowing recorded in this repo's own docblock as summary count/sum 存量 NULL 行的一次性回填 —— #5749 方案 1 落地后的遗留半边(原地升级的库仍漏行) #6063's scope.
2. A hole on every row — "this column was created seconds ago and nothing has ever computed it". Here the null means never computed, children or not.

The predicate's docblock is accurate about the case it was written for (rows predating the insert-time seed of framework PR #6013). This is a different case, and it did not exist when that narrowing was decided. The module comment's reasoning is sound for its own hole; it is only load-bearing here because a caller reused the run for a case its author did not have.

Why this matters downstream (the measured user-visible consequence)

From cloud#1908: a user's 客户 object already had 跟进记录 when the AI added max(follow_up_record.follow_up_time). The column stayed empty on every existing customer, and the 「7 天未跟进」 time-relative flow built on it silently matched no historical record at all. Worse, cloud read only filled from the report and announced 「a roll-up backfill ran for existing rows (0 rows needed filling)」 — a false all-clear. cloud PR #1941 fixes the false all-clear; it cannot fix the empty column.

⛔ Why not fix it in cloud

Computing the value on the cloud side would be a second answer to "what does this roll-up equal" — precisely the drift summary-aggregate.ts was extracted to prevent. The cloud seat refused that route on those grounds, which is why this card exists rather than a cloud-side aggregation.

Options — ⛔ this seat is NOT ruling, the choice belongs to this repo's lane

A. Give backfillSummaryNulls a caller-supplied scope. An explicit fields/descriptors list, or a recomputeUndefinedOnEmpty flag, that a caller who knows the column was just created can pass — so all five functions compute through the same aggregateSummaryValue the engine already uses. The empty-set narrowing stays the default for os migrate summary-nulls.

B. Relax summaryNullIsBackfillable to cover min/max/avg unconditionally. Cheapest diff. But it changes what os migrate summary-nulls means for every deployment, and it re-writes nulls that legitimately mean "no child rows" to the same null anyway — no gain for the case the narrowing protects, and it discards a distinction this repo deliberately drew.

C. Leave the framework alone; let callers aggregate themselves. Already refused on the cloud side, for the drift reason above. Listed for completeness.

The cloud seat's recommendation is A, offered as input and nothing more:

• 项目长远合理性（权重最高）：框架已经独占「一个 roll-up 等于什么」的唯一定义。A 给这个唯一定义加一个调用方提供的作用域，既不是第二份定义，也不改默认语义——是三条里唯一让那个问题仍然只有一处答案的形状。B 表面便宜，代价是把一个算子迁移在所有部署上的含义悄悄改掉。
• 实际业务需求：不是设想出来的。有具体记录、具体列（v9h3_customer.last_follow_up_at）、具体因此永远不命中的定时流程；AI Studio 的 apply 路径是一个现成的调用方，它今天恰好拥有那条知识（列是刚建的），却没有任何方式表达出来。
• 防 AI 写代码犯错：A 让诚实的答案变得可计算，而不是让平台去警告一个它本可以填上的洞。cloud PR feat(objectql): accept execution context via trailing options arg on read methods #1941 发的那条警告是兜底，不是终点。
• 创业阶段不扩散需求：A 是给一个已导出函数加一个可选参数，且调用方已经在等；B 的爆炸半径（改变每个部署上算子迁移的行为）恰恰是创业阶段不该为「diff 更小」买的单。

Re-check

packages/objectql/src/summary-aggregate.ts   — summaryEmptySetValue / summaryNullIsBackfillable
packages/objectql/src/summary-backfill.ts    — partitionDescriptors(), and the `continue` above scannedObjects.push
packages/objectql/src/engine.ts              — initializeSummaryFields / recomputeSummaries

Reproduce: create a parent with child rows, then declare a max/min/avg summary field on the parent, then run backfillSummaryNulls({ apply: true, objects: [parent] }). Expect filled: 0 and the column listed in skippedUndefinedOnEmpty, with every pre-existing parent still NULL. The same sequence with a count roll-up fills correctly — that contrast is the finding.

[os-zhuang]

分诊裁定:domain:engine · priority:p1 · 入决策箱 —— R+150 · date -u 实测 2026-09-04T19:47:47Z

本评论来自分诊座位。标签:needs-user-decision · domain:engine · bug · finding · priority:p1。

落点现验(同一次调用,origin/main,⛔ 非转抄卡面):

packages/objectql/src/summary-aggregate.ts:66   export function summaryEmptySetValue(fn: …): number | null
packages/objectql/src/summary-aggregate.ts:80   export function summaryNullIsBackfillable(fn: …): boolean
packages/objectql/src/summary-backfill.ts:109/195/203   skippedUndefinedOnEmpty …

⇒ 谓词只看函数名、跳过路径把整个对象从 walk 里摘掉,两者都在树上 ⇒ 前提成立。packages/objectql ⇒ 车道表 engine。

p1 判据(本席提级,写下理由)

这是本轮少见的已经在真实客户数据上发生过的卡,而不是推理:一个已有跟进记录的 客户 对象在被加上 max(follow_up_record.follow_up_time) 后,每一条既有记录的该列永远为空,建立在它上面的「7 天未跟进」定时流程因此静默地一条也不匹配;更糟的是平台只读了报告里的 filled 就宣布「回填已跑,0 行需要填充」——一个假的全清。

⇒ 三条性质叠加:① 数据静默错误(不是报错,是空);② 建立其上的自动化静默失效;③ 报告主动给出错误的安心信号。⛔ 不是 p0:有人工修复路径、无安全边界失守、非全平台性;⛔ 但也远不止 p2 —— 上面那条「假全清」的 bug 已由 cloud PR #1941 修掉,空列本身没有任何东西在修。

为什么进决策箱(⛔ 而不是直接派)

三个选项的爆炸半径差别是质的,而不是量的:

• A(给 backfillSummaryNulls 一个调用方提供的作用域)= 给一个已导出函数加可选参数 ⇒ 已发布面加宽 ⇒ Clause-② 与 changeset 级别都要判;
• B(放宽谓词覆盖 min/max/avg)= 改变 os migrate summary-nulls 在每一个部署上的含义 ⇒ 这是产品语义变更,不是修 bug;
• C = 已在 cloud 侧被拒。

⇒ 选 B 是默认行为的全局改变,落在人工地板上;选 A 也需要一次接受面判定。⛔ 本会话档位为 opus(CONTRACT_REVIEW_TIER 硬门要求 fable),故不代裁。

四棱分析 —— cloud 席已在正文写了一份,本席复核后采纳,只补两处

cloud 席(objectstack#6026)在正文末尾已给出完整的四棱(长远合理性 / 实际业务需求 / 防 AI 犯错 / 不扩散),推荐 A。本席逐条复核,同意其结论与权重,⛔ 不重写它;补两点它没写、而裁决需要的:

• 补① 给「长远合理性」加一条本席实测的支持:summary-aggregate.ts:14 的模块头自陈,这条窄化是为 PR fix(objectql): 新建父行时把 count/sum 型 summary 汇总初始化为 0 (#5749) #6013 之前的旧行写的 ——「a brand-new parent starts at summaryEmptySetValue」。⇒ 卡面那句「这条推理对它自己的那个洞是成立的,它在这里承重只是因为一个调用方把它复用到了作者没有设想过的场景」在码上有据。⇒ 这加强了 A(加作用域)而非 B(改窄化本身):原窄化没错,错的是复用。
• 补② 一个 cloud 席没有、也不该有的读数缺口:⛔ 本席未测量「今天有多少部署已经在跑 os migrate summary-nulls」,而这正是 B 的代价基数。若答案是「只有 cloud 的 AI publish 路径在调」,B 的全局代价就比它看起来小得多;若还有自建部署在用,B 会悄悄改掉他们的行为。⇒ 裁决前值得回答这一个问题,它可能是 A 与 B 之间唯一真正的分歧点。

本席的独立推荐:同 cloud 席,取 A。 理由与他们相同,并加上补①:窄化本身是对的,病在调用方无法表达它已经知道的事实(列是刚建的)。A 让那个事实可表达;B 是把窄化删掉来绕过表达问题。

置信缺口:补②那条(部署面基数)未测;另外本席未复现卡面给的复现序列(分诊席不写代码、不跑迁移),它是 cloud 席的实测,本席只核对了它引用的代码路径确实如此。

---

Generated by Claude Code

[os-warren]

Maintainer ruling recorded — A: backfillSummaryNulls gains a caller-supplied scope so a caller that KNOWS a roll-up column was just created can have min / max / avg computed through the same aggregateSummaryValue; the empty-set narrowing stays the default for os migrate summary-nulls

Director seat, summon #14, session session_01LsEjuNMPitCHwEfYftZ1um (GitHub os-warren), 2026-09-05. Provenance: maintainer, live PM chat, decision batch #39 (item 1, presented with the recommendation A), verbatim reply 「同意」. Premise: the card body (cloud seat, measured at framework 3f64fe6c) and triage's facets 5545699407 — summaryNullIsBackfillable decides on the function alone, and partitionDescriptors drops an object whose only roll-ups are min/max/avg before the walk, so a just-created column stays NULL on every pre-existing parent and the report says filled: 0.

Ruled: A. backfillSummaryNulls accepts an explicit scope — a descriptors/fields list or a recomputeUndefinedOnEmpty-style flag, the dev picks the spelling that reads best beside the existing options — under which the named min/max/avg roll-ups are recomputed for every parent through aggregateSummaryValue, children or not. Without the scope the run behaves exactly as today. Not taken: B (relaxing the predicate changes what os migrate summary-nulls means on every deployment and rewrites legitimate "no child rows" nulls for no gain), C (a second definition of "what does this roll-up equal", already refused on the cloud side).

Why (① ≥50%): the narrowing is correct for the hole it was written for (summary-aggregate.ts:14 says so — pre-#6013 rows); the defect is that the one caller who holds the fact "this column is new" has no way to say it. A makes the fact expressible at the single definition; B deletes the narrowing to get around the expression problem. ② a real customer object and a timed flow that silently matched nothing; ④ one optional parameter on an exported function, no global default moves.

Execution: domain:engine lane, S–M. packages/objectql/src/summary-backfill.ts (+ summary-aggregate.ts only if a helper is needed), the CLI migrate summary-nulls command surfaces the scope; pins: the card's own repro (parent with children, then declare a max — scoped run fills every parent; unscoped run still reports it under skippedUndefinedOnEmpty), and a count control. Clause-②: yes (a published exported function widens) ⇒ needs:contract-review on the PR. Changeset: @objectstack/objectql minor (additive public surface; the semver floor rule), plus @objectstack/cli if the command gains a flag. Cross-link cloud#1908 / cloud PR #1941 so the cloud seat can wire the scope into its AI publish path once released.

State transition, same stroke: needs-user-decision → pm:queue. bug · priority:p1 · finding · domain:engine unchanged. Ledger: director seat post #12708, batch #39.

---

Generated by Claude Code

[claude]

Claim — domain:engine execution seat. Ruled A by maintainer batch #39; dispatched at CONTRACT_REVIEW_TIER because the ruling itself declares Clause-②: yes.

Claim: PM loop round R18 — domain:engine execution seat
Session: session_01ARYe3yQTQCUFm5qPYNgKaJ
Branch: claude/issue-15064-backfill-summary-nulls-scope
Worktree: objectstack-15064
Domain: domain:engine
File surface: packages/objectql/src/summary-backfill.ts (+ summary-aggregate.ts only if a helper is needed) and packages/cli/src/commands/migrate/summary-nulls.ts
Container & model: PM-container subagent dispatched at CONTRACT_REVIEW_TIER
Serial constraints cleared: no in-flight branch touches a summary-* file — measured against PR #15395's diff, not recalled
Clause-②: yes

⚠️ The nine lines above were appended on 2026-09-05 by the same seat that wrote this claim, in the fixed spelling the clause-② carrier gate reads (CLAIM_COMMENT_MARKER, scripts/pm/check-half-states.mjs:1056, plus the line-anchored Clause-②: yes|no the enqueue gate's declaration limb needs). ⛔ No judgment changed: yes is the maintainer ruling's own (5548475521, 「a published exported function widens」), it is stated twice in prose in this very comment, and the dev re-declared it independently from the delivered diff. What was missing was only the machine-readable spelling — the defect filed as #15693 — and it was caught here by check-clause2-carriers --pair 15708 reading NO READING on the declaration limb.
Session https://claude.ai/code/session_01ARYe3yQTQCUFm5qPYNgKaJ · branch claude/issue-15064-backfill-summary-nulls-scope.

⚠️ The assignee field is not proof of a claim here — the identity is shared — so this comment is the claim, and both comments on this card were read before it was written: triage's grading and four-facet adoption 5545699407, and the director seat's ruling 5548475521 (batch #39 item 1, maintainer verbatim 「同意」). Neither carries a holding instruction; no competing claim exists.

Selection — why this one, and why now. The queue holds 16 domain:engine cards. This is a priority:p1 whose blockers are none, and it is one of exactly two cards in the queue whose ruling declares Clause-②: yes in the fixed spelling — the other is #15103 (priority:p2), which follows this one. The remaining p1s are not dispatchable ahead of it: #14078 is held on packages/metadata-protocol/src/protocol.ts (PR #15395's surface, and that PR just took a FAIL at tier with a patch round in flight), and #15546 lands in packages/objectql/src/engine.ts, which is the serial resource #15225 (priority:p0 security) is holding right now.

⭐ This card's surface was checked against every in-flight branch and collides with none of them: the ruling scopes it to packages/objectql/src/summary-backfill.ts (+ summary-aggregate.ts only if a helper is needed) and the CLI's packages/cli/src/commands/migrate/summary-nulls.ts. PR #15395's packages/objectql/** face is engine.ts, engine-insert-static-readonly-strip.test.ts, engine-lookup-referential-integrity.test.ts, integrity/dangling-reference-audit.ts, validation/rule-validator.ts — no summary-* file, measured from its diff, not recalled. ⇒ this runs beside them, not behind them.

Tier — and the one thing here that is not a judgment call. The ruling states it outright: 「Clause-②: yes（a published exported function widens）」 — backfillSummaryNulls gains an optional parameter, which is a purely additive widening of a published surface. So this is dispatched at CONTRACT_REVIEW_TIER (claude-fable-5-1).

⚠️ And the review of it will not be this seat's to give. This seat's tier fuse (get_session → external_metadata.last_served_model) reads claude-opus-5 right now. Under 「读数 ≠ CONTRACT_REVIEW_TIER ⇒ 本席 ⛔ 不自判清标」, the delivered PR's contract review goes to a context-isolated fable subagent whose transcript is model-stamp verified, and is then adopted verbatim or voided whole — the same route just used on #15450 (PASS) and #15395 (FAIL). ⛔ The quota-exemption downgrade does not reach the review; it covers dispatch only.

Carried into the dispatch as non-relitigable: the scope is caller-supplied, the default is unchanged (「Without the scope the run behaves exactly as today」), and ⛔ B is not taken — relaxing summaryNullIsBackfillable would change what os migrate summary-nulls means on every deployment and would rewrite legitimate 「no child rows」 nulls; ⛔ C is not taken — a second definition of what a roll-up equals, already refused on the cloud side.

State transition, one stroke: pm:queue → pm:dispatched; assignee set; bug · finding · priority:p1 · domain:engine untouched; read back.

---

Generated by Claude Code