notification 响应侧:`unreadCount` 声明「总未读数」实测只数 limit 窗口内;响应 `cursor` 从无 producer 发出

[qq9340100]

发现于 #5792(Stage A / #3877 notification 族响应体一致性测试)的前置测量。不在该 PR 修——两条都是
#3676(删声明)与 #3847(改实现)方向相反的判断题,按纪律另立单。

这是 #6361 的响应侧对照单(那单是请求侧)。两条都活在双断言看不见的盲区里,值得单说:
schema.parse() 判值、键集 ⊆ 声明键集判键——两条都绿,因为 unreadCount 无论对错都是个
number,而 cursor 是 optional 所以「从不发出」也是合法的。这一点本身是给 #3877 Stage D
棘轮设计的输入。

事实 1:unreadCount 的声明语义与交付语义不一致

声明(packages/spec/src/api/protocol.zod.ts:924):

unreadCount: z.number().describe('Total number of unread notifications')

.describe() 不是注释——它进 content/docs/references/,是发布出去的 API 文档原文。

实现(packages/services/service-messaging/src/messaging-service.ts:284-333)自己的注释就写着相反的话:

unreadCount is computed over the fetched window (bounded by limit, like the Console bell's poll).

计数发生在 rows.map(...) 里,而 rows 已经被 limit 截断过(默认 clamp 到 50,上限 200)。

实测(真实 boot:sqlite-wasm + ObjectQL + service-messaging + hono + dispatcher,60 条未读):

无 limit 查询   →  rows: 50   unreadCount: 50      ← 真值是 60
?limit=10      →  rows: 10   unreadCount: 10      ← 真值是 60

也就是说:一个未读超过窗口的用户,拿到的角标永远等于窗口大小,而契约说这是总数。

事实 2:响应侧 cursor 没有任何 producer 发出

声明(ListNotificationsResponseSchema,protocol.zod.ts:925):

cursor: z.string().optional().describe('Next page cursor')

实测:GET /api/v1/notifications?limit=5 的响应体里 cursor 键不存在
(Object.prototype.hasOwnProperty(body.data, 'cursor') === false),listInbox 的返回类型
(InboxListResult,packages/spec/src/contracts/notification-service.ts:100-104)也只有
{ notifications, unreadCount }。与 #6361 的请求侧 cursor 是同一个未实现的分页能力的两半。

谁在消费(三轴的「业务需求」证据,实读得来)

GET /api/v1/notifications 的实测消费者只有 SDK(client.notifications.list)。
objectui 的通知铃不调这条路由:它 dataSource.find('sys_inbox_message', …),自己 join
sys_notification_receipt,自己 reduce 出未读数
(objectui/packages/app-shell/src/layout/AppHeader.tsx:354 / :391 / :496),
只用本族的两条 mark-read POST。所以今天没有界面被这个错值伤到——但它是发布出去的契约。

判断题(不猜,列证据供裁决)

关于 unreadCount

A. 改实现(#3847 方向) —— 真的数总未读:窗口外的未读也要算进去。

• 长远合理性轴:角标就该是总数,这是「通知铃」这个 UI 元件的通用语义;声明本来就是对的。
• 代价:读路径要多一次计数。读态存在另一个对象(sys_notification_receipt,ADR-0030),
  所以「未读总数」不是一次 count(sys_inbox_message) 能答的——要么反连接,要么维护计数。
  这是真实设计工作。
• 防 AI 轴:强。声明与交付一致,消费者不需要知道实现细节。

B. 改声明(#3676 方向) —— 把 .describe() 改成「所返回窗口内的未读数」,并按惯例
提供「50+」式的上限表达。

• 业务需求轴:今天没有实测消费者被伤到(见上),而按窗口计数正是 Console bell 轮询的实际用法。
• 长远合理性轴:弱一些——把一个可以正确交付的语义降级为窗口语义,是让契约迁就实现。
• 注意:改 .describe() 会动 content/docs/references/(生成物),按 AGENTS.md 走
  pnpm --filter @objectstack/spec gen:schema && gen:docs。

建议:A(改实现),理由是三轴里长远合理性与防 AI 都指向同一边,而「没人消费」在这里
不是削减能力的理由——unreadCount 是本路由存在的主要产出之一(另一半 notifications[] 本就
可以从 sys_inbox_message 直接读到,objectui 正是这么做的),把它降级为窗口计数等于让这条路由
只剩一个更差的数据 API。但代价落在读路径设计上,请维护者定。

关于响应 cursor

与 #6361 的请求侧 cursor 必须同向裁决——分页是一个能力的两半,只删一半或只实现一半都是新的不一致。
建议随 #6361 一并决定。

关联

• Part of Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877(Stage A / notification 族),测量记录见 conformance(Stage A / #3877):notification 族响应体一致性测试 —— 双断言口径,预期违规率按 2/2 双向查 #5792 的 PR 正文
• 请求侧对照单:GET /api/v1/notifications 从不解析它声明的请求 schema —— cursor 被静默丢弃(SDK 分页永远第一页),limit 默认 20 声明 vs 50 实现 #6361(cursor 不被读取 / limit 默认 20 vs 50)
• 先例:GetTranslationsRequest declares namespace / keys that no server reads — declared ≠ enforced #3676(删声明)、GetFieldLabelsResponse declares rich label entries; both surfaces emit bare strings #3847(改实现)、dispatcher 多个 domain 调用契约里没有的方法 —— #4087 的同类，只是方向相反（契约缺声明，不是调用点乱编） #4127(InboxQuery 已删 cursor)
• 给 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 Stage D 的输入:本族双断言 3/3 全绿,而上面两条真实不一致两条断言都看不见
  ——棘轮若只有「值 + 键」两问,这一类「声明了但从不交付 / 交付了但语义不同」会整类漏掉

[claude]

Triage: needs-user-decision + domain:services — two items, one of them jointly bound to #6361

Verdict. Escalated. The card carries two distinct facts and they do not have the same shape, so the decision should be taken as two:

Item 1 — unreadCount semantics. The declared meaning ("Total number of unread notifications", protocol.zod.ts:924, re-verified present on origin/main) and the delivered meaning (count over the limit-bounded window) disagree, and the disagreement is user-visible the moment a user's unread count exceeds the window: the badge saturates at the window size forever. Route (A) fixes the implementation, route (B) demotes the contract. This needs a ruling because the two routes have genuinely different costs and the cheap one is the one that makes the product worse — exactly the shape where triage should not quietly pick.

Item 2 — response-side cursor. Declared, never emitted by any producer; InboxListResult (packages/spec/src/contracts/notification-service.ts:100–104) does not even carry the field. This is one half of a single capability whose other half is #6361's request-side cursor. ⚠️ Rule it in the same direction as #6361, in the same sitting — deciding them apart produces a fresh inconsistency whichever way each lands.

Routing: domain:services, anchored to the recommended route. (A) lands in packages/services/service-messaging/src/messaging-service.ts:284–333 (the count currently computed inside rows.map(...) over an already-truncated set) plus whatever the true-total read costs against sys_notification_receipt (ADR-0030) ⇒ domain:services. If the maintainer picks (B) instead, the work becomes a .describe() text change with no acceptance-surface movement ⇒ domain:spec-surface, and it should be re-routed here rather than by the lane. Item 2 under (A)-style implementation also lands in service-messaging; under removal it lands in packages/spec ⇒ domain:spec, tracking #6361.

Premise re-verified against origin/main: both declarations present at protocol.zod.ts:924 / :925; messaging-service.ts untouched since the repo-wide 4dd9cbd. No in-flight collision.

Note on the measurement, kept because it is the load-bearing part. The "no interface is hurt today" reading is measured, not assumed — objectui's bell computes its own unread count from sys_inbox_message joined to receipts (AppHeader.tsx:354/391/496) and never calls this route. Worth keeping visible in the decision: it argues for (B) on the business axis and the card argues against letting it, since unreadCount is most of this route's reason to exist. Both halves of that tension are in the body and neither was resolved here.

Also carried forward as the card asks: this pair is an input to #3877 Stage D — both inconsistencies are invisible to the value+keyset double assertion (a wrong number is still a number; an optional key that is never emitted is still legal). A ratchet built on those two questions alone misses this entire class.

Dedup (issues + PRs, three repos): no duplicate; #6361 is the deliberate request-side sibling and is cross-linked from there.

⛔ Do not dispatch. ⛔ Do not auto-answer.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — 2026-08-07. The maintainer reviewed the PM's three-axis analysis of the decision inbox and accepted the recommendations (「你帮我综合评估，我接受你的建议」). Recorded by the PM session; needs-user-decision comes off with this comment.

Decision: Option A for unreadCount — implement the declared semantics: count total unread, not the fetched window. Response cursor: removed together with #6361 (same direction; a pagination capability is never half-deleted).

Rationale: unreadCount is this route's primary output — the list half is directly readable from sys_inbox_message, as objectui itself proves — and a badge that can never exceed the window size is a lie in published contract docs (.describe() ships into references). Long-term and AI-safety axes both point to making the declaration true rather than documenting the lie.

Implementation notes: read state lives on sys_notification_receipt (ADR-0030), so total-unread needs a reverse join or a maintained counter — real, bounded design work; keep the existing window behavior for the list itself. Sanctioned fallback: if the v17 window gets tight, re-describing as window semantics ("50+" cap) may ship for the release with this card kept open for A — but that swap requires explicit maintainer sign-off at release time, never a silent substitution.

Also stands as recorded input to #3877 Stage D: both defects here were invisible to the value + key double assertion.

---

Generated by Claude Code

[hotlong]

认领:PM 循环第 9 轮(维护者 2026-08-07 17:00Z 已裁 Option A)
会话:session_015a5qkLzpGXhLL2F5gvJ7dD
分支:claude/issue-6363-unread-count-true-total
Worktree:objectstack-6363
域:domain:services
文件面:packages/services/service-messaging/src/messaging-service.ts(:284-333 的 unreadCount 计数,现落在已被 limit 截断的 rows.map(...) 里)+ 其测试 + changeset

范围 = 裁决的 unreadCount 半边:实现声明语义(数总未读,不是窗口内),列表本身保持既有窗口行为;读态在 sys_notification_receipt(ADR-0030)⇒ 需反连接或维护计数,属真实设计工作。⛔ cursor 半边不在本单——裁决明确「分页能力不半删」,随 #6361 同向处理,其移除落 packages/spec 归 spec 座位。⛔ 亦不改 .describe()(Option A 是让声明成真,不是改声明);维护者授权的「窗口语义 + 50+ 上限」回退仅限发布窗口吃紧时、且须发布时显式签字,不是本单可自选的路线。

---

Generated by Claude Code