[Decision] Should a DECLARED 5xx on a polled route (501 NOT_IMPLEMENTED for an uninstalled optional service) log one error line per request under the "5xx never stays quiet" rule?

[hotlong]

Blocked-by: —

背景

#14310 的裁决是「4xx may stay quiet; 5xx never」，PR #14654 按字面实现：每个 5xx 信封在唯一漏斗 logServerFault 记一条 error 级日志。dev 实测到一个可达后果：没有安装 service-messaging 的部署上，GET /api/v1/notifications 应答声明式 501 NOT_IMPLEMENTED，而 Studio 会轮询它 —— 于是每次轮询都打一行 error。这条日志通道是本卡刚建立的，让它逐请求叫狼可能把它训练成运维会忽略的噪音。

选项

• A（已发货）：字面执行，每个 5xx 都记。零发明，与裁决一致；代价是声明式 501/503 在轮询路由上的逐请求噪音。
• B：排除「声明式能力缺席」（NOT_IMPLEMENTED / SERVICE_UNAVAILABLE 回答的是配置事实而非故障），其余一律响亮。packages/rest 已有先例：isExpectedRouteError 把 502/503 当正常生命周期结果。需要一个两扇门共读的「声明式缺席」定义。
• C：声明式缺席按 route 每进程只记一次（去重），保留信号、压掉体量。

四维分析

• 实际业务需求：噪音可达但未在真实部署上量到（dev 只证明了路径存在）；今天没有用户被它伤到。有拉动的是 A 已经修掉的 P1（500 零日志）。
• 项目长远合理性（≥50%）：B 是原则上的终态 —— 「这个部署没装可选服务」是配置事实不是故障，逐轮询叫狼的通道最终退化回沉默；但 B 需要一个两扇门（REST / 派发器）共读的谓词，在修复中途发明它正是本仓反复付费修的「逐门分叉」。
• 防 AI 犯错：中性；若做 B，谓词必须住在 @objectstack/types 与 logServerFault 同家，⛔ 不在任一门里各写一份。
• 创业阶段不扩散：无拉动不新增第二个谓词；A 先落地，B/C 等到噪音被观测到再做。

推荐

维持 A 落地（PR #14654），本卡挂 needs-user-decision 等维护者裁 B 或 C 的时机；若裁 B，作为独立卡派发，谓词落在 types 包与漏斗同家并带两扇门的一致性 pin。

Source: os-dev report on #14310 (open question 1).

Generated by Claude Code

[huangyiirene]

Triage — sweep repair, two rounds overdue. Added the missing domain:cli and priority:p3; needs-user-decision kept as filed. Applied and read back first.

⛔ Lane repair only — ⛔ no recommendation on the question itself. "Should a declared 5xx on a polled route log per request" is a logging-policy call under a standing rule, and rules about what the platform must never stay quiet about are the maintainer's to bend.

Routing

domain:cli. The "declared 5xx" concept and its handling live in packages/rest/src/error-response.ts — :1717 ("[#5437] A declared 5xx never ships its own message text") and :1944 ("a declared 5xx never reaches…") — and packages/rest is domain:cli by the lane table. Whatever is ruled, that file is where the answer gets spelled.

Why p3

Nothing is broken and no request fails; the cost is log volume on a polled route, which is a real operational irritant but not a defect. The decision is worth making because the standing rule and the observed behaviour disagree in a way that will keep being rediscovered — but nothing is waiting on it.

One fact for whoever rules it

⭐ The card's framing turns on 501 NOT_IMPLEMENTED being declared — i.e. an answer the platform chose, not a fault it suffered. error-response.ts already draws exactly that line for a neighbouring purpose: a declared 5xx is deliberately treated differently from an undeclared one (it never ships its own message text). So the distinction the ruling needs is already a concept in the code, with a precedent for treating the two asymmetrically.

That does not answer the question — "declared, therefore quiet" and "5xx, therefore loud" are both defensible — but it means the answer can be expressed in vocabulary that already exists, rather than needing a new category. ⛔ Worth knowing before anyone proposes a third classification.

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling recorded — B + C: a declared capability absence is reported once per route per process at warn; every other 5xx stays loud per request (2026-09-03)

Provenance. Ruled by the maintainer (pm@objectstack.ai) in the director seat's live session (session_01ShyhexkB2d1AeRZ85tgAAe), decision batch #23, 2026-09-03 after 16:05Z. Verbatim reply: 「同意」. The batch was presented with this card's recommendation as B + C (fallback A: leave the literal rule until a real deployment measures the noise), so 「同意」 adopts B + C. Ledger: objectstack#12708, batch #23 ledger comment.

What was ruled. The #14310 rule ("4xx may stay quiet; 5xx never") stands for faults. A declared capability absence — a 5xx the platform chose because the deployment did not install an optional service (the NOT_IMPLEMENTED / SERVICE_UNAVAILABLE family answering a configuration fact, e.g. GET /api/v1/notifications without service-messaging) — is a configuration fact, not a fault: it is reported once per route per process, at warn, naming the missing service, and then stays quiet for that route. Everything else that reaches logServerFault keeps the shipped per-request error line.

Constraints that are part of the ruling.

• The predicate ("is this envelope a declared capability absence") lives in one place, beside logServerFault in @objectstack/types, reusing the error-response.ts "declared 5xx" vocabulary that already exists (:1717, :1944). ⛔ Not spelled once per door: the REST door and the dispatcher read the same predicate, and a pin asserts both doors agree on a fixture envelope.
• The dedupe key is (route, process); a restart reports again. ⛔ No global "first N" throttle — that is the shape that hides the second route.
• The wire answer does not change: this is logging only. Clause-②: no (re-read on the final diff; if any response byte moves, stop and report).

Execution. domain:cli lane (packages/rest + the shared funnel in @objectstack/types), S/M. Pins: a declared 501 on a polled route logs exactly once across N requests in one process, at warn; an undeclared 500 on the same route logs N times at error; the two doors agree. Changeset: patch on the packages whose logging changes. Fixes #14656.

State. needs-user-decision → pm:queue in the same stroke; domain:cli, priority:p3 kept; unassigned.

---

Generated by Claude Code