`sys_comment.visibility` and `sys_comment.reply_count` are declared but nothing anywhere reads or maintains them (ADR-0049 enforce-or-remove)

[os-zhuang]

Found while implementing #4630 (record-level authorization for sys_comment). Filed unassigned, out of that PR's scope.

What

sys_comment (packages/plugins/plugin-audit/src/objects/sys-comment.object.ts) declares two fields that no code path in this repo — or in objectui — ever reads or writes:

field	declaration	reality
visibility	Field.select(['public','internal','private'], { defaultValue: 'public' })	Never read. No gate consults it: not enforceFeedsCapability, not the record-level gates added in #4630, not the REST layer, not objectui's RecordDetailView discussion panel. A comment marked private is exactly as visible as a public one.
reply_count	Field.number({ defaultValue: 0, readonly: true })	Never incremented. Nested replies are modelled by the parent_id lookup; nothing counts them on either side. Every row's reply_count is 0 forever, and the field is readonly so an author cannot even set it by hand.

$ grep -rn "reply_count" --include=*.ts packages/    # only the schema + its generated translations
$ grep -rn "visibility" packages/plugins/plugin-audit/src/   # only the schema
$ grep -rn "reply_count" --include=*.tsx ../objectui   # nothing

Why it matters

This is the exact shape of the Prime Directive #10 trap: visibility reads as an access-control lever on a collaboration object. An app author (or an AI authoring metadata) who sets visibility: 'private' on a sensitive comment will reasonably believe it is hidden from other users who can read the record. It is not. Declaring an unenforced security-looking key is worse than not declaring it.

reply_count is milder but the same class: a UI that binds a "N replies" badge to it renders 0 forever.

Precedent — this exact pair was already resolved once, next door

sys_attachment carried share_type and visibility with zero runtime consumers, and #2755 removed both rather than implementing them, on the grounds that attachment access derives from the parent record and there is no replacement key (see packages/services/service-storage/CHANGELOG.md, the f531a26 entry: "Both fields were modeled in v1 with zero runtime consumers (ADR-0049 parsed-but-unenforced). There is no replacement key: attachment access is derived from the parent record by the hooks above.").

After #4630 that argument transfers verbatim to sys_comment.visibility: a comment's access now derives from the record its thread_id names, so a per-row visibility enum has no coherent meaning layered on top of it — unless someone deliberately designs one (e.g. internal = hidden from external/portal principals, which would need to be defined against ADR-0090 D11's externalSharingModel, not invented ad hoc).

Decision needed (maintainer)

For each field, enforce or remove:

• visibility — (a) REMOVE, following the sys_attachment precedent (the spec-property-retirement playbook applies: tombstone + changeset with the FROM/TO, and note these are object fields, not spec keys, so the kit is lighter); or (b) ENFORCE, which first requires deciding what internal and private mean relative to OWD/sharing and to external principals. Recommendation: (a) remove — an undesigned enum on a security surface is a liability, and sys_comment has no record-level authorization: any org member reads and writes comments on records they cannot see #4630's parent-derived rule is the coherent answer to "who sees this comment".
• reply_count — (a) REMOVE, and let consumers count parent_id children; or (b) MAINTAIN it with afterInsert/afterDelete hooks on sys_comment (a roll-up, cheap and self-contained). Recommendation: (b) maintain if any UI wants the badge, otherwise (a); this one is a genuine convenience denormalization, not a security claim.

Note that removing either field is a stored-data question as well as a schema one — existing rows carry the columns, and the sys_attachment removal chose to leave the DB columns as unmanaged leftovers with no migration.

[os-zhuang]

认领本单开始实施。

• session: session_0176qgxgCXTJCUv4YFLtusP9
• 分支: claude/issue-4756-sys-comment-dead-fields

维护者已裁决:两键都移除(visibility 与 reply_count),不走 rollup hook 路线。

