docs(catalog): name what the retired setting projection actually carries - #5053
Conversation
Signed-off-by: NIU-123370 <191000457+NIU-123370@users.noreply.github.com>
huangruiteng
left a comment
There was a problem hiding this comment.
English verdict: APPROVE — the catalog row now names the fields the retained-setting projection actually exposes; no blocker found on this exact head.
动机
合并后的 IP-037 索引行说投影会携带“reason”,但实际的保留配置摘要没有 reason 字段。这个错位会让读文档的维护者或集成方去寻找不存在的数据,并可能把拒绝消息或迁移通知中的原因码误当成配置投影的一部分。本 PR 只修正该索引行的字段描述,属于能独立交付的文档纠偏,不声称改变运行时行为。
改动思路
沿用现有 catalog 的一行一模式结构,只替换该行的目标表述,不引入新协议或第二份迁移规则。核对了 local_authority_shadow_summary 的返回值:合法保留项有 status: retired 和 replacement: coordination_runtime_shadow,格式不合法时 status 为 invalid;拒绝启用时的原因只在错误文本中,迁移通知另有 reason_code。这样能把“显示的状态”和“拒绝原因”分开,避免索引说明越权定义字段。
具体改动
关键内容讲解
唯一改动是 docs/concepts/interaction-pattern-catalog.md 的 IP-037 索引行:原句“carry its reason in the projection”改为“carry its retired status and replacement in the projection”。它仍要求在写入前拒绝已退役设置的激活、保留旧条目可见且只读,并明确清除旧设置不等于启用或 bootstrap 替代功能。索引行的模式编号、所属类别和详情节均未变;详情节提到的拒绝信息、迁移 reason_code、reward-memory retirement_reason 各自指向不同契约,不能把其中一个字段挪到摘要。该精度提升也不影响 catalog smoke 所守护的一号一族和索引/标题配对。
对主干的风险
风险低且局限于公开文档的一处措辞:不会改变配置解析、持久化、读回、CLI 或默认开关。可能的边界是 status 在损坏的保留配置中会是 invalid 而非 retired;此句描述的是有效退役项,详情与实现并未把异常态隐藏,因此不构成阻断。如果将来继续精修,可以写成“status (retired/invalid) and replacement”,但不应为此扩大本 PR。独立在 exact head 运行 catalog smoke 通过,git diff --check 通过;未查询远端 CI,按本次 review packet 的本地验证策略处理。
我的整体评价
APPROVE。它消除了一个真实的文档/实现歧义,并保持文档层边界:长期看减少集成方依据不存在字段实现逻辑的风险,阅读体验更准确;无新增运行时维护负担。当前 head 为 fe9b2f54b4a54f0bbc7919bf9cd6e31b5be97674,此结论只适用于该 head,不代表代替合并就绪或授权合并。
Goal And Delivered Outcome
a270a55bdand merged asbea36ae46with one non-blocking wording finding: the IP-037 index row saysthe projection must "carry its reason", but the retired-setting summary
actually carries
status: "retired"(orinvalidwhen malformed) plusreplacement(loopx/control_plane/coordination/runtime_shadow.py:53-63).The standalone reason code exists only in the rejection message (
:72) and inthe migration row (
loopx/state_migration.py:236-241). As written, that cellinvites a reader to look for a
reasonfield the summary never had.row overstates what the projection carries; after, it names the two things
that are actually there — retired status and replacement. Proven by the
manualrow below, which re-reads each cited source.([Task]: GH-C37 add IP-037 a retired setting is not an absent setting #5042, docs(catalog): add IP-037 a retired setting is not an absent setting #5043). Base
main.Scope And Continuation
no change: its three "reason" mentions point at the rejection message, the
migration
reason_code, and the reward-memoryretirement_reason, and allthree fields exist as cited.
Validation
fe9b2f54bstaticpassedpython3 examples/interaction-pattern-catalog-smoke.py→interaction-pattern-catalog-smoke: ok.staticpassedloopx check --scan-path docs/concepts/interaction-pattern-catalog.md→public boundary scan clean: 1 files,errors=0. Its two warnings are this scratch worktree having no local registry, not a finding about the diff.manualpassedstatus/enabled/configured/replacementand noreason; the reason code appears in the rejection text and in the migration notice. The corrected wording matches all three.regression_paritypassedgit diff --checkclean.cover, so no
unit/integration/real_backendrow applies. Interpreter note:the checks ran with repository-relative commands against a locally installed
Python 3.12 environment (an editable install from another worktree on this
machine), not
uv sync --extra test.Frontend / Visual Evidence
Type of Change
LoopX Area
Technical Direction
incubator — wording accuracy on the GH-C37 catalog entry. No roadmap S/G/R id
claimed.
Shared-authority RFC fixture impact
routing or projection code is touched.
Boundary Checklist
.loopx/,.codex/goals/, and liveACTIVE_GOAL_STATE.md).none.Signed-off-bytrailer (git commit -s).