GET /api/v1/notifications 从不解析它声明的请求 schema —— `cursor` 被静默丢弃(SDK 分页永远第一页),`limit` 默认 20 声明 vs 50 实现

[qq9340100]

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

事实(实测,origin/main@4d552af3f)

DEFAULT_NOTIFICATION_ROUTES 给 GET /api/v1/notifications 声明了 ListNotificationsRequestSchema(见 packages/spec/src/api/protocol.zod.ts:914-919):

read:   z.boolean().optional()
type:   z.string().optional()
limit:  z.number().default(20)
cursor: z.string().optional()

服务端(packages/runtime/src/domains/notifications.ts:106-112)只读三个,且不经过这个 schema:

const read  = query?.read === undefined ? undefined : String(query.read) === 'true';
const limit = query?.limit ? Number(query.limit) : undefined;
const type  = query?.type ? String(query.type) : undefined;
const result = await inbox.listInbox(userId, { read, type, limit });

于是两条声明落空:

声明	实际	后果
cursor	谁都不读	见下面实测
limit 默认 20	未传时 forward undefined,MessagingService.listInbox 自己 clamp 到 50(messaging-service.ts:289)	声明的默认值从来没有生效过

cursor 的调用方是存在的:client.notifications.list({ cursor }) 确实把它拼进 query
(packages/client/src/index.ts:3679-3688)。所以这不是「无人使用的声明」,是「有人发、服务端静默忽略」。

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

page1 = GET /api/v1/notifications?limit=5
        ids: ["YmkEfraba3S3E8GQ","N4eT1bK5MEGu-6j3","PsGcTsTjf0RqAOO-","6xLrm7tJadih3ccL","tZx2EQQ4MfeKKfWp"]
page2 = GET /api/v1/notifications?limit=5&cursor=tZx2EQQ4MfeKKfWp
        ids: ["YmkEfraba3S3E8GQ","N4eT1bK5MEGu-6j3","PsGcTsTjf0RqAOO-","6xLrm7tJadih3ccL","tZx2EQQ4MfeKKfWp"]
page2 === page1 ?  true

即:一个照着 SDK 声明分页的调用者会无限循环在第一页上,不报错,不 400。这正是 #3676
「request 声明了服务器不读的过滤器」那一类,只是这次调用方真的会发。

为什么此前没被发现