• visibility → 移除。它只有在外部主体(portal)存在时才有语义,而外部主体要等 ADR-0090 D11 externalSharingModel 落地;sys_comment has no record-level authorization: any org member reads and writes comments on records they cannot see #4630 之后「谁能看评论 = 谁能看 thread_id 指向的记录」是唯一连贯规则。这是 security 观感的假闸门(标 private 的评论对所有人可见),按 [attachments] v1 follow-ups: sys_file orphan lifecycle + non-admin permission matrix dogfood #2755 在 sys_attachment 上的先例逐字迁移移除。
• reply_count → 移除,明确不选「补 rollup hook」。本仓同日已系统性发现谓词式/批量写 hook 缺口一族(bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 / 审批记录锁 bindApprovalLockHook 对谓词式(multi)更新完全失效:if (!id) return 把「没解析到行」当成「允许」 #4778 / 共享规则 hook 对谓词式(multi)写入不重算:if (!id) return 让 sys_record_share 授权在批量更新后变陈旧 #4779),靠 hook 维护的计数器正落在这类缺口上,批量删回复后计数不减 —— 会漂移的计数比没有计数更糟。徽章需求改为读时按 parent_id 聚合。

存量 DB 列按 #2755 先例留作 unmanaged leftover,不做数据迁移(changeset 中写明)。

---

Generated by Claude Code

[os-zhuang]

实施完成,draft PR: #4849(分支 claude/issue-4756-sys-comment-dead-fields,session session_0176qgxgCXTJCUv4YFLtusP9)。

做了什么:按裁决把 sys_comment.visibility 与 sys_comment.reply_count 一起移除;reply_count 明确不补 rollup hook(#4770 / #4778 / #4779 的批量 hook 缺口会让计数漂移,漂移的计数比没有更糟)。四份 plugin-audit translation bundle 用文档记录的 extractor 重生(merge 模式,手写译文全保留);存量 DB 列按 #2755 留作 unmanaged leftover,不迁移。

消费方复核(裸名扫描,三仓):没有任何真 reader。objectui 里只有 camelCase 的 replyCount,是 FeedItem 的前端本地状态(回复时自己 +1 / replies.length),它从 sys_comment 拉行的 map 只读 id / author_name / author_avatar_url / body / created_at / updated_at / parent_id / reactions,create 负载也不发这两个字段;cloud 零命中。

墓碑形态:本仓没有 object field 级的 retiredKey() 设施(那是 spec 属性的),所以墓碑由 pin 测试 + 源码处方注释承担 —— sys-comment-retired-fields.test.ts,任一字段被复活即红,失败信息直接带处方。sabotage 实跑已贴在 PR 里(2 failed / 3 passed,恢复后 5 passed)。

验证读数:全仓 typecheck 122 successful;全仓 build 71 successful;plugin-audit 94 passed;check:i18n 9 包 in sync;check:i18n-coverage none new;受影响消费方 rest 573 / metadata-protocol 260 / platform-objects 266 全绿。

另在 docs/adr/0052 §5 的历史对比表下加了一条 Note (#4756) —— 决策不动,只说明该行的字段清单是决策当时的状态、reply_count 已退役,免得后来的读者从历史表里读出一个不存在的字段。

保持 draft,不 auto-merge、不自行 ready。

---

Generated by Claude Code

[os-zhuang]

✅ 验收通过 → PR #4849 已转正 + auto-merge

对照 GitHub 实际 diff(a23dabeb vs c4ab50b6)复核,全部合格:

• 两个字段确已从 sys-comment.object.ts 消失 —— 实测该文件仍有 5 处 visibility / reply_count 命中,逐条核过全部是处方注释(docblock 里的退役说明 + :145 那句「No visibility field: who can see a comment is decided by the record …」),零字段声明。
• 形态判定正确:本仓没有 object field 级墓碑设施(retiredKey() / UNKNOWN_KEY_GUIDANCE 都是 spec 属性的),liveness ledger 也不登记 sys_comment 字段 —— 与 [attachments] v1 follow-ups: sys_file orphan lifecycle + non-admin permission matrix dogfood #2755 当时一致。因此墓碑由 pin 测试 + 源码处方注释承担,且 sabotage 实跑确认失败信息里直接带处方(两条断言分别点名 sys_comment has no record-level authorization: any org member reads and writes comments on records they cannot see #4630 与 bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770/审批记录锁 bindApprovalLockHook 对谓词式(multi)更新完全失效:if (!id) return 把「没解析到行」当成「允许」 #4778/共享规则 hook 对谓词式(multi)写入不重算:if (!id) return 让 sys_record_share 授权在批量更新后变陈旧 #4779)。这比一句干巴巴的 not.toContain 有用得多。
• reply_count 不做 rollup 的论证站得住:靠 hook 维护的计数器正落在同日发现的批量 hook 缺口一族上,批量删回复后计数不减 —— 会漂移的计数比没有计数更糟,因为 UI 和 AI 都会信任它。
• 存量列处置的诚实分层是本 PR 额外的价值:读路径(filter/sort/select/expand)因门禁从 object schema 解析字段名,任何部署上都是 400 INVALID_FIELD;写路径只在新库上响亮,老库遗留列仍接受写入但无人读。没有把「删了就干净了」说成事实。
• [attachments] v1 follow-ups: sys_file orphan lifecycle + non-admin permission matrix dogfood #2755 先例逐字迁移成立(attachment access derived from parent record → comment access derived from thread_id record),存量列同样留作 unmanaged leftover 不迁移。
• ADR-0052 只加 > Note (#4756) 不改决策本身(Prime Directive [WIP] Add Chinese version of the documentation #13),处置正确。
• translations 用配置 docstring 记录的命令重生(merge 模式,四份各 −11 行,手写译文保留),未手改生成物。
• content/docs/releases/ 零触碰。

入队说明:本 PR 不触及 packages/spec(实测 0 文件),四张 ratchet 无改动,因此脱离 #4831 / #4841 / #4846 共用 spec-changes.json 的那条串行链,可独立入队,已直接放行。

注:CI 首跑若在 Test Core 的 DTS 步骤失败,那是已立案的 #4845(spec DTS 贴 runner 内存天花板,三例首跑全中、重跑可过),与本 PR 无关 —— 本 PR 甚至不改 spec。

---

Generated by Claude Code