• 请求体从不与声明它的 schema 对照(#3877 的请求侧对偶):7 个 schema 定义了从未启用,而 API 目录已宣称生效 #3899 把 catalog 的 requestSchema 接到了真实入口,但只接 body;GET 的 query
  schema 不在其范围内,本路由的 body 校验(POST /read)是接上的,query 没有。

• InboxQuery(packages/spec/src/contracts/notification-service.ts:69-76)当年已经就
  同一个事实做过一次裁决,而且方向是「删」:

  Mirrors ListNotificationsRequestSchema minus cursor — no implementation paginates by
  cursor yet, and declaring a parameter nothing honours is the declared ≠ enforced gap this
  file exists to close (dispatcher 多个 domain 调用契约里没有的方法 —— #4087 的同类，只是方向相反（契约缺声明，不是调用点乱编） #4127).

  也就是说内部契约面已经删过 cursor,wire schema 面没跟上。

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

A. 删声明(#3676 方向) —— 从 ListNotificationsRequestSchema 摘掉 cursor,把 limit
的默认值改成实现真正用的 50(或去掉 default,让「未传 = 由服务端决定窗口」成为显式契约),
同时摘掉 client.notifications.list 的 cursor 参数。

• 业务需求轴:今天 GET /notifications 的实测消费者只有 SDK。objectui 的通知铃不走这条路由——
  它直接 dataSource.find('sys_inbox_message', …) 并自己 join 回执、自己算未读
  (objectui/packages/app-shell/src/layout/AppHeader.tsx:354/391/496),只用本族的两条
  mark-read POST。所以「分页」目前没有被任何真实界面拉动。
• 长远合理性轴:与 dispatcher 多个 domain 调用契约里没有的方法 —— #4087 的同类，只是方向相反（契约缺声明，不是调用点乱编） #4127 已经在 InboxQuery 上做过的裁决同向,消除两个契约面的分歧。
• 防 AI 轴:强。一个 AI 写的集成看到 cursor 会照着写分页循环,拿到的是无限的第一页——
  声明比没有声明更危险,正是 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 不排期 Stage C 的同一条理由。
• 代价:摘 wire schema 的键是 spec 面的破坏性变更(api-surface 重生成 / ADR-0087 路线 / changeset),
  且是 spec 车道。

B. 改实现(#3847 方向) —— 真的实现 cursor 分页(listInbox 按 created_at + id 游标取下一页,
响应回填 cursor),并把 query 接到 ListNotificationsRequestSchema 上(默认值随之生效)。

• 业务需求轴:目前没有实测拉动。收件箱的深翻页在 objectui 里走的是 setup app 的
  sys_inbox_message 列表视图(InboxPopover.tsx:129),已有自己的分页。
• 长远合理性轴:通知列表迟早需要分页,但「迟早」不是本轮的证据。
• 代价:listInbox 的读路径要改(受 receipt join 与 in-memory read 过滤影响,游标语义要想清楚),
  是真实设计工作,不是机械替换。

建议:A(删声明 + 把 limit 默认对齐实现),理由是三轴里业务需求轴给不出拉动,而
#4127 已在同一事实上裁过同一方向;创业期能力扩张从紧,分页词汇可以在真的有业务拉动时
连同实现一起回来。但这是公开契约变更,按纪律不猜——请维护者定。

关联

• 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 正文
• 同一族的响应侧另有一单(unreadCount 语义 + 响应 cursor)
• 先例: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)、请求体从不与声明它的 schema 对照(#3877 的请求侧对偶):7 个 schema 定义了从未启用,而 API 目录已宣称生效 #3899(只接 body schema)

[claude]

Triage: needs-user-decision + domain:spec — a public wire-contract call, correctly escalated

Verdict. This one genuinely belongs in the maintainer's inbox, and the reason is narrower than "there are two options." Both routes change something the outside world can see: (A) removes a key from a published request schema — a breaking change to ListNotificationsRequestSchema plus the SDK parameter that feeds it — and (B) ships a pagination capability that nothing currently pulls for. Triage can pick between options when a standing ruling already answers one of them (that is what happened on #6369 an hour ago). Here no standing ruling reaches either side: the startup-phase focus principle argues against (B), but it does not authorise a breaking removal from a wire schema, which is its own decision with its own version window.

Routing: domain:spec, not spec-surface. Anchored to the landing site of the recommended route (A): packages/spec/src/api/protocol.zod.ts:914–919, removing cursor and re-basing limit's default. That changes the acceptance surface — a request body carrying cursor is judged differently after than before — which is the split's red line: any acceptance/rejection change is domain:spec regardless of size. If the maintainer picks (B) instead, the work moves to packages/runtime/src/domains/notifications.ts + service-messaging and the card should be re-routed then (domain:cli for the runtime half, domain:services for the read path); ⛔ the lane must not re-label it itself — flag it back here.

Premise re-verified against origin/main:

• packages/spec/src/api/protocol.zod.ts:925 still declares cursor: z.string().optional().describe('Next page cursor').
• packages/runtime/src/domains/notifications.ts still reads only read / limit / type, and its last commit is the repo-wide 4dd9cbd — nobody is fixing this in flight.

What makes the report unusually decidable — recorded so the decision does not have to re-derive it: the consumer axis is measured, not assumed (GET /api/v1/notifications has exactly one real caller, the SDK; objectui's bell goes around the route entirely via dataSource.find('sys_inbox_message', …)), and #4127 already ruled the same way on the same fact one contract surface over — InboxQuery dropped cursor with the reasoning quoted verbatim in the body. So (A) is not a new judgement, it is the wire schema catching up to a judgement already made internally. That is the strongest argument in the card and the one worth putting in front of the maintainer first.

Coupling — must be decided jointly with #6363. The response-side cursor on ListNotificationsResponseSchema is the other half of the same unimplemented capability. Deciding these two independently produces a new inconsistency in either direction (a request cursor with no response cursor, or vice versa). No Blocked-by: line was added, because needs-user-decision already bars dispatch on both and a blocker would misrepresent an ordering constraint as a dependency; the coupling is stated here and on #6363 instead.

Dedup (issues + PRs, three repos): no duplicate. #3676 / #3847 / #4127 / #3899 are precedent and context, not the same card; #6363 is the deliberate response-side sibling.

⛔ 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. Remove cursor from ListNotificationsRequestSchema and from the response schema (ruled together with #6363 — one capability's two halves, same direction, never half-deleted), drop the cursor parameter from client.notifications.list, and align the declared limit with the implementation: either declare the real server default (50, clamp documented) or drop the default and describe it as server-decided — implementer's choice, but the declared number must stop being fiction.

Rationale: the only measured consumer is the SDK; the objectui bell bypasses this route entirely; #4127 already ruled the same direction on InboxQuery — the wire schema simply never followed; a declared-but-ignored cursor makes an AI-written integration loop on page one forever, so the declaration is strictly worse than absence. Pagination vocabulary returns together with an implementation when something real pulls for it.

Scope: spec wire-schema change (api-surface regen, changeset, ADR-0087 bookkeeping as applicable) plus the client SDK parameter removal. Contract-first: spec half lands first; triage may split the client half with a Blocked-by line. Sequence with #6363.

---

Generated by Claude Code